VNUML User Manual
version 1.3

Authors:
Fermín Galán (galan at dit.upm.es)
David Fernández (david at dit.upm.es)

November 14th, 2003

This section introduces some basic concepts which are important to know in order to use VNUML tool to design, build and run tests over simulated scenarios.

A typical working cycle using VNUML is made up of the following phases:

• Desing phase. First of all, the user has to desing a simulation scenario. For that, several aspects have to be considered in advance: the number of virtual machines, the topology (network interfaces in each machine and how they are connected), what processes each virtual machine will execute, etc. Note that the whole simulation runs in the same physical machine (named host). The host can be part of the simulation or not (VNUML allows both options).
• Implementation phase. Once the simulation scenario has been designed, the user has to write the source VNUML file describing it. This is an XML file, whose sintax and semantic is described in the VNUML Language Reference. There are three kinds of tags in VNUML: structural tags, with few or none semantics; topology tags, used to describe the topology; and simulation tags, used to describe simulation parameters and commands. See more information about the different classes of tags later in this manual.
• Execution phase. Once the user has the VNUML file written, he has to run vnumlparser.pl against it in order to build and manage the simulation scenario. Execution phase consists in four steps, each one corresponding to an option or mode of vnumlparser.pl:
  1. Build Scenarion (mode -t). The parser creates the virtual networks that will interconnect the virtual machines and the host, and later boots and configures the virtual machines defined, adding IP addresses, static routes or any other network related parameters. This step is very intensive in CPU consumption, due to UML booting process.
  2. Simulation Start (mode -s). Once the scenario has been built using -t mode, the simulation processes are started inside each virtual machine. Basically in this step, the parser takes the commands defined in the VNUML file under each virtual machine section and executes them using a remote shell from the host.
  3. Simulation Stop (mode -s). This step is basically the inverse process of the previous one. The user defines a set of commands whose goal is to stop the simulation processes started with -s mode, in order to take each virtual machine to the initial state.
  4. Release Scenario (mode -d). In this final step, all the simulation components created using -t mode (UMLs, virtual networks, etc.) are cleanly released. This step is also very intensive in CPU consumption, due to UMLs shutdown process.

The typical life cycle with VNUML will consist on executing step 1 to create the scenario, executing steps 2 and 3 to start and stop the simulation processes as many times as desired or needed, and finally executing step 4 in order to release the scenario.

This approach makes VNUML a flexible tool, allowing to perform several simulations over the same scenario, without having to start and stop it each time (which, as it was mentioned before, is a costly task in terms of CPU and time). Even in some cases, steps 2 and 3 could not be executed, for example, when the user prefers to interact directly with the virtual machines, instead of defining the commands in VNUML language and using vnumlparser.pl to manage them.

Each execution of step 2 followed by step 3 is named a simulation cycle of the scenario. In a similar way, we name the scenario life cycle to the period of time between the execution of steps 1 and 4. Therefore, each life cycle will include zero or more simulation cycles. The following figure represents graphically the different states and the transitions between them.

Note that ending a life cycle does not destroy the filesystem that are used by the virtual machines (in the same way that the filesystem of a actual machine is not erased whenever the machine is powered down).

Note also that in steps 2 and 3, vnumparser.pl does not perform any interpretation of the simulation tags (see Types of Tags later in this document). It just executes the commands defined in the VNUML file by the user as they are. The user is therefore responsible for the correctness of that commands. On the contrary, all tags used when building or releasing the scenario are checked by the parser before execution.

Several simulation scenarios can be executed simultaneously in the same host, as long as certain rules are followed (see Concurrent Simulation Scenarios for more details). Concurrent simulations can be executed isolated or even sharing connections among them and the host.

1.1. Types of Tags

There are three types of tags in a VNUML file:

• Structural tags, that are used to define the structure of the file, organizing it in different sections, each one containning other specific tags. There are five tags of this type: <vnuml>, <global>, <vm>, <boot> and <host>. VNUML parser uses them to know the structure of the description file in any execution mode.
• Topology tags, that carry the semantic related to the scenario topology. They are used during the buildng and releasing scenario modes (-t and -d modes of vnumlparser.pl) and ignored during start and stop simulation modes (-s, -p and -r modes of vnumlparser.pl). There are 18 tags of this type: <ssh_key>, <automac>, <netconfig>, <host_mapping>, <tun_device>, <net>, <filesystem>, <mem>, <kernel>, <con0>, <if>, <hostif>, <mac>, <ipv4>, <ipv6>, <physicalif>, <route> and <forwarding>.
• Simulation tags, that carry the semantic related to the simulation. They are used during start and stop simulation modes (-s, -p and -r modes of vnumlparser.pl) and ignored during build and release scenario modes (-t and -d modes of vnumlparser.pl). There are three tags of this type: <filetree>, <start> and <stop>.

