User Mode Linux HOWTO
User Mode Linux Core Team
Mon Nov 18 14:16:16 EST 2002
This document describes the use and abuse of Jeff Dike's User Mode
Linux: a port of the Linux kernel as a normal Intel Linux process.
______________________________________________________________________
Table of Contents
1. Introduction
1.1 How is User Mode Linux Different?
1.2 Why Would I Want User Mode Linux?
2. Compiling the kernel and modules
2.1 Compiling the kernel
2.2 Compiling and installing kernel modules
2.3 Compiling and installing uml_utilities
3. Running UML and logging in
3.1 Running UML
3.2 Logging in
3.3 Examples
4. UML on 2G/2G hosts
4.1 Introduction
4.2 The problem
4.3 The solution
5. Setting up serial lines and consoles
5.1 Specifying the device
5.2 Specifying the channel
5.3 Examples
6. Setting up the network
6.1 General setup
6.2 Userspace daemons
6.3 Specifying ethernet addresses
6.4 UML interface setup
6.5 Multicast
6.6 TUN/TAP with the uml_net helper
6.7 TUN/TAP with a preconfigured tap device
6.8 Ethertap
6.9 The switch daemon
6.10 Slip
6.11 Slirp
6.12 pcap
6.13 Setting up the host yourself
7. Sharing Filesystems between Virtual Machines
7.1 A warning
7.2 Using layered block devices
7.3 Note!
7.4 Another warning
7.5 uml_moo : Merging a COW file with its backing file
8. Creating filesystems
8.1 Create the filesystem file
8.2 Assign the file to a UML device
8.3 Creating and mounting the filesystem
9. Host file access
9.1 Using hostfs
9.2 hostfs as the root filesystem
9.3 Building hostfs
10. The Management Console
10.1 version
10.2 halt and reboot
10.3 config
10.4 remove
10.5 sysrq
10.6 help
10.7 cad
10.8 stop
10.9 go
11. Kernel debugging
11.1 Starting the kernel under gdb
11.2 Examining sleeping processes
11.3 Running ddd on UML
11.4 Debugging modules
11.5 Attaching gdb to the kernel
11.6 Using alternate debuggers
12. Kernel debugging examples
12.1 The case of the hung fsck
12.2 Episode 2: The case of the hung fsck
13. What to do when UML doesn't work
13.1 Strange compilation errors when you build from source
13.2 (obsolete)
13.3 A variety of panics and hangs with /tmp on a reiserfs filesystem
13.4 The compile fails with errors about conflicting types for 'open', 'dup', and 'waitpid'
13.5 UML doesn't work when /tmp is an NFS filesystem
13.6 UML hangs on boot when compiled with gprof support
13.7 syslogd dies with a SIGTERM on startup
13.8 TUN/TAP networking doesn't work on a 2.4 host
13.9 You can network to the host but not to other machines on the net
13.10 I have no root and I want to scream
13.11 UML build conflict between ptrace.h and ucontext.h
13.12 The UML BogoMips is exactly half the host's BogoMips
13.13 When you run UML, it immediately segfaults
13.14 xterms appear, then immediately disappear
13.15 Any other panic, hang, or strange behavior
14. Diagnosing Problems
14.1 Case 1 : Normal kernel panics
14.2 Case 2 : Tracing thread panics
14.3 Case 3 : Tracing thread panics caused by other threads
14.4 Case 4 : Hangs
15. Thanks
15.1 Code and Documentation
15.2 Flushing out bugs
15.3 Buglets and clean-ups
15.4 Case Studies
15.5 Other contributions
______________________________________________________________________
11.. IInnttrroodduuccttiioonn
Welcome to User Mode Linux. It's going to be fun.
11..11.. HHooww iiss UUsseerr MMooddee LLiinnuuxx DDiiffffeerreenntt??
Normally, the Linux Kernel talks straight to your hardware (video
card, keyboard, hard drives, etc), and any programs which run ask the
kernel to operate the hardware, like so:
+-----------+-----------+----+
| Process 1 | Process 2 | ...|
+-----------+-----------+----+
| Linux Kernel |
+----------------------------+
| Hardware |
+----------------------------+
The User Mode Linux Kernel is different; instead of talking to the
hardware, it talks to a `real' Linux kernel (called the `host kernel'
from now on), like any other program. Programs can then run inside
User-Mode Linux as if they were running under a normal kernel, like
so:
+----------------+
| Process 2 | ...|
+-----------+----------------+
| Process 1 | User-Mode Linux|
+----------------------------+
| Linux Kernel |
+----------------------------+
| Hardware |
+----------------------------+
11..22.. WWhhyy WWoouulldd II WWaanntt UUsseerr MMooddee LLiinnuuxx??
1. If User Mode Linux crashes, your host kernel is still fine.
2. You can run a usermode kernel as a non-root user.
3. You can debug the User Mode Linux like any normal process.
4. You can run gprof (profiling) and gcov (coverage testing).
5. You can play with your kernel without breaking things.
6. You can use it as a sandbox for testing new apps.
7. You can try new development kernels safely.
8. You can run different distributions simultaneously.
9. It's extremely fun.
22.. CCoommppiilliinngg tthhee kkeerrnneell aanndd mmoodduulleess
22..11.. CCoommppiilliinngg tthhee kkeerrnneell
Compiling the user mode kernel is just like compiling any other
kernel. Let's go through the steps, using 2.4.0-prerelease (current
as of this writing) as an example:
1. Download the latest UML patch from
the download page <http://user-mode-linux.sourceforge.net/dl-
sf.html>
In this example, the file is uml-patch-2.4.0-prerelease.bz2.
2. Download the matching kernel from your favourite kernel mirror,
such as:
ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2
<ftp://ftp.ca.kernel.org/pub/kernel/v2.4/linux-2.4.0-prerelease.tar.bz2>
.
3. Make a directory and unpack the kernel into it.
host%
mkdir ~/uml
host%
cd ~/uml
host%
tar -xzvf linux-2.4.0-prerelease.tar.bz2
4. Apply the patch using
host%
cd ~/uml/linux
host%
bzcat uml-patch-2.4.0-prerelease.bz2 | patch -p1
5. Run your favorite config; `make xconfig ARCH=um' is the most
convenient. `make config ARCH=um' and 'make menuconfig ARCH=um'
will work as well. The defaults will give you a useful kernel. If
you want to change something, go ahead, it probably won't hurt
anything.
Note: If the host is configured with a 2G/2G address space split
rather than the usual 3G/1G split, then the packaged UML binaries
will not run. They will immediately segfault. See ``UML on 2G/2G
hosts'' for the scoop on running UML on your system.
6. Finish with `make linux ARCH=um': the result is a file called
`linux' in the top directory of your source tree.
Make sure that you don't build this kernel in /usr/src/linux. On some
distributions, /usr/include/asm is a link into this pool. The user-
mode build changes the other end of that link, and things that include
<asm/anything.h> stop compiling.
The sources are also available from cvs at the project's cvs page,
which has directions on getting the sources. You can also browse the
CVS pool from there.
If you get the CVS sources, you will have to check them out into an
empty directory. You will th