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 vnumlparser.pl 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
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
needed to run VNUML and Section 3 the steps to install and run it.
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):
> vnumlparser.pl -V
If you have all the required modules you should see the
following message (version numbers may vary):
This is vnumlparser.pl version: 1.2.1a (15/06/2003)
Fermín Galán Márquez. email@example.com
If something is wrong you will see some messages like:
Can't locate XML/DOM.pm in @INC (@INC contains: ....
... /usr/lib/perl5/site_perl/5.8.0 /usr/lib/perl5/site_perl .)
at /usr/local/bin/vnumlparser.pl line 129
BEGIN failed--compilation aborted at /usr/local/bin/vnumlparser.pl 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
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
> 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
> 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
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.
- echo (usually as a shell built-in)
- I'm forgetting something?
If you don't have any of them, try installing
the appropiated package (RPM or deb).
2.1. Installing Perl
Perl modules are distributed as .tar.gz files. The
standarized way to install them is the following:
- Uncompress file.
- Execute 'perl Makefile.PL'. This checks
dependencies and tell you if another required module have
to be installed previously.
- Execute 'make'.
- Execute 'make test'. Note that (curiously!)
not getting 100% success doesn't mean always that the
module is not going to work.
- Install the module with 'make install' (root
privilegies are needed).
Required Perl modules can be downloaded from our server:
Alternatively you can search them in
Comprehensive Perl Archive Network).
If you don't find the module you need in our server, please,
tell us in order to
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
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
unpack it and copy vnumlparser.pl 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 vnumlparser.pl /usr/local/bin
> chmod a+x /usr/local/bin/vnumlparser.pl
The first line of vnumlpaser.pl is the pathname of the Perl
interpreter. If your Perl interpreter is not located in /usr/bin/perl,
you need to edit vnumlparser.pl and change it to use the right
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
> 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
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
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
> bunzip2 root_fs_tutorial.bz2
> mv root_fs_tutorial /var/vnuml/root_fs_tutorial