Tags <version>, <simulation_name>, <ip_offset> and <shell> can be considered either topology or simulation tags, due to the fact that they are used in all modes.

VNUML source file can be edited between simulations, but only to modify simulation tags (that is: <filetree>, <start> and <stop> tags). In this way, the simulation behaviour and objectives can be changed between simulation cycles. However, do no edit other tags because it can lead to unpredictible and erroneous behaviours.

This section describes in detail vnumlparser.pl usage options. Basically, the parser is a Perl script that it is called from a shell command-line (it is recommened to put vnumlparser.pl file within console command path).

If you call the parser without arguments you get the following brief (but uselful) description of its modes and options:

Usage: vnumlparser.pl -t VNUML_file [-o prefix] [-m mount_point] [-c vnuml_dir]
                 [-T tmp_dir] [-k] [-i] [-S scan_mode ] [-w delay] [-B] [-v] [-g]
       vnumlparser.pl -s VNUML_file [-T tmp_dir] [-M vm_list] [-k] [-i] [-S scan_mode ] [-B] [-v] [-g]
       vnumlparser.pl -p VNUML_file [-T tmp_dir] [-M vm_list] [-k] [-i] [-S scan_mode ] [-B] [-v] [-g]
       vnumlparser.pl -r VNUML_file [-T tmp_dir] [-M vm_list] [-k] [-i] [-S scan_mode ] [-B] [-v] [-g]
       vnumlparser.pl -d VNUML_file [-c vnuml_dir] [-F] [-T tmp_dir] [-k] [-i] [-S scan_mode ] [-B] [-v] [-g]
       vnumlparser.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)
       -S scan_mode, the way UML readiness is scanned (default is 0, socket style)
       -w delay, waits delay seconds between UMLs booting (defult is wait no time)
       -B, blocking mode
       -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 ,)

Since version 1.3.1: new mode (purge mode, -P) and a new optional switch (-e) for the building topology mode (-t).

Usage: vnumlpaser.pl -t VNUML_file [-o prefix] [-m mount_point] [-c vnuml_dir]
                 [-T tmp_dir] [-k] [-i] [-S scan_mode ] [-w delay] [-B]
                 [-e screen_file] [-v] [-g]
       ...
       vnuml -P VNUML_file [-T tmp_file] [-k] [-i] [-v] [-g]
Mode:
       ...
       -P VNUML_file, purge simulation (WARNING: it will remove UML cowed filesystems!)
Options:
       ...
       -e screen_file, make screen configuration file for pts devices

The parser can be invoked using one of the following four diferent modes: build topology (-t mode), start simulation (-s), stop simulation (-p) or destroy simulation (-d). There is an aditional mode, the restart mode (-r), that is a combination of -s and -p executed in sequence. Besides, there is a pseudo-mode, -V, that shows program version and exits. The following sections describe each of these modes in detail.

You must be root user to execute vnumlparser.pl (except in debug execution mode, with -g switch).

Since version 1.3.1: there is an additional mode: purge mode (-P mode).

Since version 1.3.0, vnumlparser.pl supports SKAS mode.

2.1. Building a Simulation Scenario

To build a simulation scenario use switch -t. If the escenario (or another scenario with the same <simulation_name>) is already running, the parser exits inmediatelly.

During the scenario start-up process, several virtual interfaces and bridges are created in the host for the management of virtual machines (they are basically managed by sending commands through a ssh session from the host). This interfaces and bridges exists while the scenario is running, and are destroyed when the release scenario mode (-d) is called.

Note that building a simulation scenario can last long, because the UML booting process of each virtual machine is a slow process. The exact duration will heavily depend on the number of virtual machines, the root file system and the physical resources of the host.

The following optional switches can be used when invoking vnumlparser using mode -t:

• UML booting output (-o switch). UML booting process generates a lot of verbose output messages. Furthermore, when booting several UMLs concurrently, the output of all of them is mixed. The -o switch can be used to redirect booting output to files. The parameter after the switch specifies the name of the file where the output will be stored (the name of each virtual manchine will be sufixed to the filename to have each virtual machine log in a separate file). For example, '-o /tmp/delme' redirects output to /tmp directory (filenames prefixed by 'delme' string).
  Version 1.3.1: '-o /dev/null can be used to redirect to the null device.
  Since version 1.3.2: by default UML booting output is redirected to /dev/null. Using '-o /dev/null' is not neccesary and -o switch should be used only when redirection of the output to file is required.
• Boot delay (-w switch). When used, vnumlparser.pl waits when booting a UML before booting the following the amount of time specified, in seconds (for example, '-w 10' waits ten seconds). This switch is focused in situations when some UMLs could not boot properly when the topology is built (it depends of UML unstability related with certain host Linux distributions and kernels). This situation is detected when the sshd daemon of some UML doesn't start (vnumlparser.pl seems waitting forever in blocking mode, -B switch) and a short interbooting delay seems to fix the problem.
• Mountpoint (-m switch). Before booting each virtual machine, the parser has to temporarily mount UML filesystems to configure them. It uses /mnt/uml as the default mount point in the host filesystem, but -m switch can be used to override it.
  Since version 1.3.2-4: the default mountpoint can be changed with --with-mount-point option of configure when building the VNUML package.
• Working directory (-c switch). By default the working directory for vnumparser.pl is /var/vnuml. Using -c switch this default can be overriden. Read more about the VNUML working directory.
  Since version 1.3.2-4: the default working directory can be changed with --with-writedata option of configure when building the VNUML package.

Since version 1.3.1: new optional switch:

• Screen configuration (-e switch). Followed with a filename (for example, '-e /tmp/screen.conf'). When used, a file is generated (/tmp/screen.conf in the later example) with the configuration of the screen(1) command for the pts defined in the <con0> tags of the simulation file. This file is for using as -c argument of the screen(1) command:

  screen -c /tmp/screen.conf
  

2.2. Starting and Stopping Simulations

To start a simulation over and already running scenario use switch -s; to stop it use switch -p; and to restart it (that is, to stop it and inmediately start it again), use switch -r.

Both starting and stopping modes are very similar (-r mode is just a concatenation of both) so they will described together. Basically, the main diference between them is that in start simulation mode vnumlparser.pl executes commands defined with <start> tags, while in stop simulation mode <stop> tagged commands are executed.

Before executing start or stop commands, <filetree> tag can be used to copy files or directories from the host file system to the virtual machines ones, or viceversa. This tag is very useful to copy the configuration files needed by the applications to be started in each virtual machine.

To use these modes the scenario must have been already started using -t mode. Moreover, UMLs have to be ready to receive commands (management interfaces up and sshd daemon listening in all UMLs). The parser check this, exiting without doing anything if the check fails.

The order in which <start> or <stop> commands appear in the VNUML file is the order in which they are executed in the UML or host.

As the parser uses SSH to execute commands inside the UMLs, the use of <ssh_key> tag is highly recomended, in order to avoid having to type the password for each SSH access.

Due to some problems of the 'ssh' command, vnumlparser.pl may block when executing the UML commands backgrounded with '&'. In this case, press Ctrl+C to unblock it and continue the command execution. 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 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. For example, to include the previous command inside a <start> tag, you should write:

<start type="verbatim">nohup /usr/bin/hello &lt;/dev/null &gt;/dev/null 2&gt;&amp;1 &amp;</start>

An alternative to avoid having to escape special characters is to store the commands in a file and use the parameter type="file" inside the start or stop tag. Commands included in files do not need to be escaped.

The following optional switch can be used when invoking vnumlparser using modes -s, -p or -r:

• Virtual machine list (-M switch). By default, the starting/stopping/restarting is performed in all UMLs of the scenario. To restrict the actions to some virtual machines, use -M switch, specifing a list of comma separated virtual machine names after the switch. For example:

  vnumlparser.pl -r sim.xml -M uml1,uml3,uml6
  

  only 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.

2.3. Releasing an Scenario

To release a simulation scenario use switch -d.

This mode terminates the scenario lifecycle, by halting all virtual machines and destroying virtual interfaces and bridges created during the start-up mode (-t switch). After a sucessful -d mode, the scenario has to be rebuilt using -t mode. Note that destroying a scenario does not destroy the filesystems of the UMLs.

