How to make a UML image on Debian

Out there, on the Internet, there is a lot of conflicting information on how to properly build a UML image on Debian. These instructions are for Debian Sid, but should work on Etch and Sarge as well. The instructions are partially based on the ones available here.

First, you want to apt-get install user-mode-linux uml-utilities bridge-utils debootstrap realpath. Then, become root either by su or sudo bash. Make an empty directory (such as ~/uml) and cd into it. Now, follow this psudeo script:

# setup environment, feel free to change DEBIAN_MIRROR to your closest mirrror, IP to an IP not already being used on your network, and GATEWAY to your LAN's gateway (not your host machine)
export TMPDIR=`pwd`"/tmp"
export IMAGE="root_fs"
export HOSTNAME="NameThisMachine"
export IP=""
export GATEWAY=""
mkdir $TMPDIR

# produce a 1GB image, fudge with seek to change size
dd if=/dev/zero of=$IMAGE bs=1 count=1 seek=1G

# make partition, and mount it; Debian Sid kernels can only mount ext2, ext3, cramfs, iso9660, and reiserfs, ext3 is the only one worth using
mkfs.ext3 $IMAGE
mount -o loop $IMAGE $TMPDIR

# download and install Debian into your image: change arch to the arch you're using, and change sid to sid, etch, or sarge; this step takes awhile
debootstrap --arch i386 sid $TMPDIR $DEBIAN_MIRROR

# install a correct fstab, proc and sys are automatically loaded on boot
echo "/dev/ubd0 / ext3 defaults 0 0" > $TMPDIR/etc/fstab
echo $HOSTNAME > $TMPDIR/etc/hostname

# tweak inittab
cp $TMPDIR/etc/inittab $TMPDIR/etc/
grep -v "getty" $TMPDIR/etc/ > $TMPDIR/etc/inittab
echo "# We launch just one console for UML:" >> $TMPDIR/etc/inittab
echo "c0:1235:respawn:/sbin/getty 38400 tty0 linux" >> $TMPDIR/etc/inittab
echo "# UML modification: use tty0 or vc/0" >> $TMPDIR/etc/securetty
echo "tty0" >> $TMPDIR/etc/securetty
echo "vc/0" >> $TMPDIR/etc/securetty

# add networking stuff
echo "auto lo" >> $TMPDIR/etc/network/interfaces
echo "iface lo inet loopback" >> $TMPDIR/etc/network/interfaces
echo "" >> $TMPDIR/etc/network/interfaces
echo "auto eth0" >> $TMPDIR/etc/network/interfaces
echo "iface eth0 inet static" >> $TMPDIR/etc/network/interfaces
echo "address $IP" >> $TMPDIR/etc/network/interfaces
echo "netmask" >> $TMPDIR/etc/network/interfaces
echo "gateway $GATEWAY" >> $TMPDIR/etc/network/interfaces

# clean up
umount $TMPDIR
rmdir $TMPDIR

You now have an image full of Debian named root_fs. To run, simply execute linux mem=64M ubd0s=root_fs. If you need more memory, increase the mem paramater. By default, there is no password for root, so just use root as your login and press enter when it asks for password.

A little aside on networking:the auto tuntap method (eth0=tuntap,,,, which basically does ARP proxying on the host machine) does not work properly as it only allows host->UML traffic. The only way I’ve been able to get UML networking to work properly is to build a full bridge setup. The following commands in /etc/network/interfaces/ sets up the bridge. You probably have something like:

auto eth0
iface eth0 inet dhcp

Comment that out with #s, and change it to:

auto br0
iface br0 inet dhcp
pre-up tunctl -u user-to-run-uml -t tap0
pre-up ifconfig eth0 promisc up
pre-up ifconfig tap0 promisc up
pre-up brctl addbr br0
pre-up brctl stp br0 off
pre-up brctl setfd br0 1
pre-up brctl sethello br0 1
pre-up brctl addif br0 eth0
pre-up brctl addif br0 tap0
post-down tunctl -d tap0

allow-hotplug eth0
iface eth0 inet manual
pre-up ifconfig eth0 promisc up
pre-up brctl addif br0 eth0
pre-down brctl delif br0 eth0
pre-down ifconfig eth0 down

Add the additional parameter to linux‘s command line: eth0=tuntap,tap0. That will make UML connect to tap0, and use the IP set above when you built the image. If you use a firewall, you need to change the interface to firewall from eth0 to br0, and to allow br0->br0 traffic.

Written by
Open Source software architect and technologist. He's just this guy, you know? Follow him him on Google+.
Published in
Transmissions from the Little Blue Marble

Published February 13th, 2007


3 Responses
Adrian Rueegsegger


There’s a small error in your howto:

echo $HOSTNAME > /etc/hostname

should be

echo $HOSTNAME > $TMPDIR/etc/hostname

otherwise the hostname file of the host-system will be overwritten.

1) You have to belong to the uml group to do so.

2) Yes, use screen.

1. What about running uml as non root ?

2. Is there a way of running multiple uml instances and easily connection to the consoles ?

Leave a Reply