Val's User-Mode Linux tips

User-Mode Linux is awesome, especially if you are a file systems developer. But getting it running was a little tricky, partly because there is so much documentation! Here are the things I learned about running UML.

There is a summary of how to get, compile, and run UML at the end of this page, but I strongly suggest you read the whole thing first. It will save you a lot of time later.

UML Tips

• You don't need kernel patches any more. Any fairly current kernel has UML included, and it usually compiles and runs just fine.
• You will need a decent .config file. Here's .config file I used for doing file system development.

  UML .config for fs development

  This has, among other things, the setting to require synchronous I/O to the file containing the file system image. This is a requirement for doing file system development, otherwise it is like having a disk that lies continually about whether it has written your data.
• Don't forget to always always always run compile commands with ARCH=um. For example:

  $ make menuconfig ARCH=um
  $ make linux ARCH=um
  $ make clean ARCH=um
  

  If you accidentally run a command without ARCH=um, this will build a .config or the kernel or set up the headers for the wrong ARCH. To fix this, you'll have to do a:

  $ make mrproper
  

  If you get tired of forgetting this, you can edit the ARCH= line in the Makefile, but that produces unsightly extra bits when you make patches.
• Next you will need a root file system. You can either download someone else's UML root file system, or you can make your own with debootstrap or something similar. This step is a lot simpler than it used to be in the olden days, but it's still the most painful part. Here's one fairly recent tutorial on creating a UML root file system using debootstrap.
• Once you have a file system image, you will need to tell UML where it is located when it boots. This seems relatively simple on first sight:

  $ ./linux ubd0=/path/to/unzipped/root_fs
  

  However, you will find yourself continually mistyping this by transposing the 'b' and the 'd' in the "ubd" part. UML helpfully prints out a little message saying that you have probably mistyped this, which promptly scrolls up and off the screen, leaving you to wonder why your root file system can't be mounted. If you say "UML Block Device" out loud several times, you will remember which way to type this. (I would prefer UML just recognized both forms).
• Another excellent way to fail to mount your root file system is to only partially kill off a running UML instance, leaving several threads still off in the background doing something inscrutable. These threads still have the file containing your file system image open, and UML refuses to run unless it can get an exclusive lock on this file. I usually fix the problem thus:

  $ pkill -9 '^linux$'
  

  Be careful if you are running any other process on the system named linux; this command will kill that process too.
• If you want to edit the file system image on the host:

  $ sudo mount -o loop /path/to/unzipped/root_fs /mnt
  [edit files]
  $ sudo umount /mnt
  

• Now it's time to run UML under gdb. I put the following commands into a file named gdb_commands:

  set args ubd0=/path/to/unzipped/root_fs
  handle SIGSEGV nostop noprint
  handle SIGUSR1 nopass stop print
  

  About the gdb signal handler "handle" lines above: UML uses SIGSEGV for internal communication. Without the above instruction to "nostop noprint", gdb will automatically drop into the debugger every time UML sends itself a SIGSEGV. SIGUSR1 is what we will use to stop UML and drop it into the debugger intentionally. Older versions of UML used different signals for different purposes and these may change in the future.

  Run gdb as follows:

  $ gdb -x ../gdb_commands ./linux
  [wait for prompt, then type "run"]
  

  If you want to drop into the debugger, send it SIGUSR1 (which we have configured gdb to catch in the gdb_commands file above):

  $ pkill -SIGUSR1 -o linux
  

Running UML in a nutshell

• Download the latest kernel from http://www.kernel.org/
• Unpack the kernel. Copy this .config file into the top-level directory.
• Download a file system image.
• Cd into the top-level directory of the kernel source and run:

  $ make oldconfig ARCH=um
  $ make linux ARCH=um
  $ ./linux ubd0=/path/to/unzipped/root_fs
  [wait for prompt, then login as "root", no password]