To use -d mode, the scenario must have been already started and all UMLs have to be ready to receive commands (management interface up and sshd daemon listening in all UMLs). The parser checks that, exiting without doing anything if the check fails.

As the parser uses SSH to execute the halt command inside each UML, the use of <ssh_key> tag is highly recomended, in order to avoid having to type the password for each UML.

Note that releasing a simulation scenario can take a long time, because the UML halting process of each virtual machine is a slow process. The exact duration will heavily depend on the number of virtual machines, the root file system and the physical resources of the host.

The following optional switches can be used when invoking vnumlparser using mode -d:

• Forced mode (-F switch). When using forced mode, UMLs are not stopped throught sshed halt command. Instead, halt is performed directly in the UML kernel (using mconsole to send a halting signal from the host). Disk caches are not synchronized in the UML filesystem before halting, so this option can lead to UML filesystem corruption. So it is highly recommened to use -F only in exceptional cases (see more information later in this manual).
• Working directory (-c switch). By default the working directory for vnumparser.pl is /var/vnuml. With -c switch this behaviour can be overriden. Note that if this switch is used, the working directory must be the same that the one used when building the scenario (-t mode). Read more about the VNUML working directory.
  Since version 1.3.2-4: the default working directory can be changed with --with-writedata option of configure when building the VNUML package.

2.4. Purging an Scenario

Only since version 1.3.1.

The main purpose of this mode (-P switch) is to automate deleting actions when a -d mode fails releasing a simulation.

When switch -P is used, copied and cowed filesystem in the simulacion directorio are permanently deleted. So, use purge mode carefully!

While purging a scenario the following actions are performed:

1. Forced release of the scenario (equivalent to -d with -F).
2. Kill (SIGTERM) all UML processes.
3. KIll (SIGKILL) all remaining UML processes.
4. Remove (rm) all files related with the simulation (usually in /var/vnuml/simulation_name/).

Warning: steps 2 and 3 produces the killing of all UML processes, not only those in the purged simulation. So, when you are purging a simulation, take care of cleanly terminate (-d mode) all the others simultations (if any) previously.

2.5. Common Switches

The following optional switches are common to all vnumlparser.pl execution modes:

• Blocking mode (-B switch). Used during build scenario mode, the parser blocks until all the virtual machined defined in the simulation are SSH ready (the default behaviour without -B is exist inmediately after the booting of the last virtual machine). Used during start or stop simulation or release scenario modes, the parser waits for the virtual machines if they are not yet ready (the default behaviour without -B is exist inmediately if at least one is not ready).
• Scanning mode (-S switch).. Select the way of UML readiness checking: socket style (with '-S 0') or ps style (with '-S 1'). The default behaviour is socket style and it is recommended not to change it, because ps style is not compatible with SKAS mode.
• Ignore XML validation (-k switch). Use it to avoid the XML DTD-based validation when parsing source VNUML file. Due to the fact that vnumlparser.pl heavyly relies in the correctness of the VNUML source file, -k switch is strongly not recomended.
  Since version 1.3.2: -k switch is no longer supported.
• Verbose mode (-v switch). It tells vnumlparser.pl to show each command result after executing it. Prompt 'host> ' is used when executing command in the host enviroment. When executing commands in a UML (usually in deferred way, throught a script) the name of the virtual machine is used as prompt. The verbose output is very useful to know what vnumlparser.pl is exactly doing and debug it, so using -v is recommended.
• Debug mode (-g switch). Tells vnumlparser.pl not to actually execute commands, only show them as in verbose mode. A 'D-' is added to any prefix prompt in debuging output. When -v and -g are used simultaneously, -g takes preference.
• Interactive execution (-i switch). Used in combination with -v switch (in other case, it is silently ignored). When using interactive execution mode, a key must be pressed after each command is executed by vnumlparser.pl. So, the parser actions can be followed step-by-step.
• Temporal directory (-T switch). Use to define the directory used for temporal files (/tmp is used by default). Version 1.3.0 and before uses this directory in -s and -p modes to store commands scripts that will be installed in the UMLs for execution (see Start and stop commands temporal files).
  Since version 1.3.2-4: the default temporal directory can be changed with --with-tmp option of configure when building the VNUML package.

