1. VNUML Sim. Philosophy|
1.1. Types of Tags
2. VNUML Parser Usage|
2.1. Building Sim. Scenario
2.2. Execute Commands
2.3. Releasing Sim. Scenario
2.4. Purging Sim. Scenario
2.5. Common Switches
3. Advanced topics|
3.1. Host Interfaces
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 cmd files
3.9. Concurrent Simulations
3.10. Ext. Conns/VLANs
3.11. Release when -d fails
4. Building Custom Kernel|
5. Filesystem Requirements|
6. Installing Software|
VNUML User Manual
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:
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, 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.
There are three types of tags in a VNUML file:
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 vnumlparser.pl usage options.
Basically, the parser is a Perl script that it is called from a shell
command-line (it is recommended to put vnumlparser.pl file
within console command path, typically
If you call the parser without arguments you get the following brief (but useful) description of its modes and options:
Usage: vnumlparser.pl -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] vnumlparser.pl -x cmd_seq@VNUML_file [-T tmp_dir] [-M vm_list] [-i] [-S scan_mode ] [-B] [-v] [-g] vnumlparser.pl -r VNUML_file [-T tmp_dir] [-M vm_list] [-i] [-S scan_mode ] [-B] [-v] [-g] vnumlparser.pl -d VNUML_file [-c vnuml_dir] [-F] [-T tmp_dir] [-i] [-S scan_mode ] [-B] [-v] [-g] vnumlparser.pl -P VNUML_file [-T tmp_file] [-i] [-v] [-g] vnumlparser.pl -H vnumlparser.pl -V Mode: -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!) 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) -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 vnumlparser.pl.
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 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:
Since version 1.3.0, vnumlparser.pl supports SKAS mode.
Following four sections describe each of these modes in detail.
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:
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).
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_file
Where 'cmd_seq' is the command sequence to be executes (matching with
The restart mode (switch -r) is related to the execute commands mode. In particular
vnumlparser.pl -r VNUML_fileequals to two consecutive vnumlparser.pl invocations:
vnumlparser.pl -x stop@VNUML_file vnumlparser.pl -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, 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 and -r (and the deprecated -s and -p):
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.
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:
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:
The following optional switches are common to all vnumlparser.pl execution modes:
|3. Advanced topics|
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:
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).
The <net> is the key piece to define virtual networking. Two attributes (mode and type) defines the way a virtual network is created.
Note that mode and type are independent, so there are four kinds of network configurations:
A hostfs-ready directory can be built from a filesystem file (that can be downloaded from the VNUML files area) following these steps:
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.
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.
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:
When the -e switch is used while building the scenario (-t mode) vnumlparser.pl 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.
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:
Note: .cter in the working directory always stands for counter file for a particular resource that VNUML parser needs to know.
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.
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:
#!/bin/bash # UML start commands file generated by vnumlparser.pl 1.6.0 at Thu Jul 31 00:07:53 CEST 2003 (commands)
The first line is the shell that executes this script (the value of the optional <shell> tag, by default /bin/bash).
The name of this file is vnuml.name.seq, 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).
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:
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 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 workin directory (due to the default one, ~/.vnuml, is user-specific).
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.
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 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:
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:
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:
/dev/udb1 /mnt/vnuml iso9660 defaults 0 0
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 vnumlparser.pl 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: