Host Kernel

Although User-Mode Linux can be run as a user process under any host Linux kernel, there are several patches that can be made to the host kernel to improve the efficiency and throughput of the UML guest systems. Two important patches provide for the SKAS and SYSEMU enhancements. In fact, these two are so important that they have been combined into a single patch by Blaisorblade. The latest patch is the skas-*-v9-pre9 patch.

How the host kernel is patched, compiled and installed depends on the Linux distro. For Debian, we use the kernel-package system. A Precompiled 2.6.17 kernel with the skas3-2.6.17-rc5-v9-pre9 patch already applied can be found in our Debian repository. Also available are older precompiled 2.6.7 through 2.6.12 kernels with the host-skas3-v8 patch already applied.

Common problems:

• 2.6.9 - When used as the host, version 2.6.9 and up of the Linux kernel has modifications that breaks some assumptions made by the UML guest kernel. As a result, in order to use a 2.6.9 host kernel, one must use a guest kernel that is patched properly to fix those problems. As a practical matter, this means using either a 2.4.27 guest kernel with the uml-2.4.27-bs1 patch, or 2.6.9 guest kernel with the uml-2.6.9-bs7 patch, or a guest kernel that is version 2.6.10 or higher. If using an older guest kernel is important, one should stick with a 2.6.8.1 or earlier host kernel.

Guest Kernel

The guest kernel is the executable program that can be run by a normal user to start up a virtual Linux machine. To build a guest kernel, one typically needs the Linux kernel sources, the main UML patch, and incremental patches, along with these instructions. However, starting with version 2.6.9, the main UML code is already part of the Linux kernel source code, so in theory, no patches are necessary. However, UML is in continuous development at this point, so practically, one still needs the latest incremental patches in order to build a solid kernel that has all the updated features and bug fixes.

For Debian, we have precompiled the latest 2.6.17 guest kernel with NTPL support and the CONFIG_2G2G option turned on to work around the configuration of the default Debian kernels. We also have an archive of older kernels, including a 2.6.9 guest kernel using the uml-2.6.9-bs7 and uml-pretend-to-be-i586 patches, as well as the 2.6.12, 2.6.13, and 2.6.14 guest kernels with only the uml-pretend-to-be-i586 patch. These can be found in our Debian repository. These kernels are also available unpackaged (2.6.9-bs7, 2.6.12, 2.6.13, 2.6.14, 2.6.17).

Common problems:

• config defaults - When compiling a 2.6.* guest kernel for the first time, if the default configuration options are used, the resulting guest kernel is unusable because many devices important to UML are turned off. In order to start off with sane defaults, one must issue a "make defconfig ARCH=um" command before the "make menuconfig ARCH=um" or equivalent. Alternatively, start off with a known working configuration such as the config file we used to compile our 2.6.9-bs7 guest kernel.
• TT mode - Most live User-Mode Linux installations use SKAS enabled host kernels. As a result, TT mode does not get as much testing as SKAS mode, and not surprisingly, many older versions of guest kernels will not run properly in TT mode. Be sure to use a recent guest kernel if TT mode is important.
• 2.6.13 - Starting with version 2.6.13, devfs is no longer supported in the linux kernel. Any guest filesystems that require devfs will need to use an older kernel.

Guest File System

There are many documents around the net on creating guest file systems for User-Mode Linux:

• Creating a root filesystem with rootstrap
• Debian Installation Inside UML HOWTO

There are also many prebuilt guest file systems available for download. Some example sites are the official UML download site, Matt Zimmerman's Debian stable filesystems, and Henrique Moreira's Debian, Slackware, and RH9 filesystems. However, due to the problems described below, many available file systems fail to boot under the latest uml kernels. Some individual file systems that we've downloaded (or created) that we were able to boot up sucessfully with our 2.6.9 guest kernel along with the command lines we used include:

Debian 3.0r2 (42.4Mb, Matt Zimmerman)

linux-2.6.9 mem=64M ubd0=Debian-3.0r2.ext2 con=null con0=null,fd:2 con1=fd:0,fd:1 devfs=nomount

Debian Sid (26.3Mb)

linux-2.6.9 mem=64M ubd0=debian-sid.ext3 con=null con0=null,fd:2 con1=fd:0,fd:1 devfs=nomount eth0=daemon,,unix,/var/run/uml-utilities/uml_switch.ctl

Common problems:

• DevFS - Some files systems are configured to use devfs. They typically require an additional command line argument to the guest kernel ("devfs=mount") in order to work. Internally, the guest file system generally refers to the first terminal device as /dev/vc/0 or /dev/tty/0 and the first disk device as /dev/ubd/0 or /dev/ubd/disc0/disc. Other file systems are configured without devfs, which may require a command line argument ("devfs=nomount"), and they generally refer to the first terminal device as /dev/tty0 and first disk device as /dev/ubd0. Still, others may use udev (also "devfs=nomount"), and that typically refers to the first tty device as /dev/tty0 and first disk device as /dev/ubda. It is important to make sure the guest file system is coordinated with the proper command line argument and that the /etc/inittab and /etc/fstab, as well as other init scripts refer to the proper device names. Additionally, the symlinks /dev/ubd/0, /dev/ubd/1, etc., are no longer created in the latest 2.6.9 uml kernels even when specifying devfs=mount. Many old guest file systems that were expecting to find the hard drives at those locations will no longer boot up sucessfully without manual modifications via a loop device.
• NPTL/TLS - Thread Local Storage (TLS), which is required by the Native POSIX Thread Library (NPTL), is now supported in UML in 2.6.17. However, when using a 2.6 guest kernel version 2.6.16 or earlier on i686, the system assumes that NPTL is available and tries to start it, which will crash or hang the system. The workaround for this problem is to remove or rename the /lib/tls directory to something else (typically /lib/tls.disabled) so that the TLS libraries cannot be found. Another workaround is to compile the guest kernel to report that it is running on a i586 or lower system so that NPTL is not started.

Networking

Any reasonable networking setup in User-Mode Linux requires the latest version of uml-utilities to be installed. In Debian, this is part of the standard packages, so a simple "apt-get install uml-utilities" will suffice. Alternatively, one can download the source code from the official UML download site and then compile and install it manually.

UML networking is documented well on the main UML site. Besides the general information, the most important sections are the TUN/TAP with the uml_net helper, TUN/TAP with a preconfigured tap device, and the switch daemon sections. A reasonably current UML networking setup should be using one of these three methods.

On Debian, the switch daemon is the simplest setup. Follow the instructions from the readme file at /usr/share/doc/uml-utilities/README.Debian after installing the uml-utilities package. However, note that the debian package initializes the socket at /var/run/uml-utilities/uml_switch.ctl instead of the UML default of /tmp/uml.ctl. This means that command line argument for the guest kernel in order to use the switch daemon must be "eth0=daemon,,unix,/var/run/uml-utilities/uml_switch.ctl", not simply "eth0=daemon" as described in the readme.

Additionally, in order for the UML guests to connect to the Internet, it is necessary to either set up routing on the UML host or add a network bridge to connect the UML guests directly to the outside network. This is described briefly under the TUN/TAP with a preconfigured tap device section in the documentation. Keep in mind that the setup described there is equally applicable to the other two configurations as well. Another write-up on setting up a network bridge can be found in this article.

Management Utilities

Various utilities can be used to edit filesystem images, and manage pools of UMLs.

• UMLazi
• UMLd

Mailing Lists

The best way to stay updated on User-Mode Linux is to subscribe to one or both of the mailing lists: user-mode-linux-user and user-mode-linux-devel.

Developers' Sites

Several sites of primary developers contain the most recent patches and information for User-Mode Linux.

• User-Mode Linux home page
• UML Patches from Blaisorblade
• UML Patches from Kraxel