VNUML 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 [Reference 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 vnumlparser.pl against it in order to build and manage the simulation scenario. Execution phase consists of three steps (although one of them is actually optional), each corresponding to an option or mode of vnumlparser.pl:
  • 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.
  • 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.
    This step is actually optional. If you don't need to execute command sequences (because you prefer interact with the virtual machines directly), you don't need it.
    Note for old users: if you have used vnumlparser.pl 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 vnumlparser.pl to run whatever command sequence you want: the start-stop simulation cycle paradigm is not suitable for all cases. Note that -s, -p, and -r modes and with <start> and <stop> tags are no longer supported since version 1.7. You must use <exec> instead.
  • 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 step 2, vnumlparser.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 (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.

[edit] 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 containing other specific tags. There are five tags of this type: <vnuml>, <global>, <vm>, <vm_defaults> 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 building and releasing scenario modes (-t and -d modes of vnumlparser.pl) and ignored during executing commands mode (-x mode of vnumlparser.pl). There are 23 tags of this type: <ssh_key>, <automac>, <netconfig>, <host_mapping>, <tun_device>, <net>, <bw>, <filesystem>, <mem>, <kernel>, <console>, <xterm>, <mng_if>, <if>, <hostif>, <mac>, <ipv4>, <ipv6>, <physicalif>, <route>, <forwarding>, <user>, and <group>.

• Simulation tags, that carry the semantics related to the simulation. They are used during command execution mode (-x mode of vnumlparser.pl) and ignored during build and release scenario modes (-t and -d modes of vnumlparser.pl). There are four tags of this type: <ssh_version>, <basedir>, <filetree> and <exec>.

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> and <exec> tags). In this way, the simulation behaviour and objectives can be changed between simulation cycles. However, do not edit other tags if you are not really sure because it can lead to unpredictable and erroneous behaviours.

[edit] VNUML Parser Usage 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. In fact, the installation procedure place the script file in the right directory (/usr/local/bin/vnumlparser.pl if you installed from source .tgz or /usr/bin/vnumlparser.pl, if you installed from .deb package -recommended).
If you call the parser with -H switch you get the following brief (but useful) description of its modes and options:
gracia:~# vnumlparser.pl -HUsage: vnumlparser.pl -t VNUML_file [-o prefix] [-c vnuml_dir] [-u user]                 [-T tmp_dir] [-i] [-w timeout] [-B] [-Z]                 [-e screen_file] [-4] [-6] [-v] [-g]       vnumlparser.pl -x cmd_seq@VNUML_file [-T tmp_dir] [-M vm_list] [-i]                  [-B] [-4] [-6] [-v] [-g]       vnumlparser.pl -d VNUML_file [-c vnuml_dir] [-F] [-T tmp_dir] [-i]                  [-B] [-4] [-6] [-v] [-g]       vnumlparser.pl -P VNUML_file [-T tmp_file] [-i] [-v] [-g]       vnumlparser.pl -h       vnumlparser.pl -VMode:       -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)       -d VNUML_file, destroy current simulation (using VNUML_file as source)       -P VNUML_file, purge simulation (WARNING: it will remove UML cowed filesystems!)Pseudomode:       -V, show program version and exits.       -H, show this help message and exits.Options:       -o prefix, dump UML boot messages output to files (using given prefix           in pathname)       -c vnuml_dir, vnumlparser.pl 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)       -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       -Z, avoids filesystem VNUMLization       -e screen_file, make screen configuration file for pts devices       -i, interactive execution (in combination with -v mode)       -4, process only IPv4 related tags (and not process IPv6 related tags)       -6, process only IPv6 related tags (and not process IPv4 related tags)       -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 four different modes: build topology (-t mode), execute commands (-x), destroy simulation (-d) or purge simulation (-P).
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 vnumlparser.pl.
Since version 1.3.0, vnumlparser.pl supports SKAS mode
Note for old users: the start simulation (-s), stop simulation (-p), and restart (-r) modes still has been definetively removed since VNUML 1.7.0. Use execute command sequences (-x) instead. In addition, the -S switch (scan mode) was removed in release 1.8.0: ps scan mode is obsolete so it was removed.
All users can run vnumlparser.pl 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:

• Only type="uml_switch" may be used in <net> tags. See more details about uml_switch virtual networks later in this manual.

• The <vm_mgmt> type attribute may not be "private". See the reference for more details on configuring other management types.

• The <host_mapping> and <host> tags may not be used.

• Attribute capture_dev in <net> can not be used.

Following four sections describe each of these modes in detail.
[edit] 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 in 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 filesystem and the physical resources of the host.
Warning when upgrading root filesystem for COW-based existing simulations: if you use a symlink that points to the actual filesystem (tipically root_fs_tutorial -> root_fs_tutorial-X.Y.Z), note that upgrading the actual filesystem (root_fs_tutorial-X.Y.Z) will corrupt previously created COW based simulations so you probably get problems when building topology. Therefore, it is advisable to purge (vnulmparser.pl -P) that simulations before (or event removing directly their directory under ~/.vnuml/simulations to be sure).
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 where where the output will be stored. Several posibilities:
  • '-o /dev/null', redirects output to the null device
  • '-o /dev/stdout', redirects output to standard output
  • Other files in /dev are forbidden for security reasons (you don't really want to redirict the output to your hard disk block device, do you? :)
  • '-o -', the same as '-o /dev/stdout'
  • '-o existing file', appends output to the file
  • '-o prefix, redirects the output of each one virtual machine to a different file, using prefix with the name of the virtual machine as suffix. For example, if there are three virtual machines named vm1, vm2 and vm3, with '-o /tmp/vnuml_output' will create the /tmp/vnuml_output.vm1, /tmp/vnuml_output.vm2 and /tmp/vnuml_output.vm3 files. 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 vnumlparser.pl will not timeout when booting a UML. The default timeout is 30 seconds.
• Working directory (-c switch). By default the working directory for vnumlparser.pl 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 vnumlparser.pl 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 <console> tags of the simulation file. This file is for using as -c argument of the screen(1) command: screen -c /tmp/screen.conf
• Avoid VNUMLization (-Z switch) (new in 1.7.1). Useful when root filesystem has been previously adapted to VNUML (like the ones available for download in the VNUML Project webpage) and the VNUMLization step is not needed, saving time in the topology building procedure. See more on VNUMLization.

Notes for old users:

• -m switch is no longer supported since version 1.6.0.

• 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).

[edit] 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:
vnumlparser.pl -x cmd_seq@VNUML_fileWhere 'cmd_seq' is the command sequence to be executed (matching with seq attribute in <exec> tag) and 'VNUML_file' is the VNUML specification of the simulation.
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, 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 <exec> tag, you should write:
<exec seq="start" type="verbatim">nohup /usr/bin/hello </dev/null >/dev/null 2>&1 &</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:

• 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:

vnumlparser.pl -x start@sim.xml -M uml1,uml3,uml6only executes the 'start' secience in virtual machines named uml1, uml3 and uml6, leaving all other virtual machines unaltered. Note that, no matter if -M is used, the commands of the respective sequence are always executed in the host when <host> is used.
Note for old users: start simulation (-s), stop simulation (-p) and restart simulation (-r) modes and <exec> tag instead.
[edit] 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, vnumlparser.pl 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 vnumlparser.pl 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 vnumlparser.pl 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.

[edit] Purging an Scenario The main purpose of this mode (-P switch) is to automate deleting actions when a 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:

• Forced release of the scenario (equivalent to -d with -F).
• Kill (SIGTERM) all UML processes from the given scenario.
• Kill (SIGKILL) all remaining UML processes from the given scenario.
• Remove (rm) all files related with the simulation (usually in ~/.vnuml/simulations/simulation_name/).

[edit] 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 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), vnumlparser.pl 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), vnumlparser.pl (in execution mode) exits without executing any commands.

• Only IPv4 (-4 switch) or only IPv6 (-6 switch). Using -4 (-6) only IPv4 (IPv6) address and routes are used. That means that <ipv6> (<ipv4>) and <route> tags with type="ipv6" (type="ipv4") are ignored. Both switches can not be used together. See the tutorial_limited_user_ipv6.xml tutorial in /usr/share/examples.

• 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 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 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 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 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). The vnumlparser.pl program remove the files after using it, so user shouldn't worry about that, but sometimes (for example, in the case of a power failure while vnumlparser.pl is running) some files could remain. The default temporal directory can be changed with --with-tmp option of configure when building the VNUML package.

[edit] Advanced topics [edit] 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 vnumlparser.pl:

• Management interfaces. When private management is used (type="private" in the <vm_mgmt> tag), the interfaces created on the host are named "name-e0", 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 vnumlparser.pl 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 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 when executing command sequences (-x mode). 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-en", 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).
[edit] 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"

A powerfull feature that uml_switched networking allows (developed by Esteban's Martin as part of his M.Sc work) is the capture of virtual network traffic to lipcap formated files in the host, or even create capture pseudodevices that can be used from Ethereal directly. Please, check the capture_* attributes in <net> and the contrib/uml_router directory in the VNUML package.
[edit] Hostfs Filesystems Hostfs is a UML feature that allows directories in the host to be mounted in the virtual machine, thus allowing sharing files. VNUML 1.8 implements two hostfs related features: automatic hostfs mountpoint and the ability of use hostfs as root filesystem.
In order to hostfs to work properly you need UML kernel >= 2.6.9. Anyway, hostfs could not work well at all. Please see this comment for some details
[edit] Automatic hostfs mountpoint An automatic mount is created in each virtual machine "connecting" ~/.vnuml/simulations/simulation_name/vms/vm_name/hostfs in the (within host filesystem working directory) to /mnt/hostfs (virtual machine filesystem). This can be used by the user as "interchange area" to share files between virtual machine and host.
In addition, this connection is used under the hood by the VNUML parser when processing <exec> and <filesystem> in mconsole execution mode.
[edit] Hostfs as root fileystem A hostfs root filesystem can be used instead of using a filesystem file (the default <filesystem> behaviour). This hostfs-ready directory can be built from a filesystem file (that can be downloaded from the VNUML files area) following these steps:

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

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.
[edit] UML Readiness When vnumlparser.pl 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, vnumlparser.pl 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, vnumlparser.pl 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 vnumlparser.pl (see the mconsole=notify:socket UML argument). If a designated timeout is reached before vnumlparser.pl receives the notification, then vnumlparser.pl 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. vnumlparser.pl 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.
[edit] 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 <console> 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 con0returns 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/6When the -e switch is used while building the scenario (-t mode) vnumlparser.pl can get the pts devices of the UMLs automatically and put them 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 <console id="n">xterm</console> and you are having weird problems (UML hanging, xterms poping up but no text appear inside, xterms not popping up, etc.) using a different xterm program with <xterm> (for example, gnome-terminal) is recommended.
[edit] Working Directory The default vnumlparser.pl 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 vnumlparser.pl starts and deleted when it finishes execution. Before starting, vnumlparser.pl checks that the file does not exist. This method ensures that no more than one instance of vnumlparser.pl 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 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.
  • ~/.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 vnumlparser.pl 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 vnumlparser.pl 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 strong>opt_fs</strong>.
    • ~/.vnuml/simulations/simulation_name/vms/vm_name/hostfs/. This is the directory used for the hostfs automatic mount described in automatic hostfs mountpoint section in this manual.

Note: .cter in the working directory always stands for counter file for a particular resource that VNUML parser needs to know.
[edit] 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/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 vnumlparser.pl 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.

[edit] Filesystem VNUMLization VNUMLization is a pre-booting step performed in order to adapt the filesystem to VNUML actual booting. Is based on the execution of the vnumlize.sh script (located in /usr/lib/vnuml/vnuml/ if using defaults in ./configure when installing) in virtual machine context.
Please, have a lock to the vnumlize.sh script in order to know what exactly it does. Maybe you want to improve (tell us about in that case! :) or adapt it to your particular purposes.
New in 1.7.1: in the case you were using a previously adapted root filesystem (like the ones available in the VNUML Project webpage for download) you can avoid the VNUMLization step unsing -Z switch in the vnumlparser.pl command line. This would save some time during the topology building procedure.
[edit] 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.7.1 (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 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 it exists 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.
If two or more concurrents simulations belong to different users, they should use -c switch in order to define a common working directory (due to the default one, ~/.vnuml, is user-specific).
[edit] 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 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 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.
[edit] 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 vnumlparser.pl 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:

• Use forced destroy topology mode: -d mode with -F switch.
• 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).
• 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-100NOTE: '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.
[edit] 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:

• Get Linux kernel sources, usually from http://www.kernel.org/. Decompress the source tarball into same place (for example, /usr/src/linux-2.6.12.2).
• Configure the kernel. This process is the same that configuring a conventional Linux kernel. Note the required ARCH=um switch. make menuconfig ARCH=um
• Compile the kernel. make ARCH=umThis 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/share/vnuml/kernels/

Kernel modules can also be compiled and used. Read about it in the UML Project web page.
[edit] 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).
For a quick procedure to create a root_fs comptatible with 1.8 see this HOWTO. The requirements on the root_fs filesystems are derived from the commands used to create it.
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 /mntIt is not a requirement of vnumlparser.pl itself, but it is important to note that the files needed to support <exec> 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).

[edit] Installing Software in UML Filesystems 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 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. in addition, note that if you are using type="cow" in <filesystem> you could lost your changes and need to install the software again (you should use type="direct").
• 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 /mntcd /usr/local/src/zebra./configure --prefix=/mntmakemake installmake cleanmake distcleanumount /mnt
• Mount the filesystem, chroot to it and then install the software (this is specially recommendable if you are using tools that perform installations using the network, as APT). For example: mount -o loop root_fs_tutorial /mnt/loopmount -t proc none /mnt/loop/procchroot /mnt/loopapt-get updateapt-get install something...exitumount /mnt/loop/procumount /mnt/loop