User-mode Linux/Guide

Obtaining User-Mode Linux
As the user-mode Linux website states, user-mode Linux allows a user to "run Linux inside itself". Specifically, user-mode Linux provides a virtual machine on which a user can "[r]un buggy software, experiment with new Linux kernels or distributions, and poke around in the internals of Linux, all without risking your main Linux setup." Experimental changes to Gentoo core packages such as or  have the potential to break the system and render it unbootable; with user-mode Linux we can test these changes without having to worry about breaking the live system.

Most 2.6 kernels have UML support. Although you can use your current kernel sources, it might be wiser to keep the UML kernel tree(s) separate. After all, you'll be building a new kernel with a different configuration and you might want to have heterogeneous systems on your main Linux system (several different UML kernels).

So download a nice kernel tree (like the vanilla one from kernel.org) and extract it to some local development location.

Next, configure this UML kernel as you would do for any other system, but append ARCH=um so that the kernel build software knows that the kernel is meant to run as a guest process on the main system.

On a default Gentoo system, is in your. If it isn't, you should find a definition of  in the  and fix it:

Sample definition of $PATH in /etc/profile

Don't forget to run  for the change to take effect.

For the user-mode Linux kernel to properly boot a Gentoo system the kernel needs to be configured to not automatically mount (devfs) by default. Also, you will almost certainly want to make sure that you have tmpfs (the "Virtual Memory Filesystem") compiled in, since by default the Gentoo Linux bootscripts store their information in a small tmpfs partition. (The binary kernels available from the user-mode website do automatically mount, and they don't have tmpfs compiled in; don't bother with them).

I highly recommend reading the user-mode Linux documentation, but the basic idea is that running the program boots the user-mode kernel and tries to bring up the system stored in the file  that should be located in the current working directory.

It won't hurt to also install the user-mode Linux tools.

These tools facilitate networking (among other things) between the user-mode Linux virtual system and the host Linux system.

Making the Gentoo chroot
The file needed for user-mode Linux is a single file that contains an entire Gentoo Linux file system. To generate this file you will need to have loopback device support enabled in the host (non-user-mode) kernel.

Generating the file itself will be our last step. First we will generate a Gentoo file system in an ordinary chroot. We need the stage tarball available, which could be downloaded separately, extracted from an Installation CD, or extracted from an Installation CD .iso.

Setting up the chroot is essentially identical to an ordinary Gentoo Linux build.

Go ahead and unmount the .iso. You don't need it anymore.

Build the system in the usual fashion: chroot into and follow the Gentoo installation instructions.

Add any additional packages you desire. Feel free to give your virtual Gentoo system a hostname, if you so desire. In you will want  to be , with a fs type of either ext2, ext3, or reiserfs. Set to be , and comment out.

At this point, remember to set your root password.

Now we need to make some changes to the boot scripts. Remove consolefont and keymaps from the boot runlevel:

Exit the chroot, unmount all of the bind mounts, tar up the new Gentoo distro, and clean up.

Making root_fs
Our Gentoo chroot is nearly 300 MB in size, so needs to be at least that size. We'll choose 0.5 GB as a reasonable size.

It would also be nice to have a 0.5 GB swap partition.

Now see if it works!

User-mode Linux uses xterms for the virtual consoles that are run at boot time, so you need to make sure that the terminal from which you run user-mode Linux has $DISPLAY properly set (along with proper xhost/xauth permissions).

With any luck you should be able to log into your user-mode Linux Gentoo system. The only thing keeping this user-mode Linux version of Gentoo from being fully functional is networking from the virtual machine to the host.

Using an Existing Network
Make sure that the host kernel has the following settings compiled as modules:

Run the following commands on the host machine:

The iptables line sets up IP Masquerading between the private network that our user-mode system will be on and the internet (reachable via  in our case). The echo line then turns on packet forwarding between the private network and the interface that the default gateway is on (eth0 for us).

Now we bring up the user-mode system and see if networking is functional.

Login to user-mode system, and then run:

On the user-mode system we assign the user-mode eth0 interface the private IP address 192.168.0.1 and bring up the interface. The host has private IP address 192.168.0.254, and we ping it to make sure that our networking is, indeed, up. The route line adds a default gateway, namely our host, we use scp to retrieve a working (if necessary), and we ping www.gentoo.org to make sure that name resolution (and general access to the internet) is working from our user-mode system. Now the user-mode system can  at will!

Using a Virtual Network
UML supports an additional networking facility, accessible by the UML instances. The  package provides a tool called   which defines the end points of the switch.

If the switch information should stay in the foreground:

If it should be backgrounded:

To start the UML instances on the switch, run the next command. Your (virtual) network interface will be connected to the  process and will be using the given MAC address.

You can still connect the system to the existing network, or have a second process attached to both the virtual one and the existing one:

More information about the tuntap setting can be found in the previous section.

Testing the .iso
Perhaps the true ideal of Gentoo Linux testing would be to boot the .iso with user-mode Linux and do the complete Gentoo install from within the user-mode Linux virtual system.

Booting the .iso, or actually the initrd from the .iso, is pretty straightforward.

Now you can follow the Gentoo install doc essentially verbatim, although you'll need to know that the root file system will be, the swap "partition" will be  , and the CD rom will be.

Resources

 * Bridging with UML
 * UML Homepage
 * Caker's UML Notes
 * UML Mailinglist archives

Acknowledgements
We would like to thank the following authors and editors for their contributions to this guide:


 * Grant Goodyear
 * John Davis
 * Sven Vermeulen
 * Benny Chuang