Jump to: navigation, search

How to create a VNUML-compatible root filesystem from scratch using debootstrap (Debian/Ubuntu)

Michael Monreal
Fermín Galán (galan at
David Fernández (david at
version 1.1, February 25th, 2008


Virtual machines created by VNUML need a root filesystem (root_fs) to work. The VNUML root_fs are basically UML filesystem, slightly tunned to work with the tool (for example, special mount point has to be created).

Until now the VNUML Project has provided a root_fs_tutorial filesystem for download (current version at time of writing this is 0.4.1). However, maintaining the root_fs_tutorial is costly because there are a lot of details to check when a new version is released. In addition, the bunch of packages included in root_fs_tutorial hardly satisfy all the user needs (some won't find the particular packages they want and many others will have a lot of unnecessary stuff they don't need).

Therefore, a more practical approach is to provide simple and easy-to-implement procedure that allow user to produce it's own VNUML-compatible filesystems, with the size and software package they want. This goal is addressed by the present document.

The procedure described in this document has been developed by Michael Monreal, with minor additions and fixes by Fermín Galán. This procedure has been satisfactorily used to generate the base root_fs_tutorial-0.5.0.


The procedure will create a Debian-based VNUML-compatible root_fs. We asume you are using Debian (or maybe other Debian-based distribution) to generate the root_fs. Before starting ask yourself:

  • The size of the desired root_fs (we'll consider 800Mb here)
  • Which Debian packages you want to include (we'll use here a list based on the contents of root_fs_tutorial).

Note that the base filesystem created by debootstrap seems to take around 200MB. Take it into account when deciding the root_fs size and the packages that you will install.

Let's go (I'll asume you are logged as root; otherwise execute privileged commands using sudo):

  1. Create an ext3 filesystem (800MB). Change the destination directory (/usr/share/vnuml/filesystems) if it is not suitable for you.
  2.   $ dd if=/dev/zero of=/usr/share/vnuml/filesystems/debian.ext3 bs=1024k seek=800 count=0
      $ mkfs.ext3 /usr/share/vnuml/filesystems/debian.ext3
      $ tune2fs -c 0 -i 0 /usr/share/vnuml/filesystems/debian.ext3
  3. Mount and use debootstrap to install the latest "etch" release. The last command can take a while, depending of the speed of your Internet connection (as a figure I have a high speed connection and I has taken around 11 minutes). You could use a mirror of the Debian package repository close to your geographical location (like if you want.
  4.   $ mkdir /mnt/debian
      $ mount -o loop /usr/share/vnuml/filesystems/debian.ext3 /mnt/debian
      $ debootstrap etch /mnt/debian/
  5. Change root to the new system
  6.   $ mount -t proc none /mnt/debian/proc
      $ chroot /mnt/debian
      # env -update
  7. Edit /etc/apt/sources.list with some like that:
  8.   deb etch main contrib non-free
  9. Refresh package cache
  10.   # apt-get update
  11. Install the desired packages (it's up to you! :). Here were are using an arbitrary list, based on the old root_fs_tutorial, around 151MB after unpacking. It is highly recommendable to install at least openssh-server (for the sshd daemon).
  12.   # apt-get install apache2.2-common apache2-mpm-prefork apache2-utils \
         bzip2 dnsutils ethereal-common fdutils file fileutils finger ftp ftpd \
         iproute ipsec-tools iputils-tracepath ipv6calc ipvsadm less lpr lsof \
         lynx modutils ncurses-term  nfs-common openssh-client openssh-server \
         openssl perl perl-modules pidentd portmap ppp procmail python \
         python-central python-newt quagga racoon radvd setserial sharutils \
         shellutils squid squid-common ssh ssl-cert strace syslinux tcpdump \
         tcsh telnet tethereal textutils time tshark ucf vlan whois \
         wireshark-common sudo vim iptables

    If you want to install the same packages that the ones in a "reference" system, firts, get a list of packages in that system. The following command can be useful:

      # dpkg -l | grep ^ii | awk '{print $2}' > packages-list

    Then, you can install exactly the same packages with:

      # apt-get install $(cat packages-list)
  13. (Optional) If you want to free space of the downloaded packages (around 42MB):
  14.   # apt-get clean
  15. Set timezone (use the proper one for you, I'm using Europe/Madrid because it corresponds where I live :)
  16.   # ln -sf /usr/share/zoneinfo/Europe/Madrid /etc/localtime
  17. Edit /etc/hosts (no existing at the begining)
  18.		localhost
      ::1             	localhost
      # The following lines are desirable for IPv6 capable hosts
      ::1     ip6-localhost ip6-loopback
      fe00::0 ip6-localnet
      ff00::0 ip6-mcastprefix
      ff02::1 ip6-allnodes
      ff02::2 ip6-allrouters
      ff02::3 ip6-allhosts
  19. (Optional) Edit /etc/hostname and set a name different from the one of the host where you executed debootstrap (actually, VNUML will set the host name properly based on the name of the virtual machine so this step is optional but recommendable anyway).
  20. Edit /etc/inittab and add the following (otherwise, you won't get a login prompt in xterms, although VMs boot correctly and SSH should work)
  21.   0:2345:respawn:/sbin/getty 38400 tty0
  22. Change the ca line in /etc/inittab, so it uses /sbin/halt, as follows:
  23.   ca:12345:ctrlaltdel:/sbin/halt
  24. Edit /etc/securetty and add the following (otherwise login will be rejected, not even asking for a password)
  25.   tty0
  26. Edit /etc/network/interfaces (empty at the beginging):
  27.   iface lo inet loopback
      auto lo
  28. Edit /etc/fstab (empty at the beginging):
  29.   proc         /proc          proc     defaults   0 0
      devpts       /dev/pts       devpts   mode=0622  0 0
      /dev/ubda    /              ext3     defaults   0 1
      /dev/ubdb    /mnt/vnuml     iso9660  defaults   0 0
  30. (Optional) Set root password (if you skip this step the root password won't be prompted, you are warned! :)
  31.   # passwd
  32. Some VNUML stuff:
  33.   # mkdir /mnt/vnuml
      # mkdir /mnt/hostfs
      # ln -s /mnt/vnuml/umlboot /etc/rc2.d/S11umlboot
  34. Exit of the chroot enviroment. The latest steps will be performed in the mount /mnt/debian.
  35.   # exit
  36. Create the /dev/ubda, /dev/ubdb, etc. devices. The recommended way is to use the script (
  37.   $ cd /mnt/debian/dev
      $ wget
      $ chmod a+x
      $ ./
      $ rm
  38. Install modules corresponding to your UML kernel. For example, in the case of the linux- kernel (, considering the linux- has been downloaded in /tmp:
  39.   $ cd /tmp
      $ tar xfvj linux- 
      $ mv linux- /mnt/debian/lib/modules/
      $ cd /mnt/debian/lib/modules/
      $ tar xfv modules-
      $ rm -f modules-
      $ rm -rf /tmp/linux-
  40. Umount filesystem:
  41.   $ cd /
      $ umount /mnt/debian/proc/
      $ fuser -k /mnt/debian
      $ umount /mnt/debian

The filesystem is ready to be used! You can perform a quick test editing simple.xml and changing the filesystem tag to:

  <filesystem type="cow">/usr/share/vnuml/filesystem/debian.ext3</filesystem>

Then (the -P is only needed if you have to purge some pre-existing scenario based on simple.xml): -P simple.xml -v -t simple.xml -v

and you should see the usual xterm poping-up.

NOTE: you could want to edit /etc/inittab in the root_fs, but it is not actually required, because the VNUML-ization step performed by during -t mode will properly configure the file (execpt if you are skipping VNUML-ization for some reason with -Z; in that case you have to edit /etc/inittab to allow the use of tty0).

Notes for pre-1.7.0 users

In the case you plan to use your filesystem with a VNUML version previous to 1.7.0 (e.g., 1.6.0, 1.5.0, etc.) you need to use a different /etc/fstab table. In particular:

  proc         /proc          proc     defaults   0 0
  devpts       /dev/pts       devpts   mode=0622  0 0
  /dev/ubd/0   /              ext3     defaults   0 1
  /dev/ubd/1   /mnt/vnuml     iso9660  defaults   0 0

(Note: I haven't checked it myself, because I don't use now old VNUML versions. If you try this please tell us if it works for you or not to vnuml at Thanks! :)

As reference:

  for u in a b c d e f g h
          do dev=$device$u
          mknod $dev b $major $minor
          chmod 660 $dev
          chgrp disk $dev
          for i in $(seq 1 15)
               mknod $dev$i b $major $(($minor + $i))
               chmod 660 $dev$i
               chgrp disk $dev$i
       minor=$(($minor + 16))

Appendix 1: Quick recipe for Ubuntu Feisty

  • Create and populate base filesystem:
 dd if=/dev/zero of=ubuntu bs=1024k seek=1000 count=0
 mkfs.ext3 ubuntu 
 tune2fs -c 0 -i 0 ubuntu 
 mkdir /mnt/ubuntu
 mount -o loop ubuntu /mnt/ubuntu/
 debootstrap --arch i386 feisty /mnt/ubuntu/
 mount -t proc none /mnt/ubuntu/proc
 chroot /mnt/ubuntu/
 env -update
 apt-get update
 apt-get install openssh-server
 apt-get clean
 ln -sf /usr/share/zoneinfo/Europe/Madrid /etc/localtime
  • Configure the keymaps and timezone
apt-get install language-pack-es
dpkg-reconfigure locales
dpkg-reconfigure console-setup
  • Edit /etc/hosts:		localhost
 ::1             	localhost
 # The following lines are desirable for IPv6 capable hosts
 ::1     ip6-localhost ip6-loopback
 fe00::0 ip6-localnet
 ff00::0 ip6-mcastprefix
 ff02::1 ip6-allnodes
 ff02::2 ip6-allrouters
 ff02::3 ip6-allhosts
  • Edit /etc/hostname and set the desired hostname
  • Edit /etc/network/interfaces
iface lo inet loopback
auto lo
  • Edit /etc/fstab
proc         /proc          proc     defaults   0 0
devpts       /dev/pts       devpts   mode=0622  0 0
/dev/ubda    /              ext3     defaults   0 1
/dev/ubdb    /mnt/vnuml     iso9660  defaults   0 0
  • Set root password:
  • VNUML stuff:
 mkdir /mnt/vnuml /mnt/hostfs
 ln -s /mnt/vnuml/umlboot /etc/rc2.d/S11umlboot
  • Exit from chroot:
  • Create ubd devices:
cd /mnt/debian/dev
chmod a+x
  • Copy kernel modules:
cd /mnt/ubuntu/lib/modules
tar xfv /usr/share/linux-um/modules-
  • Create /etc/event.d/tty0 file:
 cp /etc/event.d/tty1 /etc/event.d/tty0
 vi /etc/event.d/tty0     (change any occurence of tty1 by tty0)
  • Edit /etc/securetty and include tty0
 umount /mnt/ubuntu/proc/
 umount /mnt/ubuntu/