Gentoo Linux Developer's guide to system testing with User-Mode Linux

1. Obtaining User-Mode Linux

As the user-mode linux website (http://user-mode-linux.sourceforge.net) 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." Changes to Gentoo core packages such as sys-apps/baselayout or sys-libs/glibc 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.

Installing user-mode linux is essentially identical to a normal kernel install. First install the kernel sources (appropriately patched for user-mode linux), and then configure the user-mode linux kernel in the usual fashion:

# emerge sys-kernel/usermode-sources
# cd /usr/src/uml/linux
# make menuconfig ARCH=um
# make linux ARCH=um
# cp linux /usr/local/bin/linux

Make sure that /usr/local/bin is in your path. Edit /etc/env.d/00basic to that the PATH variable contains /usr/local/bin and rerun env-update:

# nano -w /etc/env.d/00basic
# env-update
# source /etc/profile

For the user-mode linux kernel to properly boot a Gentoo system the kernel needs to be configured to not automatically mount /dev (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 /dev, 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 /usr/local/bin/linux program boots the user-mode kernel and tries to bring up the system stored in the file root_fs that should be located in the current working directory.

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

# emerge sys-apps/usermode-utilities

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

2. Creating root_fs

Making the Gentoo chroot 

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

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

# mkdir /mnt/loop
# mount -o loop /path/to/install-<TAB>.iso /mnt/loop

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

# mkdir /mnt/gentoo
# cd /mnt/gentoo
# tar xvjpf /path/to/stage<TAB>.tar.bz2

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

Bootstrap and build the system in the usual fashion. Just follow the installation instructions :)

Add any additional packages you desire. Feel free to give your virtual Gentoo system a hostname, if you so desire. In /etc/fstab you will want /dev/ROOT to be /dev/ubd/0, with a fs type of either ext2, ext3, or reiserfs. Set /dev/SWAP to be /dev/ubd/1, and comment out /dev/BOOT.

At this point, remember to set your root password.

# passwd

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

# rc-update del consolefont boot
# rc-update del keymaps boot

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

# cd /mnt/gentoo
# tar cvjpf ~/gentoo.tbz2 *
# cd
# rm -rf /mnt/gentoo

Making root_fs 

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

# dd if=/dev/zero of=root_fs seek=500 count=1 bs=1M
# mke2fs -F root_fs
# mount -o loop root_fs /mnt/loop
# tar xvjpf gentoo.tbz2 -C /mnt/loop
# umount /mnt/loop

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

# dd if=/dev/zero of=swap_fs seek=500 count=1 bs=1M
# mkswap -f swap_fs

Now see if it works!

# linux ubd0=root_fs ubd1=swap_fs

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.

3. Networking

Make sure that the host kernel has the following settings compiled as modules:

Networking -->
  IP: Netfilter Configuration -->
    IP tables support -->
      Full NAT -->
        <M> MASQUERADE target support 
    
    Network Device Support --> 
      <M> TUN/TAP Support

Run the following commands on the host machine:

# modprobe tun
(If you receive a FATAL error here, try deleting /dev/net/tun and retry)
# modprobe iptable_nat
# iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
# echo 1 > /proc/sys/net/ipv4/ip_forward

The iptables line sets up IP Masquerading between the private network that our user-mode system will be on and the internet (reachable via eth0 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.

# linux ubd0=root_fs ubd1=swap_fs eth0=tuntap,,,192.168.0.254
(login to user-mode system)
# ifconfig eth0 192.168.0.1 up
# ping -c 2 192.168.0.254
PING 192.168.0.254 (192.168.0.254): 56 octets data
64 octets from 192.168.0.254: icmp_seq=0 ttl=255 time=0.8 ms
64 octets from 192.168.0.254: icmp_seq=1 ttl=255 time=0.6 ms

--- 192.168.0.254 ping statistics ---
2 packets transmitted, 2 packets received, 0% packet loss
round-trip min/avg/max = 0.6/0.7/0.8 ms
# route add default gw 192.168.0.254
# netstat -rn
Kernel IP routing table
Destination  Gateway        Genmask        Flags MSS Window irtt Iface
192.168.0.0  0.0.0.0        255.255.255.0  U      40 0         0 eth0
0.0.0.0      192.168.0.254  0.0.0.0        UG     40 0         0 eth0
# scp [email protected]:/etc/resolv.conf /etc/resolv.conf (if needed)
# ping -c 2 www.gentoo.org
PING www.gentoo.org (207.170.82.202): 56 octets data
64 octets from 207.170.82.202: icmp_seq=0 ttl=240 time=119.6 ms
64 octets from 207.170.82.202: icmp_seq=1 ttl=240 time=92.0 ms

--- www.gentoo.org ping statistics ---
2 packets transmitted, 2 packets received, 0% packet loss
round-trip min/avg/max = 92.0/105.8/119.6 ms

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 /etc/resolv.conf (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 emerge at will!

4. 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.

# mount -o loop /path/to/install-<TAB>.iso /mnt/loop
# cp /mnt/loop/isolinux/gentoo.igz .
# linux load_ramdisk=1 prompt_ramdisk=0 ramdisk_size=22000 \
> initrd=rescue.gz root=/dev/ram0 ubd0=root_fs ubd1=swap_fs \
> ubd2=/dev/cdroms/cdrom0 eth0=tuntap,,,192.168.0.254

Now you can follow the Gentoo install doc essentially verbatim, although you'll need to know that the root filesystem will be /dev/ubd/0, the swap "partition" will be /dev/ubd/1, and the CD rom will be /dev/ubd/2.

5. Resources

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