User Mode Linux HOWTO

User Mode Linux Core Team

1. Introduction

• 1.1 What is User Mode Linux?
• 1.2 How is User Mode Linux Different?
• 1.3 How does UML Work?
• 1.4 Why Would I Want UML?

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 Moving a backing file
• 7.6 uml_moo : Merging a COW file with its backing file
• 7.7 uml_mkcow : Create a new COW 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 command line options
• 9.3 hostfs as the root filesystem
• 9.4 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
• 10.10 log
• 10.11 proc
• 10.12 Making online backups
• 10.13 Event notification

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 UML hangs on boot after mounting devfs
• 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 cannot set up thread-local storage
• 13.16 Process segfaults with a modern (NPTL-using) filesystem
• 13.17 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