VNUML User Manual
version 1.6

Fermín Galán (galan at
David Fernández (david at
Casey T. Deccio (ctdecci at

August 12th, 2005

Virtual Network User Mode Linux

1. VNUML Simulation Philosophy
   1.1. Types of Tags
2. VNUML Parser Usage
   2.1. Building a Simulation Scenario
   2.2. Execute Commands
   2.3. Releasing a Simulation Scenario
   2.4. Purging a Simulation Scenario
   2.5. Common Switches
3. Advanced topics
   3.1. Host Interfaces and Virtual Bridges
   3.2. Virtual Networking
   3.3. Hostfs Filesystems
   3.4. UML Readiness
   3.5. Direct login to UMLs
   3.6. Working Directory
   3.7. Privilege Separation
   3.8. Temporal Command Files
   3.9. Concurrent Simulation Scenarios
   3.10. External Connections and VLAN support
   3.11. How to release a Scenario when -d fails
4. Building a Customized Kernel
5. Filesystem Requirements
6. Installing Software in UML filesystems

1. VNUML Simulation Philosophy

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

VNUML is executed in a GNU/Linux host. The tool can be used by conventional users (i.e, no-root users), but when running as root additional features can be used.

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

  • Design phase. First of all, the user must design 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 may or may not be part of the simulation (VNUML provides functionality for both options), when root runs the tool. When a conventional user runs the tool, host can not be part of the simulation.
  • Implementation phase. Once the simulation scenario has been designed, the user must write the source VNUML file describing it. This is an XML file, whose syntax and semantic is described in the VNUML Language Reference. There are three kinds of tags in VNUML: structural tags, with few or no 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 written the VNUML file, he must run against it in order to build and manage the simulation scenario. Execution phase consists of four steps, each corresponding to an option or mode of
    1. Build scenario (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. The UML boot process makes this step very processor intensive.
    2. Execute commands (mode -x). Once the scenario has been built using -t mode, you can run command sequences on it. Basically in this step, the parser takes the commands defined in <exec> tags in the VNUML definition file and executes them using a remote shell from the host. Several command sequences may be defined (e.g., one to start routing daemons, another to perform a sanity check in the virtual machines, etc.), specifying which to execute when using -x switch.

      Note for old users: if you have used 1.4.0 or a previous version, you may have used the starting simulation and the stopping simulation modes (-s and -p switches, respectively). The new execution mode (-x switch) is much more flexible, because you may use to run whatever command sequence you want: the start-stop simulation cycle paradigm is not suitable for all cases. Anyway, what happens with -s, -p, and -r modes and with <start> and <stop> tags in version 1.6? They still work, but are deprecated, so you are strongly encouraged to use <exec> instead.
    3. Release Scenario (mode -d). In this final step, all the simulation components created using -t mode (UMLs, virtual networks, etc.) are cleanly released. The UML shutdown process makes this step also very processor intensive.

The typical life cycle of VNUML consists of executing step 1 to create the scenario, executing step 2 to execute commands as many times as desired or needed, and finally executing step 3 in order to release the scenario.

This approach makes VNUML a flexible tool, allowing multiple simulations to be run over the same scenario, without having to release and rebuild it each time (which, as it was mentioned before, is a costly task in terms of CPU and time). The user may also prefer to interact directly with the virtual machines, rather than solely using pre-defined command sequences in step 2.

Note that releasing a scenario (step 3) does not destroy the filesystems that are used by the virtual machines (in the same way that the filesystem of an actual machine is not erased whenever the machine is powered down). The filesystem when using COW or copy, can be reseted using purge mode (-P).

Note also that in steps 2, 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 (step 1 and 3) 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:

Tags <version>, <simulation_name>, <vm_mgmt>, <mgmt_net>, 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 commands executions (-x mode), but only to modify simulation tags (that is: <ssh_version>, <basedir>, <filetree>, <start>, <stop>, and <exec> 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 unpredictable and erroneous behaviours.

2. VNUML Parser Usage

This section describes in detail usage options. Basically, the parser is a Perl script that it is called from a shell command-line (it is recommended to put file within console command path, typically /usr/local/bin/

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

Usage: -t VNUML_file [-o prefix] [-c vnuml_dir] [-u user]
                 [-T tmp_dir] [-i] [-S scan_mode ] [-w timeout] [-B]
                 [-e screen_file] [-v] [-g] -x cmd_seq@VNUML_file [-T tmp_dir] [-M vm_list] [-i] [-S scan_mode ] [-B] [-v] [-g] -r VNUML_file [-T tmp_dir] [-M vm_list] [-i] [-S scan_mode ] [-B] [-v] [-g] -d VNUML_file [-c vnuml_dir] [-F] [-T tmp_dir] [-i] [-S scan_mode ] [-B] [-v] [-g] -P VNUML_file [-T tmp_file] [-i] [-v] [-g] -H -V
       -t VNUML_file, build topology (using VNUML_file) as source
       -x cmd_seq@VNUML_file, execute the cmd_seq command sequence (using VNUML_file as source)
       -r VNUML_file, restart simulation (executes start and stop command sequences consecutively)
          (using VNUML_file as source)
       -d VNUML_file, destroy current simulation (using VNUML_file as source)
       -P VNUML_file, purge simulation (WARNING: it will remove UML cowed filesystems!)
       -V, show program version and exits.
       -H, show this help message and exits.
       -o prefix, dump UML boot messages output to files (using given prefix in pathname)
       -c vnuml_dir, working directory (default is ~/.vnuml)
       -u user, if run as root, UML and uml_switch processes will be owned by this user instead (default 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 timeout, waits timeout seconds for a UML to boot before prompting the user for further action; a timeout of 0 indicates no timeout (default is 30)
       -B, blocking mode
       -e screen_file, make screen configuration file for pts devices
       -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 can be invoked using one of the following five different modes: build topology (-t mode), execute commands (-x), destroy simulation (-d) or purge simulation (-P). There is an additional mode, the restart mode (-r), that combines the execution of the "stop" command sequence followed by the execution of the "start" command sequence.

Virtual machines are processed one by one. If no order attribute is used in <vm> tags, the processing order is the order of the virtual machines in the VNUML specification file. Otherwise, virtual machines are processed in the same order in which they are described in the VNUML file. The order attribute is especially useful when some virtual machine should execute commands before others.

Additionally there are two pseudo-modes: -V, which shows program version and exits; and -H, which prints the usage of

Note for old users: the start simulation (-s) and stop simulation (-p) modes still work, but are deprecated, so you are strongly encouraged to use execute command sequences (-x) instead.

All users can run in debug execution mode (-g switch). The root user can run any simulation. Conventional users (non-root) are allowed to execute only simulations that comply with the following limitations:

Since version 1.3.0, supports SKAS mode.

Following four sections describe each of these modes in detail.

2.1. Building a Simulation Scenario

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

During the scenario start-up process, several virtual interfaces, bridges and uml_switch processes are created on the host for the management of virtual machines (virtual machines are basically managed by sending commands through a ssh session from the host). These interfaces, bridges and uml_switches exist while the scenario is running, and are destroyed when the scenario is released (-d).

Note that building a simulation scenario can take a long time because the UML booting process of each virtual machine is slow. 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 can generate a lot of verbose output messages. 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 machine will be suffixed 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). There are two special cases: '-o /dev/null' redirects output to the null device; '-o /dev/stdout' redirects ouput to standard output.
    Note: versions 1.6.1 and before use /dev/null as default when -o switch is not used. Versions 1.6.2 and beyond use /dev/stdout.
  • Boot timeout (-w switch). UMLs are booted one after the other, each starting after the previous has reached a successful boot level (i.e., the init process has started). A boot timeout is defined, in seconds, with the -w switch. If this timeout is reached before the UML has booted sufficiently, then the user is prompted to either abort (release the simulation), continue (halt the current UML, if it has not yet booted sufficiently), or retry (wait an additional timeout seconds for the UML to boot). If the timeout is specified as 0, then will not timeout when booting a UML. The default timeout is 30 seconds.
  • Working directory (-c switch). By default the working directory for is ~/.vnuml. Using the -c switch this default can be overridden. Read more about the VNUML working directory. This switch is very useful when several users want to run concurrent simulations.
  • User (-u switch). When is run as root, the UML and uml_switch processes that are spawned are owned by the non-privileged user, vnuml (see Privilege Separation). This can be overridden by designating a different user using the -u switch. The VNUML working directory for root (~root/.vnuml, by default) and all files and directories within it will also be owned by this non-privileged user. The --with-vnuml_user option of configure can be used to specify a different default user when building the VNUML package.
  • Screen configuration (-e switch). Followed by 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

Note for old users: -m switch is no longer supported since version 1.6.0.

Note for old users: the meaning of -w has slightly changed in 1.6.0: now it is a booting timeout (in previous versions it was a inter-boot delay).

2.2. Execute Commands

To execute commands over an already running scenario use switch -x. You must specify the commands sequence that you want to execute using the following notation: -x cmd_seq@VNUML_file

Where 'cmd_seq' is the command sequence to be executes (matching with seq attribute in <exec> tag) and 'VNUML_file' is the VNUML specification of the simulation.

The restart mode (switch -r) is related to the execute commands mode. In particular -r VNUML_file
equals to two consecutive invocations: -x stop@VNUML_file -x start@VNUML_file

Before executing commands, <filetree> tag (that works in conjunction with <basedir> tag) can be used to copy files or directories from the host file system to the virtual machines ones, or vice-versa. This tag is very useful for copying the configuration files needed by the applications to be started in each virtual machine.

To use these modes the scenario must already have been 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 <exec> 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 recommended, in order to avoid having to type the password for each SSH access.

Due to some problems with the 'ssh' command, 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 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 <exec> tag, you should write:

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

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 <exec> tag. Commands included in files do not need to be escaped.

The following optional switch can be used when invoking vnumlparser using modes -x and -r (and the deprecated -s and -p):

  • Virtual machine list (-M switch). By default, the commands execution is performed in all UMLs of the scenario. To restrict the actions to some virtual machines, use -M switch, specifying a list of comma separated virtual machine names after the switch. For example: -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 when <host> is used.

Note for old users: start simulation (-s) and stop simulation (-p) modes and <start> and <stop> tags are still working, but are deprecated, so you are strongly encouraged to use execute commands (-x) and <exec> tag instead.

2.3. Releasing a Scenario

To release a simulation scenario use switch -d.

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

When using -d mode, uses uml_mconsole to issue a cad (ctrl-alt-del) signal to each running UML process. The UMLs have been configured to halt when they receive this signal (the /etc/inittab file has been modified to allow this behavior).

Note that releasing a simulation scenario can take a long time because the UML halting process of each virtual machine is slow. 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 using mode -d:

  • Forced mode (-F switch). When using forced mode, the halt signal, rather than the cad signal, is sent to the UMLs using uml_mconsole. This is analogous to removing power to a machine without shutting it down properly. Disk caches are not synchronized in the UML filesystem before halting, so this option can lead to UML filesystem corruption. It is highly recommended to use -F only in exceptional cases (see more information later in this manual).
  • Working directory (-c switch). By default the working directory for is ~/.vnuml. With -c switch this behaviour can be overridden. Note that if this switch is used, the working directory must be the same as the one used when building the scenario (-t mode). Read more about the VNUML working directory. This switch is very useful when several users want to run concurrent simulations.

2.4. Purging an Scenario

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

When switch -P is used, copied and cowed filesystem in the simulation directory 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 from the given scenario.
  3. Kill (SIGKILL) all remaining UML processes from the given scenario.
  4. Remove (rm) all files related with the simulation (usually in ~/.vnuml/simulations/simulation_name/).

2.5. Common Switches

The following optional switches are common to all execution modes:

  • Blocking mode (-B switch). Used during build scenario mode, the parser blocks until all the virtual machines defined in the simulation are SSH ready (the default behaviour without -B is to exit immediately after the initiating the boot process of all the virtual machines).

    When this switch is used with execution mode (-x), blocks (waits) for all machines to become ready before issuing command sequences. Without the use of -B, if any one virtual machine is not ready to receive commands (i.e., the sshd daemon is not running), (in execution mode) exits without executing any commands.
  • Scanning mode (-S switch). Select the way of UML SSH-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.
  • Verbose mode (-v switch). It tells to show each command result after executing it. Prompt 'host> ' is used when executing command in the host environment. When executing commands in a UML (usually in deferred way, through a script) the name of the virtual machine is used as prompt. The verbose output is very useful to know what is exactly doing and debug it, so using -v is recommended.
  • Debug mode (-g switch). Tells not to actually execute commands, only show them as in verbose mode. A 'D-' is added to any prefix prompt in debugging 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 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). The default temporal directory can be changed with --with-tmp option of configure when building the VNUML package.
3. Advanced topics

3.1. Host Interfaces and Virtual Networking

When building a scenario with the -t switch, a set of virtual interfaces could be created in the host environment.

There are three kinds of interfaces managed by

  • Management interfaces. When private management is used (type="private" in the <vm_mgmt> tag), the interfaces created on the host 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 chosen by using the network, mask, and offset attributes in the <vm_mgmt> tag). If the address at host side is IP, the address at UML side is IP+1 (for example, if host address is a 'ping' executed in the host will check the connection to the UML through the management interface). This interface is used by to send commands to the virtual machines when executing command sequences (-x, -r and the deprecated -s and -p modes). It also can be used by the user to access the virtual machine via SSH.

    If net management is used (type="net" in the <vm_mgmt> tag), the configuration of a single tap interface (connected to a uml_switch process) must be performed prior to simulation time. The name of the interface may be anything, but its IP address must fall within the subnet defined by the network and mask attributes in the <vm_mgmt> tag and specified in the hostip attribute in the <mgmt_net>.

    Management interfaces are not needed or created on the host machine if type="none" in the <vm_mgmt> tag, or if the <mng_if>no</mng_if> tags are used on particular machines. In such cases, other mechanisms for accessing the virtual machine should be arranged (e.g., through virtual network from the host or through direct login).
  • UML interfaces. Related to mode="virtual_bridge" networks (see virtual networking section). 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 environment.
  • Virtual network interfaces. Related to mode="virtual_bridge" networks (see virtual networking section). 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)

Bridge-based (type="virtual_bridge") virtual network connectivity is achieved through the use of virtual bridges configured in the host environment. The command 'brctl show' executed in the host will show what bridges exist (one for each virtual network defined with <net>) and what UML interfaces are connected to each bridge (virtual network).

3.2. Virtual Networking

The <net> is the key piece to define virtual networking. Two attributes (mode and type) defines the way a virtual network is created.

  • mode can be "virtual_bridge" or "uml_switch" (default is virtual_bridge). Virtual bridge based networks are built using virtual bridges. They rely on the creation of UML interfaces (tap devices) and virtual bridge interfaces on the host (see host interfaces section), requiring root privileges. In the other hand, uml_switch based networks implement the virtual network using a uml_switch user process, so no special interfaces need to be created in the host, and root privileges are not required. The uml_switch mode needs a UNIX socket which is stored in the working directory
  • type can be "lan" or "ppp" (default is lan). Lan networks emulate a conventional broadcast Ethernet network (packets sent by one virtual machine connected to the network can be received for any host in the same network, even when not addressed to it, if using promiscuous mode). PPP networks are intended to emulate PPP links: just two hosts can be connected to this type of network. In addition, a link bandwidth can be defined. See <bw> for details.

Note that mode and type are independent, so there are four kinds of network configurations:

  • mode="virtual_bridge", type="lan"
  • mode="virtual_bridge", type="ppp"
  • mode="uml_switch", type="lan"
  • mode="uml_switch", type="ppp"

3.3. Hostfs Filesystems

Hostfs is a UML feature that allows to use a directory as root filesystem for virtual machines, instead of using a filesystem file (the default <filesystem> behaviour).

A hostfs-ready directory can be built from a filesystem file (that can be downloaded from the VNUML files area) following these steps:

  1. Mount the filesystem file.
    mount root_fs /mnt/loop -o loop
  2. Copy all the content to the desired location.
    cp -va /mnt/loop/* /usr/local/share/vnuml/filesystems/hostfs/1/
  3. Set permission/ownership, considering what user will run the VNUML specification.
    chown -R user:user /usr/local/share/vnuml/filesystems/hostfs/1/
  4. Use attribute type="hostfs" in <filesystem> for the particular virtual machine.
       <filesystem type="hostfs">/usr/local/share/vnuml/filesystems/hostfs/1/</filesystem>

In order to hostfs works properly you need UML kernel >= 2.6.9. Anyway, hostfs could not work well at all. Please see this comment for some details.

Note that each virtual machine must have its own hostfs directory. The parser will not check if two virtual machines are using the same hostfs directory and this situation would lead to erroneous and unpredictable behaviour in the virtual machines.

3.4. UML Readiness

When is run with the -t switch, the boot process of the virtual machines is initiated. However, before each UML is able to respond to certain commands or signals issued from the host, a certain point in the boot process must be reached. In order for a UML to properly shut down when a cad signal is sent via the uml_mconsole program, the init process must have started on the UML. To avoid a situation in which one or more UMLs do not respond to a cad signal because they have not booted sufficiently, waits for the init process to start on the UML before continuing its own execution. Before the boot process begins when using the -t switch, creates a UNIX socket on which it listens for a message from each UML as it boots. When the init process has started on the UML, it sends a message to the socket to notify (see the mconsole=notify:socket UML argument). If a designated timeout is reached before receives the notification, then prompts the user for further action (see the -w boot switch).

Additionally, before remote commands may be issued to the virtual machines, (-x mode), the host must be able to establish a SSH session with each UML. This is tested by performing a socket probe to the SSH port each virtual machine. will not allow -x mode until the host can communicate with all virtual machines

See also the -B switch, that blocks the parser execution under certains conditions of UML readiness.

3.5. Direct login to UMLs

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

This behaviour can be overridden (and your are encouraged to do that if using type="none" in the <vm_mgmt> tag or <mng_if>no</mng_if>!) using <con0> tag. Specifying xterm in a graphical environment or a tty, the UML outputs a login prompt to the specified device. In the case of using xterm, particular configuration can be specified using <xterm>.

When specifying a pts, the number of pseudo-terminal 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 ~/.vnuml/simulations/tutorial/vms/uml2/mconsole config con0

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

screen /dev/pts/6

When the -e switch is used while building the scenario (-t mode) can get the pts devices of the UMLs automatically and put it in a file (whose name is given as the argument of -e switch) that could be used as -c argument of the screen(1) command.

Warning: tests have shown that booting with xterm binary (usuallly in /usr/X11R6/bin/xterm) can be unstable under certain conditions. If you are using <con0>xterm</con0> and you are having weird problems (UML hanging, xterms poping up but no text appear inside, xterms not popping up, etc.) using a differente xterm program with <xterm> (for example, gnome-terminal) is recommended.

3.6. Working Directory

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

  • ~/.vnuml/LOCK. This is the global lock file for a particular working directory. It is created when starts and deleted when it finishes execution. Before starting, checks that the file does not exist. This method ensures that no more than one instance of is running with a given working directory at any one time.
  • ~/.vnuml/networks/. This directory contains all the global network data for vnuml simulation scenarios, including UNIX sockets for uml_switch process and references to how many simulations are using a particular vnuml network.
    • ~/.vnuml/networks/if_name.cter, where if_name is the name of certain external (external attribute in the <net> tag) network interface (in the host environment). This file is a counter to record how many simulations are using that interface, increased and decreased by 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.
    • ~/.vnuml/networks/socket_name.ctl, where socket_name is the name of certain uml_switch-based (type="uml_switch" in the <net> tag) network interface. This file is a UNIX socket or a symbolic link pointing to a socket, used by the uml_switch process associated with the virtual network.
    • ~/.vnuml/networks/socket_name.ctl.cter, where socket_name is the name of certain uml_switch-based (type="uml_switch" in the <net> tag) network interface. This file is a counter to record how many simulations are using that socket (or symbolic link), increased and decreased by when it creates (-t mode) and releases (-d mode) a scenario, respectively. The parser uses this information to know when it can kill the uml_switch process (or remove the symbolic link) that implements the associated uml_switch-based virtual network. The non existence of this file is an implicit 0 value.
  • ~/.vnuml/simulations/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 scenario. Note that the directory is not deleted when scenario life cycle ends, due to the fact that some files (e.g., COW patches) could be used the next time the scenario is built.
    • ~/.vnuml/simulations/simulation_name/lock. As long as this file exists, the scenario is running. The parser creates this file during the build scenario mode (-t switch) and deletes it during release mode (-d switch). It is used by for management tasks (e.g., to not build a simulation that has already been built, not to take starting and stopping simulation actions if the scenario is not running, etc.).
    • ~/.vnuml/simulations/simulation_name/vms/vm_name/, where vm_name is the name of a certain virtual machine (name attribute in the <vm> tag) in the simulation_name simulation (<simulation_name>). This directory contains pid files, sockets, disk images (including cow files) specific to this simulation.
      • ~/.vnuml/simulations/simulation_name/vms/vm_name/run/. This directory is created by the UML vm_name when it is started, and it is removed by the UML instance when the UML is shut down properly. It contains two files: mconsole, the UNIX socket used to send console commands to the UML using the uml_mconsole utility (e.g., for UML shutdown); and pid, the socket file containing the pid of the UML instance.
      • ~/.vnuml/simulations/simulation_name/vms/vm_name/fs/. This directory contains the filesystem images (<filesystem> or <default_filesystem>) used by a particular UML. If the filesystem type="copy", then the root filesystem image will reside in this directory as the file root_fs. If the filesystem type="cow", then the cow image of the root filesystem will reside here as root_cow_fs. For any simulation, regardless of filesystem type, the auxiliary filesystem iso9660 image (mounts on /mnt/vnuml) resides in this directory as opt_fs.

Note: .cter in the working directory always stands for counter file for a particular resource that VNUML parser needs to know.

3.7. Privilege Separation

When VNUML is installed, new users and groups are created as part of the install process. These users and groups allow administrators to more flexibly define VNUML usage and control the privileges that are granted to VNUML users.

  • uml-net (group). This group owns the /dev/net/tun device, with which TUN/TAP devices are created and accessed. A non-privileged user that owns a uml_switch process can use the -tap option to access the host, if it is a member of this group. Although uml-net is the default, this may be changed at the time of install by running configure with the --with-tun_group option.
  • vnuml (group). This group can be used to regulate access to certain directories (such as the local state directory /var/local/run/vnuml) and files that have been set up by the root user for non-privileged users of VNUML. For example, the root user may restrict the use of a uml_switch process to members of the vnuml group by giving the associated UNIX socket of the uml_switch process vnuml group ownership and 660 permissions. Although vnuml is the default, this may be changed at the time of install by running configure with the --with-vnuml_group option.
  • vnuml (user). This non-privileged user owns the UML and uml_switch processes that are spawned when is started by root. This user also owns the ~root/.vnuml/ directory and all the files in its hierarchy. This user is a member of both the vnuml and uml-net groups. Note that this user must have appropriate access to files needed for UML run time (e.g., filesystem images, etc.). Although vnuml is the default, this may be changed at the time of install by running configurewith the --with-vnuml_user option. Also, this user may be specified on the command line by using the -u switch.

3.8. Temporal Command Files

During executing commands mode (-x and -r switch, in addition to the deprecated -s and -p), the commands specified with <start>, <stop> and <exec> (either verbatim or read from a file) are printed to a script file in the host environment (by default to /tmp directory, although this can be overridden with -T).

These files have a header like that:

# UML start commands file generated by 1.6.0 at Thu Jul 31 00:07:53 CEST 2003


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, where name is the name of the virtual machine where the file will run and seq is the value of the seq attribute used as cmd_seq when calling the vnumlparser ('-x cmd_seq@VNUML_file'), including "start" or "stop", when using -r mode or the deprecated -s or -p modes.

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

3.9. 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 different name (<simulation_name>).
  • Virtual machines and network names (name attribute of <vm> and <net>) must be unique for all simulations. The same name in different simulations is not allowed. In the case of <net>, type attribute must remains the same for the same network in all concurrent simulations.
  • Management IP addresses for the management interface must not overlap in two or more simulations. To avoid this, configure the type, network, mask, and offset attributes of <vm_mgmt> with suitable values for each simulation, such that the assigned management IP addresses do not overlap. Remember that the <vm_mgmt> type determines the number of addresses per UML that are used (e.g., four addresses each for type="private" one address each UML for type="net", plus the host IP address, if it is >= the offset.
  • 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 different offset in each simulation.
  • Due to the fact that all simulations share the host environment (<host> tag), some conflicts could arise. The recommendation is not to use <host> tag at all whenever possible.

Version 1.6.0 (and before) do not perform special checking about whether the above restrictions are being accomplished or not. So, it is the user's responsibility. Not following these rules can lead to unpredictable and erroneous behaviours.

Note that, to avoid race conditions, no more than one instance of 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 is to check the existence of this file: if it exists exits doing nothing. In the other case, the file is created. When finishing, removes the LOCK as last action.

If a crash occurs while 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.

If two or more concurrents simulations belong to different users, they should use -c switch in order to define a common workin directory (due to the default one, ~/.vnuml, is user-specific).

3.10. External Connections and VLAN support

Only for type="virtual_bridge" virtual networks in <net> tags.

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 sub-interfaces 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 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 loss of network connectivity to the host from the external networks (very important if you log in your host through network instead logging in through a keyboard console).

The external and vlan attributes are ignored in type="uml_switch" virtual networks.

3.11. How to release a scenario when -d fails

Under certain circumstances, the release of a VNUML scenario may fail when -d mode is used. This is evident when hangs indefinitely while waiting for UML processes to die. Two possible reasons for this are given:

  • If the /etc/inittab file on the UML was not modified correctly upon startup, then the UML may not respond correctly to a cad signal. To properly shut down the non-responsive machine, the user should login to the machine using either a direct login or SSH via the management interface to issue the halt command.
  • If the kernel itself hangs (due to a kernel bug), then UML may not respond to the cad signal, or it may hang during the shutdown process. If this is the case, then the -F switch should be used to kill the process.

If the above circumstances are encountered, and the respective procedures for resolving them fail, these general steps may be followed to release the simulation scenario. The should be used only as a last resort, as they can lead to UML filesystem corruption:

  1. Use forced destroy topology mode: -d mode with -F switch.
  2. If this fails, use purge mode (-P). This tries to kill the UML processes in the simulation (first, with SIGTERM, but if the UML doesn't die gracefully, it tries SIGKILL) and removes all data related with the simulation (including the COW and copied filesystems).
  3. Sometimes after a -P, some UML zombie process remains in the host process space. However, they should conflict with existing or newly built simulations.

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' assumes that your kernel name includes 'linux' (like 'linux-2.4.22um12'). If you are using other name in the <kernel> tag, you must use the appropriate grep expression.

4. Building a Customized Kernel

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 for 2.6.x kernels:

  1. Get Linux kernel sources, usually from Decompress the source tarball into same place (for example, /usr/src/linux-
  2. Configure the kernel. This process is the same than configuring a conventional Linux kernel. Note the required ARCH=um switch.
    make menuconfig ARCH=um
  3. Compile the kernel.
    make ARCH=um
    This commands produces a executable file named 'linux' in the root of the sources directory. Put the file in a convenient place. For example:
    cp linux /usr/local/share/vnuml/kernels/

Kernel modules can also be compiled and used. Read about it in the UML Project web page.

5. Filesystem Requirements

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 fulfill some requirements:

  • An empty directory /mnt/vnuml must exist.
  • A symbolic link in the rc.d tree pointing to /mnt/vnuml/umlboot must exist (for example, if you are booting at runlevel 3, the symlink could be /etc/rc.d/rc3.d/S11bootuml).
  • 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     /mnt/vnuml	iso9660     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 recommended 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 accessible 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
    • Am I forgetting anything?

Such filesystem accomplishing all requirements 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 root_fs_tutorial reference filesystem (available for download at SourceForge).

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 requirement of itself, but it is important to note that the files needed to support <exec> (or <start> or <stop>) operation must be in the filesystem. For example, if you have in your VNUML source file

<exec seq="sample" type="verbatim">/usr/bin/testprogram</exec>

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

6. Installing Software in UML Filesystems

To install new software (programs) into a UML filesystem, you can use several 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 availability of 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 environment:
    mount -o loop root_fs /mnt
    cd /usr/local/src/zebra
    ./configure --prefix=/mnt
    make install
    make clean
    make distclean
    umount /mnt
  • Mount the filesystem, chroot to it and the install the software (this is specially recomendable if you are using tools that perform installations using the network, as APT). For example:
    mount -o loop root_fs_tutorial /mnt
    chroot /mnt
    apt-get upddate
    apt-get install something
    umount /mnt

Last update: