VNUML Installation Guide
version 1.3

Fermin Galan (galan at
David Fernández (david at

November 3th, 2003

Virtual Network User Mode Linux

1. Introduction
2. System Requirements
    2.1. Installing Perl Modules
    2.2. Installing VLAN Support
3. VNUML Installation

1. Introduction

Before reading this document: Starting with 1.3.2-1, VNUML package includes an easy to use installer (please read INSTALL file after unpacking the package for detailed instructions). You only need to read this document if using an older version (plain 1.3.2, 1.3.1 or 1.3.0) that requieres a "by hand" installation.

The following of this document explains in detail the steps you have to follow in order to install VNUML tool "by hand"in a Linux machine. It covers VNUML language version 1.3 and 1.3.x.

Along this document and the rest of the documentation, we refer to the machine where VNUML is running as the "host". The Linux virtual machines that run over the host using UML virtualization software are typically refered as "virtual machines" or simply "UMLs".

Basically, VNUML tool is made of just a Perl script and a XML DTD. However, it makes use of several external packages that have to be previously installed in the host in order to work properly. Section 2 details all requiements needed to run VNUML and Section 3 the steps to install and run it.

2. System Requirements

Before continuing, please check that your system fulfills the following prerequisites. VNUML may not work if any of them is not acomplished!

  • GNU/Linux box to host the simulation. VNUML does not have special requirements, so it should work over any modern Linux distribution where UML works. However, the development and the main tests have been performed over SuSE 8.X and RedHat 7.3/8.0/9.0. Small problems could arise if you use a different distribution. Please, let us know about any successful or unsucessful tests over other distributions, in order to improve the tool in future versions.

    Note that UML simulations generally consume a lot of physical host resources (CPU, disk storage, RAM, etc). As a minimum, you need a standard Pentium III 500 Mhz with 128 Mb RAM to perform the tutorial included in the documentation. However, at least 256 Mb (better 512 Mb) and a faster CPU are recomended to execute more complex scenarios.

  • Root access to the host. You need root priviledges in the host in order to execute VNUML and simulate network scenarios.
  • Expat package. This is a language processing library needed by VNUML parser. You can check if you have it already installed with 'rpm -q expat'. In case you do not have it installed, you can download and install the following RPM from our server (later versions should also work): expat-1.95.5-1.i386.rpm.
  • Perl interpreter and modules. The VNUML parser is written in Perl. Therefore you need a Perl interpreter installed in the host in order to run it. Usually, Perl interpreters are installed by default by most GNU/Linux distributions. You can check whether you have it in your systems typing the following command:
    > perl -v

    Besides, you need to download and install the Perl modules that VNUML parser uses (see the list below). In order to check if you have all of them already installed just try (note the capitalized V):

    > -V

    If you have all the required modules you should see the following message (version numbers may vary):

    This is version: 1.2.1a (15/06/2003)
    Fermín Galán Márquez.

    If something is wrong you will see some messages like:

    Can't locate XML/ in @INC (@INC contains: ....
    ...  /usr/lib/perl5/site_perl/5.8.0 /usr/lib/perl5/site_perl .)
    at /usr/local/bin/ line 129
    BEGIN failed--compilation aborted at /usr/local/bin/ line 129.

    This output is telling us that XML::DOM module is missing. It depends on the particular Perl installation on your system what modules you will need to download and install (if you are lucky, you won't have to install anything :). For example, for SuSE 8.1 system you will probably have to install:

    Since version 1.3.1: you also need probablily the the following module:

    You can get the required modules from our server following the links above, or download them from their original distribution sites. More details about how to install Perl modules can be found later in this document.

  • UML tools and Bridge utilities. If not already installed, you have to download and install UML tools (uml_utilities-20021103-1.i386.rpm); and Bridge utilities (bridge-utils-0.9.3-7.i386.rpm). Newer versions of both RPMs should also work. You can check if they are already installed using 'rpm -q bridge-utils' or 'rpm -q uml_utilities').
    Warning: you need bridge-utils => 0.9.7 if you want to run simulations with more than 32 virtual networks. Read more about VNUML limitations.
  • TUN kernel support. VNUML uses the kernel support for Virtual Point-to-Point network devices (TUN). Usually, TUN is available as an external module that VNUML parser loads when it is needed. You can check whether you have the TUN module in your system with:
    > modprobe tun
    > lsmod | grep tun

    You can type 'rmmod tun' after the cheking to remove TUN module from memory.

  • loop kernel support. VNUML uses the loop support for customize virtual machine filesystems. Usually, loop support is available as an external module that VNUML parser loads when it is needed. You can check whether you have the loop module in your system with:
    > modprobe loop
    > lsmod | grep loop

    You can type 'rmmod loop' after the cheking to remove TUN module from memory.

  • Standard Commands. VNUML parser uses several standard commands that are usually available in any Linux distribution, so you shouldn't worry. You can check the availability of any of them in the host with 'which' command.

    Since version 1.3.1: the detection of the needed commands have been improved. The parser is able to exits with a error message when someone of the needed commands is not found.

    • /bin/bash
    • modprobe
    • ps
    • pidof
    • ifconfig
    • mount
    • umount
    • mke2fs
    • dd
    • chmod
    • cat
    • sleep
    • echo (usually as a shell built-in)
    • ssh
    • scp
    • route
    • bunzip2
    • ssh-keygen
    • I'm forgetting something?

    If you don't have any of them, try installing the appropiated package (RPM or deb).

2.1. Installing Perl modules

Perl modules are distributed as .tar.gz files. The standarized way to install them is the following:

  1. Uncompress file.
  2. Execute 'perl Makefile.PL'. This checks dependencies and tell you if another required module have to be installed previously.
  3. Execute 'make'.
  4. Execute 'make test'. Note that (curiously!) not getting 100% success doesn't mean always that the module is not going to work.
  5. Install the module with 'make install' (root privilegies are needed).

Required Perl modules can be downloaded from our server: perl-modules. Alternatively you can search them in CPAN (the Comprehensive Perl Archive Network). If you don't find the module you need in our server, please, tell us in order to add it.

2.2. Installing VLAN Support

VNUML includes support for VLANs in the external interface of the host machine. Basically, if the host is connected to a switch in trunk mode (that is, tagging frames with IEEE 802.1q), virtual machines under VNUML can be connected to different VLANs through the host physical interface (see VNUML User Manual for more details).

In order to enable VLAN support in VNUML, you have to aditionally install:

  • 802.1q kernel support. VNUML uses the 802.1q VLAN support included in Linux modern kernels. Usually, it is available as an external module that the parser loads when it is needed. You can check whether or not you have that module with:
    > modprobe 8012q
    > lsmod | grep 8012q
    ('rmmod 8012q' after the cheking will remove the module from memory).
  • VLAN utilities. You can check if you already have that utilities installed in your system with 'rpm -q vconfig'). If not, download and install the following RPM (later versions also should work): vconfig.i386.rpm