2.6. Host Interfaces and Virtual Bridges

When building a scenario with -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:

• Management interfaces. They are named 'name-eth0', where name is the name of a virtual machine. This interface is a point-to-point connection (using netmask /30) from the host to the virtual machine (at the virtual machine side, the name of the interface is 'eth0'). It has a IPv4 management address (whose particular value is choosen by vnumlparser.pl using the <ip_offset>; when this value is 0, management addresses starts from 192.168.0.1). If the address at host side is IP, the address at UML side is IP+1 (for example, if host address is 192.168.0.1 a 'ping 192.168.0.2' executed in the host will check the connection to the UML through the management interface). This interface is used by vnumlparser.pl to send commands to the virtual machines during start and stop simulation and non-forced release scenario modes (-s, -p and -d switches). It also can be used by the user to access the virtual machine throught SSH.
• UML interfaces. They are named 'name-ethn', where name is the name of a virtual machine and n is an integer number different from 0. They are virtual interfaces used to configure virtual network connectivity by adding them to virtual networks (at virtual machine side, the name of the interface is 'ethn'). They do not have IP addresses in host enviroment.
• Virtual network interfaces. With name net, where net is the name of certain virtual net (name attribute of <net> tag). These interfaces are the implementation (using virtual bridges) of the virtual networks defined in simulation scenarios. They are used also (with a network address and a netmask) to connect the simulation scenario with external networks (external attribute of <net> tag)

As mentioned, virtual network connectivity is achived trough the use of virtual bridges configured in the host enviroment. The command 'brctl show' executed 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).

2.7. Direct login to UMLs

By default, virtual machines does not have console access, the only way to login is using SSH through the managament interface.

This behaviour can be overriden using <con0> tag. Specifing xterm in a graphical enviroment or a tty, the UML outputs a login prompt to the specified device.

When specifing a pts, the number of pseudoterminal can be found using uml_mconsole on the UML. For example, if the simulation name is 'tutorial' and the virtual machine name where pts have been used is 'uml2'

uml_mconsole /var/vnuml/tutorial/uml2/mconsole config con0

returns the pseudoterminal filename. This value can be used with screen command to get a console to the UML. For example, if the pseudoterminal would be /dev/pts/6:

screen /dev/pts/6

Since version 1.3.1: using -e switch while building the scenario (-t mode) the parser can get the pts devices of the UMLs automactly and put it in a file (whose name is given as the argument of -e switch) that could be use as -c argument of the screen(1) command.

2.8. Working Directory

The default vnumlparser.pl working directory is /var/vnuml; this value can be changed using -c switch. The parser stores the following files in the working directory:

• /var/vnuml/LOCK. This is the global lock file. It is created when vnumlparser.pl starts and deleted when it finishes an execution. Before starting, vnumlparser.pl checks that the file does not exits. This method ensures that no more than one instance of vnumlparser.pl is running at a any time.
• /var/vnuml/if_name, where if_name is the name of a certain external (external attribute in the <net> tag) network interface (in the host enviroment). This file is a counter to record how many simulations are using that interface, increased and decreased by vnumlparser.pl when creates (-t mode) and releases (-d mode) a scenario, respectively. The parser uses this information to know when it can remove virtual networks from a bridge. The non existence of this file is an implicit 0 value.
• /var/vnuml/simulation_name/, where simulation_name is the name of a certain simulation (<simulation_ name>). This is the directory where the parser stores certain files related with the simulation. Note that the directory is not deleted when scenario lifecycle ends, due to the fact that some files (for example COW patches) could be used the next time the scenario is built.
• /var/vnuml/simulation_name/lock. As long as this file exists, the scenario is running. The parser creates this file during build scenario mode (-t switch) and deletes it during release mode (-d switch). It is used by vnumlparser.pl for management tasks (to not build twice the same simulation, not to take starting and stopping simulation actions if the scenario is not running, etc.).
• /var/vnuml/simulation_name/name_fs, where name is the name of a certain virtual machine (name attribute in the <vm> tag) of that simulation. This file is the copy of the filesystem when type="copy" is used in the <filesystem> of the virtual machine.
• /var/vnuml/simulation_name/name_cow_fs, where name is the name of a certain virtual machine (name attribute in the <vm> tag) of that simulation. This file is the COWed copy of the filesystem when type="cow" is used in the <filesystem> of the virtual machine.
• /var/vnuml/simulation_name/name_opt_fs, where name is the name of a certain virtual machine (name attribute in the <vm> tag) of that simulation. This file is a small (about 1 MByte) auxiliar filesystem used to configure the virtual machine at building scenario time (-t switch) when type="cow" is used in the <filesystem> of the virtual machine.
• /var/vnuml/simulation_name/name/, where name is the name of a certain virtual machine (name attribute in the <vm> tag) of that simulation. This directory is where the mconsole socket lives (a UNIX socket that uml_mconsole tool uses to send commands directly to the UML kernel). The parser use it to send halt commands to the UMLs when using forced destroy scenario mode (-d with -F switches), althought it could be also be used by the user.

