Gentoo Logo
Gentoo Logo Side

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


1. 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." 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:

Code Listing 1.1: Installing UML kernel sources

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

Warning: The ARCH=um fragment is extremely important!

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:

Code Listing 1.2: Editing 00basic

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

Code Listing 1.3: Installing UML 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.

Code Listing 2.1: Mounting 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.

Code Listing 2.2: Creating the Gentoo chroot mount

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

Code Listing 2.3: Setting root password

# passwd

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

Code Listing 2.4: Removing unneeded initscripts

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

Code Listing 2.5: Finalising the installation

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

Code Listing 2.6: Creating UML files

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

Code Listing 2.7: Create swap partition

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

Now see if it works!

Code Listing 2.8: Start UML kernel thread

# 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:

Code Listing 3.1: Host kernel configuration

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:

Code Listing 3.2: Setup networking

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

Code Listing 3.3: Get UML up and running

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

--- 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
# netstat -rn
Kernel IP routing table
Destination  Gateway        Genmask        Flags MSS Window irtt Iface  U      40 0         0 eth0        UG     40 0         0 eth0
# scp [email protected]:/etc/resolv.conf /etc/resolv.conf (if needed)
# ping -c 2
PING ( 56 octets data
64 octets from icmp_seq=0 ttl=240 time=119.6 ms
64 octets from icmp_seq=1 ttl=240 time=92.0 ms

--- 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 and bring up the interface. The host has private IP address, 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 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.

Code Listing 4.1: Booting the ISO

# 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,,,

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

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.
Updated October 22, 2004
Grant Goodyear

John Davis

Sven Vermeulen

Benny Chuang

Summary:  This guide shows Gentoo Linux developers how to set up and use user-mode linux for testing potentially system-breaking changes.
The Gentoo Linux Store
Copyright 2001-2004 Gentoo Foundation, Inc. Questions, Comments, Corrections? Email [email protected].