3. VNUML Installation

This section details the steps you have to follow in order to install VNUML software in a host that fulfills the requirements mentioned in the previous section.

  • VNUML parser and language DTD. Download the parser, unpack it and copy file to a directory included in the PATH (/usr/local/bin is used along the documentation). For example:
    > tar xfvz vnumlparser-1.3.0.tgz 
    > cd vnuml 
    > mv /usr/local/bin
    > chmod a+x /usr/local/bin/

    The first line of is the pathname of the Perl interpreter. If your Perl interpreter is not located in /usr/bin/perl, you need to edit and change it to use the right pathname.

    Additionally, you have to create some directories where VNUML parser stores some information (if you don't create them, VNUML parser will complain about it when executed).

    > mkdir /var/vnuml
    > mkdir /mnt/uml

    Finally, VNUML language syntax is defined in the vnuml.dtd file included in the distribution. You have to copy it to /var/vnuml directory:

    > mv vnuml.dtd /var/vnuml
  • UML kernel. Each virtual machine simulated using UML is a completely functional Linux kernel running as a user process in the user space of the actual host kernel. This kernel is built in a similar way as any convetional Linux kernel, but with some slight but important differences (the procedure is described in detail in the VNUML User Manual).

    Not every kernel works with VNUML (in particular, we have detected problems with some precompiled kernels available at UML website). For VNUML tutorial you can use the following kernel: linux-2.4.22-8um. Alternatively you can also use the following kernel: linux-2.4.19-um51.bz2, although it has problems with RedHat 9.0.

    After downloading the kernel, unpack it, give it execution rights and copy it to a directory of your convenience (you will have to include the complete kernel path in the <kernel> VNUML tag of each virtual machine defined). If you want that kernel to be used as the default one, just rename it to "linux" and copy it to "/usr/local/bin" directory. That is:

    > bunzip2 linux-2.4.19-um51.bz2
    > mv linux-2.4.19-um51 /usr/local/bin/linux
    > chmod a+x /usr/local/bin/linux
  • UML master filesystem. Each simulated UML uses a root filesystem that lives in a huge single file on the host underlying filesystem. This filesystem MUST fulfill several requeriments in order to work with VNUML (as described in the VNUML User Manual).

    You can either adapt one of the filesystems available in the UML project website or build an entirely new one. Alternatively, to follow VNUML tutorial and make simple tests, you can use the following root filesystem: root_fs_tutorial (download can can take a while, it's a really 160 Mbytes file!). After downloading, uncompress the file and put it in /var/vnuml directory. Password for the root account in this filesystem is "xxxx"; you will need it during tests.

    > bunzip2 root_fs_tutorial.bz2
    > mv root_fs_tutorial /var/vnuml/root_fs_tutorial

Last update:

Valid HTML 4.01!