Before installing, check the prerequisites. VNUML may not work if any of them is not acomplished!
perl -v
modprobe tun lsmod | grep tun('rmmod tun' after the cheking will remove TUN module from memory).
VNUML parser is just a script, but it need several packages to work. Installation requieres root privileges.
mv vnumlparser.pl /usr/local/bin chmod a+x /usr/local/bin/vnumlpaser.plThe first line of vnumlpaser.pl is the pathname of the Perl interpreter. If in your system is other than /usr/bin/perl you need to edit vnumlparser.pl file in order to use the right pathname. Aditionally, you have to make some directories where VNUML parser stores its working and temporal files (if you don't, VNUML parser complains about it when executed).
mkdir /var/vnuml mkdir /mnt/umlYou also need to download required Perl modules that VNUML parser uses (mainly the XML-DOM processing module). In order to check if you have already installed all the modules try (note the capitalized V):
vnumlparser.pl -VIf you have all the required modules installed you should see the following (version number may vary):
This is vnumlparser.pl version: 1.2.1a (15/06/2003) Fermín Galán Márquez. galan@dit.upm.esIf something is wrong you should see same like that:
Can't locate XML/DOM.pm in @INC (@INC contains: /usr/lib/perl5/5.8.0/i586-linux-thread-multi /usr/lib/perl5/5.8.0 /usr/lib/perl5/site_perl/5.8.0/i586-linux-thread-multi /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 of the particular Perl installation of your system what modules you will need to download and install (if you are lucky, you don't have to do nothing :). For example, in a test in a SuSE 8.1 system the following were needed to be installed: Read about Perl modules installation later in this document.
bunzip2 linux-2.4.19-um51.bz2 mv linux-2.4.1-um51 /usr/local/bin/linux chmod a+x /usr/local/bin/linux
The basic installation described before is the minimum software to get VNUML working. To get additional functionality you need to install aditional software. Installation requieres root privileges.
In order to get VLAN support:
modprobe 8012q lsmod | grep 8012q('rmmod 8012q' after the cheking will remove the module from memory).
Perl modules are distributed as .tar.gz files. The standarized way to install them is following:
Where to find the required modules? First try at perl-modules. If you don't find the module that you need at that place, report it (so we can add it as soon as posible) and try searching in CPAN (the Comprehensive Perl Archive Network).
Sooner or later, you want to build your own customized UML kernel to use in VNUML simulations. This section explains how to do it.
cd /usr/src/linux-2.4.19 cat uml-patch-2.4.19-13.bz2 | bunzip2 - | patch -p1
make menuconfig ARCH=um
make dep ARCH=um make linux ARCH=umThis commands produces a executable file named 'linux' in the root of the sources directory. Put the file in a place within console command path (or a copy or a symlink). For example:
cp linux /usr/local/bin
Module for the UML kernel also can be compiled and used. Read about it in the UML Project webpage.
Each UML needs a root filesystem to boot (maybe a conventional or COWed copy of a master one). You are strongly encouraged to preserve a master filesystem that never will be used to boot UMLs. The UMLs would boot with copies of this master filesystem (actual copies or COWed copies).
The filesystem have to acomplish some requeriments:
/dev/udb1 /opt ext2 defaults 0 0
Such filesystem acomplishing all requeriments can be built from the scarth (see UML web for details) of fitting one of the availables filesystem of the UML Project web page. Anyway, the easiest option is to download the filesystem used for the tutorial.
Filesystem files can be mounted (but do not mount filesystems in use by any UML; risk of corrupting the file filesystem is very high in that case) as loopback devices. For example:
mount -o loop root_fs_tutorial /mnt
It not a requeriment of vnumlparser.pl itself but the files needed to support <start> and <stop> operation must be in the filesystem (using <filetree> to copy it at simulation time is another option). For example, if you have in your VNUML source file
<start type="verbatim">/usr/bin/testprogram</start>
the /usr/bin/testprogram executable file must be in the UML filesystem at starting simulation time.
This section describes is and overview about how VNUML can be used to build and test simulations. We can considerate a working cycle, made up the following phases:
Notes:
In a VNUML file, there are three kinds of tags:
VNUML source file can be edited between simulation to modify simulation tags (that is: <filetree>, <start> and <stop>). So, simulation can be redefined on the VNUML file between simulation cycles. However, do no edit other tags because can lead to unpredectible and erroneous behaviour.
This section describes vnumlparser.pl user interface. The parser is a Perl script that it called from a shell command-line (it is recommened to put vnumlparser.pl file within console command path).
Following is the brief descriptive (but uselful) usage message when vnumparser.pl is executed with wrong arguments:
Usage: vnumparser.pl -t VNUML_file [-o prefix] [-m mount_point] [-c vnuml_dir]
[-T tmp_dir] [-k] [-i] [-v] [-g]
vnumparser.pl -s VNUML_file [-T tmp_dir] [-M vm_list] [-k] [-i] [-v] [-g]
vnumparser.pl -p VNUML_file [-T tmp_dir] [-M vm_list] [-k] [-i] [-v] [-g]
vnumparser.pl -r VNUML_file [-T tmp_dir] [-M vm_list] [-k] [-i] [-v] [-g]
vnumparser.pl -d VNUML_file [-c vnuml_dir] [-F] [-T tmp_dir] [-k] [-v] [-i] [-g]
vnumparser.pl -V
Mode:
-t VNUML_file, build topology (using VNUML_file) as source
-s VNUML_file, start simulation (using VNUML_file) as source
-p VNUML_file, stop simulation (using VNUML_file as source)
-r VNUML_file, restart simulation (using VNUML_file as source)
-d VNUML_file, destroy current simulation (using VNUML_file as source)
-V, show program version and exits.
Options:
-k, skips XML validation in VNUML_file (warning: it is not recommended)
-o prefix, dump UML boot messages output to files (using given prefix in pathname)
-m mount_point, use mount_point as mount point to configure UML filesystem (default is /mnt/uml)
-c vnuml_dir, vnumlparser.pl working directory (default is /var/vnuml)
-F, force stopping of UMLs (warning: UML filesystems may be corrupted)
-i, interactive execution (in combination with -v mode)
-v, verbose mode on
-g, debug mode on (overrides verbose)
-T tmp_dir, temporal files directory (default is /tmp)
-M vm_list, start/stop/restart simulation in vm_list UMLs (a list of names separated by ,)
The parser runs in five diferent modes: build topology (-t mode), start simulation (-s), stop simulation (-p) and destroy simulation (-d). There is an aditional mode, the restart mode (-r), that is a combination of -s and -p executed in sequence. There is also a pseudo-mode -V that shows program version and exits.
Switch -t.
The objetive of this mode is to build a new scenario. If the same escenario has been built before (identified with <simulation_name>) the parser exits inmediatelly, nothing is done.
Building topology creates several virtual interfaces (see later) and several virtual bridges (see later) in the host enviroment, that exists while the scenario is running and are destroyed during destroy topology mode.
Note that UML booting process can take a while, depending of how much virtual machines have the simulation and the physical resources of the host.
Mode -t allows several exclusive optional switches when calling vnumlparser.pl:
Switches -s (for starting), -p (stopping) and -r (restarting).
Both starting and stopping modes are very similar (-r mode is just a concatenation of both) so they will described together. The main diference is that in start simulation mode vnumlparser.pl executes commands defined with <start> tags, while in stop simulation mode <stop> tag is used. Previous to command executioni, files are copied from host to UMLs using <filetree> tag.
These modes can be used only during the life cycle of the scenario. That is, the scenario must have been booted before using -t mode. Moreover, UMLs have to be ready to receive commands (managemente interface up and sshd daemon listening in all UMLs). The parser check this, and exits doing nothing if the check fails.
The order in which <start> or <stop> commands appear it is the same order in which they would be executed in the UML or host.
This modes uses SSH to send commands to the UMLs. So, <ssh_key> is highly recomended to avoid typing the password with each SSH access.
Due to problems of the 'ssh' command, vnumlparser.pl may block when executing the UML commands backgrounded with '&'. In this case, press Ctrl+C to unblock and continuing executing commands. Anyway, the blocking can be avoided redirecting input and output of the backgrounded process to /dev/null. For example:
nohup /usr/bin/hello </dev/null >/dev/null 2>&1 &
(See at http://www.slac.stanford.edu/comp/unix/ssh.html for a detailed description of the ssh problem).
Note that >, < and & characters are forbidden in a XML file, so you need to escape them. The actual line (inside a <start> tag, for example) should be something like the following:
<start type="verbatim">nohup /usr/bin/hello </dev/null >/dev/null 2>&1 &</start>
An alternative to escaping special characters if using type="file". Commands in specified in the file don't need to be escaped.
Modes -s, -p and -r allows several exclusive optional switches when calling vnumlparser.pl:
vnumlparser.pl -r sim.xml -M uml1,uml3,uml6only restarts virtual machines named uml1, uml3 and uml6, leaving all other virtual machines unaltered. Note that, no matter if -M is used, the simulation is always started/stopped/restarted in the host.
Switch -d.
This mode ends the scenario lifecycle, halting the virtual machines and destroying virtual interfaces and bridges created during build topology mode (-t switch). After a sucessful -d mode, the scenario have to be rebuilded using -t mode. Note that destroying topology does not destroy the filesystems of the UMLs.
These modes can be used only during the life cycle of the scenario. That is, the scenario must have been booted before using -t mode. Moreover, UMLs have to be ready to receive commands (management interface up and sshd daemon listening in all UMLs, except when -F switch is used). The parser checks this, and exits doing nothing if the check fails.
The normal destroy topology mode (when not usignt -F switch) uses SSH to send halting command to the UMLs. So, <ssh_key> is highly recomended to avoid typing the password with each SSH interaction.
Note that UML halting process can take a while, depending of how much virtual machines the simulation have and the physical resources of the host.
Mode -d allows several exclusive optional switches when calling vnumlparser.pl:
The following optional switches are common to all vnumlparser.pl execution modes:
When building a topology (-t switch) a set of virtual interfaces are created in the host enviroment. The 'ifconfig' command will show you all of them (in additon to any other interface that the host would have).
There are three kinds of interfaces managed by vnumlparser.pl:
Virtual network connectivity is achived trought virtual brigeds configured in the host enviroment. Using 'brctl show' in the host will show what bridges exists (one for each virtual network defined with <net>) and what UML interfaces are connected to each bridge (virtual network).
The default vnumlparser.pl working directory is /var/vnuml, although this value can be changed using -c switch. The parser stores certain files in this directory, whose structure will be outlined following.
During start and stop simulation modes (-s and -p switches), the commands specified with <start> and <stop> (either verbatim or readed from a file) are printed to a script file in the host enviroment (by default /tmp directory, althought this can be overriden with -T).
These files have a header like that:
#!/bin/bash # UML start commands file generated by vnumlparser.pl 1.2.1a at Thu Jul 31 00:07:53 CEST 2003 (commands)
The first line is the shell that executes this script (the value of the optional <shell> tag, by default /bin/bash).
The name of this file is vnuml.name.mode, where name is the name of the virtual machine where the file will run and mode is "start" or "stop", depending of the parser execution mode.
The so generated files are installed in the virtual machines (through 'scp' command, previous script files -with the same name- are so overriden) in the /root directory and then executed (through 'ssh'). So, /root in the UML filesystem contains the scripts executed during last start and stop simulation modes (it can be useful for debugging purposes).
Note that this files are also generated when no <start> or <stop> have been defined for the virtual machine. However, in this case the file is empty (only the header).
VNUML allows to run several concurrent simulations, each one described in a separated VNUML source file. However, to avoid interference between simulations, the following rules have to be followed:
Versions 1.2.1 and before do not perform special checking about whether the aboves restrictions are being acomplished or not. So, it is under user's responsability. Not to follow these rules can lead to unpredectible and erroneous behaviour.
Note that, to avoid race conditions, no more than one instance of vnumlparser.pl can be execute at the same time. To guarantee this, a global lock file (LOCK in the VNUML working directory) is used. The first action of vnumlparser.pl is to check the existence of this file: if exitst vnumlparser.pl exits doing nothing. In the other case, the file is created. When finishing, vnumlparser.pl removes the LOCK as last action.
If a crash occurs while vnumlparser.pl is in execution (for example, an accidental power down in the host) this file may not be removed. In this case, you have to manually remove it or vnumlparser.pl will not work.
VNUML uses as "interconnection points" among virtual machines the networks specified with <net> tags. A physical host interface can be assigned to one of these networks with the attribute external so all the virtual machines connected to this virtual network are also bridged (level 2 interconnection) to the external network. The external interface can be a conventional one (eth0, eth1, etc.) or a VLAN (using vlan attribute), configured by vnumlparser.pl.
If the external in a <net> has some configuration (IP address, networks mask and gateway) it is lost when building topology (-t mode), so if you want preserve it use <ipv4> and <route> whithin <hostif> and <host> (note that the configuration is not for the ethX interface, but the associated bridge; anyway, from a functional point of view, there is no difference). When destroying topology (-d mode) configuration is also lost. If you want that vnumlparser.pl restore it, use <physicalif> tag.
Note that if any TCP session (for example, a SSH session) is established in the host in a external interface that VNUML parser will configure it may get broken. In such cases, just reconnect after a few moments. Anyway, be careful: a wrong configuration of VNUML can lead to lost of network connectivity to the host from the external networks (very important if you log in your host throught network instead logging in through a keyboard console).
Due to unstability, destroying a scenario using -d mode can fails. This situation is identified when vnumlparser.pl waits forever to UML halting while Linux processes remains in the user processes space. To kill the parser process you can bind useful 'kill $(pidof /usr/bin/perl)' (be careful: this kills all Perl processes!).
Note that each proccess executing in UML processes space is mapped to the actual host kernel user space. You can get a list of the UML processes in a given moment using:
ps -aux | grep linux | cut -c 1-100
A hanging in -d mode would be caused by misconfiguration of sshd dameon inside UML or in the managemente interface. Following are described procedures to deal with this situation. Anyway, use it only as a last resort measure, due to they can lead to UML filesystem corruption.
touch /var/vnuml/crashed-one/lock
To install software (programs) in a UML filesystem two kind of procedures can be used:
mount -o loop root_fs /mnt cd /usr/local/src/zebra ./configure --prefix=/mnt make make install make clean make distclean umount /mnt