Since version 1.3.2-4: the default working directory can be changed with --with-writedata option of configure when building the VNUML package.

2.9. Start and Stop Temporal Command Files

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 to /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.3.0 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.

These files are installed in the virtual machines (through 'scp' command; therefore previous copies of script files -with the same name- are 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 these files are also generated when no <start> or <stop> have been defined for the virtual machine. However, in this case the files are empty (they only contain headers).

2.10. Concurrent Simulation Scenarios

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:

• Each simulation must have a diferent name (<simulation_name>).
• Virtual machines and network names (name attribute of <vm> and <net>) must be unique for all simulations. The same name in diferent simulations is not allowed.
• Management IP addresses for the management interface must not overlap in two or more simulations. To avoid this, use <ip_offset> with a different and suitable value in each simulation (it depends of the number of UMLs in each simulation). For example <ip_offset>0</ip_offset> in the one simulation, <ip_offset>10</ip_offset> in another.
• To interconnect machines of different simulations to the same network, the same network name have to be defined in both simulations. Thas it, the <net> of both simulations for the desired networks must be the same.
• Avoid using duplicated MAC addresses. If using <automac> uses a diferent offset in each simulation.
• Due to the fact that all simulations share the host enviroment (<host> tag), some conflicts could arise. The recomendation is not to use <host> tag at all whenever possible.

Versions 1.3.0 and before do not perform special checking about whether the above restrictions are being acomplished or not. So, it is under user's responsability. Not following these rules can lead to unpredectible and erroneous behaviours.

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.

2.11. External Connections and VLAN support

As mentioned before, VNUML creates virtual networks to implement the networks defined with <net> tags. These networks allow virtual machines to interchange traffic among them and can optionally be connected to the physical network interfaces of the host (using external attribute). In this way, virtual machines can gain access to external networks.

Besides, external interfaces can be physical interfaces (eth0, eth1, etc) or subinterfaces based on VLANs (vlan attribute must be used in this case).

If the interface used in a <net> with a external attribute has some configuration (IP address, networks mask and gateway), it will be lost when building the scenario (-t mode). Therefore, if you want to preserve it, you have to use <ipv4> and <route> tags within <hostif> and <host> (note that the configuration is not for the ethX interface, but for the associated bridge; anyway, from a functional point of view, there is no difference). When releasing the scenario (-d mode), the configuration is also lost. If you want vnumlparser.pl to restore it, use <physicalif> tag.

Note that if any TCP session (for example, a SSH session) is established in the host through an 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).

2.12. How to release a scenario when -d fails

Due to several possible problems, releasing a scenario using -d mode can fail. This situation can be identified by the fact that vnumlparser.pl waits forever to UML halting while Linux processes remains in the user processes space. To kill the parser process you can find useful the following command: 'kill $(pidof /usr/bin/perl)' (be careful: this kills all Perl processes!).

Note that the UML processes are mapped to the actual host kernel user space (in a one-by-one basis if SKAS is not being used). You can get a list of the UML processes at any moment using:

ps axw | grep linux | cut -c 1-100

NOTE: 'grep linux' in the commands before assumes that your kernel name is 'linux' or linux-compossed (like 'linux-2.4.22um12'). If you are using other name in the <kernel> tag, you have to use the appropiated grep expression.

vnumlparser.pl hanging in -d mode could be caused by a misconfiguration of sshd daemon inside UML or in the management interface. The following procedure deals with this situation (use it only as a last resort, it can lead to UML filesystem corruption):

1. First of all try using forced destroy topology mode: -d mode with -F switch.
2. If it fails, the mconsole could be broken. Try using: 'killall linux'
3. Some processes can ignore the SIGTERM signal. To kill the remaining process (if any) use 'kill -9 $(pidof linux)'.
4. Once all linux processes have been killed, you need to clean all additional files and structures used to create the scenario. To do so, you can use again -d mode with -F switch. The parser may complain telling that simulation does not exists. In this case, you have to regenerate the simulation lock file creating the 'lock' in the simulation directory in the VNUML working directory. For example, if the <simulation_name> is "crashed-one" and the VNUML working directory is /var/vnuml (the default), just type:

   touch /var/vnuml/crashed-one/lock
   

Since version 1.3.1: purge mode automates the procedure described above.

Sooner or later, you will want to build your own customized UML kernel to use in VNUML simulations. This section explains how to do it.

1. Get Linux kernel sources, usually from http://www.kernel.org/. Uncompress the source tarball into same place (for example, /usr/src/linux-2.4.19).
2. Get UML kernel patch for the kernel version that you want to use. The official website is http://user-mode-linux.sourceforge.net/dl-sf.html. Apply the patch to the kernel sources. For example:

   cd /usr/src/linux-2.4.19
   cat uml-patch-2.4.19-13.bz2 | bunzip2 - | patch -p1
   

3. Configure the kernel. This process is the same than configuring a conventional Linux kernel. Note the required ARCH=um switch.

   make menuconfig ARCH=um
   

4. Compile the kernel.

   make dep ARCH=um
   make linux ARCH=um
   

   This 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
   

Kernel modules can also 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 will never be used to boot UMLs. UMLs should always boot from copies of this master filesystem (actual copies or COWed copies).

Filesystem used with VNUML have to fullfill some requeriments:

• An empty directory /opt must exits.
• A symbolic link in the rc.d tree pointing to /opt/umlboot must exist (for example, if you are booting at runlevel 3, the symlink could be /etc/rc.d/rc3.d/S11bootuml).
• A symbolic link /root/.ssh pointing to /opt must exist (if /root/.ssh exists as a regular directory, remove it and make the symlink) if you want to use <ssh_key> (recommended).
• The following line as part of the automount configuration in /etc/fstab (this line is really needed for COW filesystem, but doesn't hurt in other cases).

  /dev/udb1     /opt     ext2     defaults    0 0
  

• SSH daemon (sshd) must be started automatically at boot time (using the usual symlink in the rc.d tree). It's strongly recommened to use -u0 option (usually this is configured in the script that boots sshd: /etc/init.d/sshd) to avoid DNS queries that could delay SSH access to the UML. Not to have a SSH daemon will lead to an autistic UML!
• Console tools must be accesible from the console command path (they are called from manage scripts built by VNUML parser without prefixing the command with the absolute pathname):
  • ifconfig
  • route
  • echo
  • hostname
  • halt
  • I'm forgetting something?

Such filesystem acomplishing all requeriments can be built from scratch (see UML web for details) or by modifying one of the available filesystem in the UML Project web site. Anyway, the easiest option to start using VNUML is to download the filesystem used for the tutorial.

Filesystem files can be mounted as loopback devices (be careful not to mount filesystems in use by any UML; the risk of corrupting the file filesystem is very high in that case). For example:

mount -o loop root_fs_tutorial /mnt

It is not a requeriment of vnumlparser.pl itself, but it is important to note that the files needed to support <start> and <stop> operation must be in the filesystem. For example, if you have in your VNUML source file

<start type="verbatim">/usr/bin/testprogram</start>

it is obvious that the /usr/bin/testprogram executable file must be in the UML filesystem when starting the simulation (remember that you can copy files using <filetree> tag).

To install new software (programs) into a UML filesystem, you can use two procedures:

• Run a simulation, login into the UML through ssh and install the software from inside the UML itself (compiling with gcc, installing with RPM, etc). Note that you depend on the availabilityof supporting tools in the UML filesystem to install the software. For example, you need gcc to compile source code, you need a Red Hat or SuSE filesystem to install RPMs, apt in Debian etc.
• Compile the software in the host and install the binaries in the UML filesystem (previously mounted). For example, to install Zebra 0.93a from the host enviroment:

  mount -o loop root_fs /mnt
  cd /usr/local/src/zebra
  ./configure --prefix=/mnt
  make
  make install
  make clean
  make distclean
  umount /mnt