Reference

VNX Language Reference

--------------------------
IMPORTANT: This is a very DRAFT DOCUMENT 

VNUML Language reference documentation is being adapted to VNX
Some tags/attributes shown in this document do not apply to VNX
--------------------------

Authors:
David Fernández (david at dit.upm.es)
version 2.0, May 2013

Adapted from VNUML Language Reference Document.

Introduction

The VNX specification language is based on XML and defined using a XSD Schema (available in /usr/share/xml/vnx/vnx-2.00.xsd). This document describes the semantics of the tags of the language.

VNX files start with the following two lines:

<?xml version="1.0" encoding="UTF-8"?>
<vnx xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:noNamespaceSchemaLocation="/usr/share/xml/vnx/vnx-2.00.xsd">

where the location of the XSD file in the host filesystem must be specified (in the example above, this file is /usr/share/xml/vnx/vnx-2.00.xsd). In theory, it's also possible to use a URI, instead of a file in the filesystem.

As in any other XML file, comments can be used (and will be ignored by the parser) using:

 <!-- this is a comment -->

The main tags of a VNX file are:

• <global>, to describe the global parameters of the virtual scenario.
• <net>, to describe the virtual networks.
• <vm>, to describe the virtual machine characteristics.
• <host>, to describe host configuration related to the virtual scenario.

See the following section for a detailed description of each one.

Global Definitions: <global>

This tag groups all global definitions for the simulation that do not fit inside other, more specific tags.

The following tags may appear in a <global> tag:

<version>

Required. Unique.

Specifies which VNX language version is being used in the file. It's used to perform a sanity check against the vnx program that reads the file (VNX files version 2.0 only can be parsed with vnx version 2.0.x). For present VNX version 2.0 the value of this tag is:

<version>2.0</version>

<scenario_name>

Required. Unique.

Specifies the virtual scenario name. Each scenario must have a different name.

<ssh_version>

Optional (default is 2). Unique.

Establishes the SSH version that the parser will use when accessing the virtual machines through the management interface (for example, when copying or executing commands). The valid values are 1 (for SSHv1) and 2 (for SSHv2).Example:

<ssh_version>2</ssh_version>

<ssh_key>

Optional. Multiple.

When used, specifies the absolute filename of a SSH public key of some user on the host machine. Each key specified will be added to /root/.ssh/authorized_keys in filesystems of all the virtual machines. The use of public-key authentication eliminates the need for a password when accessing a virtual machine or executing commands on it using ssh (exe_mode='net' when -x switch is passed to vnx), so user interaction is minimal.

Several keys can be installed, using as many <ssh_key> tags as desired. Note that the keys are installed in all the virtual machines. If a key should only be installed on a particular virtual machine, it should be placed inside a <user> tag with username="root" in the corresponding <vm>.

To generate a RSA1 public key (SSH v1) use the following command in the host:

ssh-keygen -t rsa1

To generate a RSA public key (SSH v2) use the following command:

ssh-keygen -t rsa

To generate a DSA public key (SSH v2) use the following command:

ssh-keygen -t dsa

Anyway, the first time that the key is used, confirmation is requested. Further information in ssh-keygen(1) and ssh(1) man pages.

See also the <ssh_key> tag when used inside a <user> tag.

<automac>

Optional. Unique.

Empty tag.When used, MAC address for the virtual machines interfaces are generated automatically, it is not necessary to use <mac> tag. The format of the automatic generated MAC address is:

   fe:fd:0:Z:X:Y

where X is the virtual machine number (in the same order as specified in the VNUML file, starting with 1) and Y is the interface number (id attribute of the <if> tag). Z is the value of the offset optional attribute (if not specified, 0 is used). Offset can be in the 0-65535 range (if offset greater than 255 then the third byte is also used for the prefix)

Note that if this tag is used is impossible that the same MAC address would be used twice in the same simulation. In the case where several concurrent simulations using <automac> share networks, different offset values should be used for each simulation. Otherwise, it is possible that two virtual machines could have the same MAC address, leading to incorrect network configuration and undesirable results.

When <automac> is used with <mac> inside <if>, address specified in <mac> takes preference. Note that the incorrect use of <mac> could result in duplicate addresses if a manually-assigned <mac> collides with the range of the addresses generated automatically by <automac>.

The use of <automac> is recommended, except when particular MAC addresses are needed (for example, if DHCP network configuration based on hardware addresses is used).

<vm_mgmt>

Optional. Unique.

This tag configures several aspects related to the management interface of the virtual machines. The main purpose of this interface is to provide a network based to virtual machines (typically through SSH). Note however, that this is only one of the possible ways of interacting with virtual machines (see other in direct login).

This interface can also be used by vnumlparser.pl to send commands to the virtual machines when executing remote command sequences (-x mode), using the mode="net" attribute in <exec>. However, since release 1.8 a more efficent network-less execution mode based on uml_mconsole (using mode="mconsole" attribute in <exec>) is available, so management networks is no longer needed for this purpose.

The tag has the following attributes:

• type (mandatory). Select the kind of management interfaces. The allowed values are: private, net or none.
  • Private. A management interface (named "name-e0", where name is the name of a virtual machine) is created on the host for each virtual machine, using a virtual bridge. 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'). The management interfaces on both the host and the virtual machines are dynamically configured with IPv4 management addresses by vnumlparser.pl (the particular address depends on the network, mask and offset attributes, as described below). Note that private management requires configuring virtual bridges. Therefore, only a privileged user may use the private type.
  • Net. The management interface on each virtual machine (named 'eth0') is connected to a uml_switched virtual network. The management interfaces on the virtual machines are dynamically configured with IPv4 management addresses by vnumparser.pl (the particular address depends on the network, mask and offset attributes, as described below). The host is not configured by vnumparser.pl: prior to simulation time, a single tap management interface must be configured by a privileged user (following the network and mask attributes provided in the tag), and a uml_switch process must be started to which the tap device is attached (i.e., using the -tap option to uml_switch). The uml_switch control socket of the virtual network is specified as the sock attribute of the <mgmt_net> tag. An example of host configuration is found in the VNUML distribution under examples/tutorial_user.xml.
  • None. No management interfaces are configured in any virtual machine. User will need other ways of accessing (for example, using direct login). This is equivalent to setting <mng_if>no</mng_if> for all virtual machines.
• network (optional, default is 192.168.0.0)
• mask (optional, default is 24)
• offset (optional, default is 0)

The network, mask and offset attributes specify a IPv4 network address range. Address assignment begins with the first address after the network address plus the offset value. For example, in the following case:

<vm_mgmt type="..." network="10.0.0.0" mask="24" offset="4" />

addressing would begin with 10.0.0.5 (the first non-network address in the 10.0.0.0/24 network plus the offset value, 4), and end with 10.0.0.254. Note that the network address (10.0.0.0) and the broadcast address (10.0.0.255) are not used in address assignment.

This range is used by vnumlparser.pl to set addresses in the management interfaces, as follows, depending on the chosen type:

• If type is private, a point-to-point connection is established from the host to each virtual machine using a /30 subnet (in fact, four IP addresses). The subnets are assigned, in order, beginning with the first subnet for the first virtual machine and continuing in sequence. The address of the host is assigned first, then the address of the virtual machine. In the example above, the host-side address of the first virtual machine's management interface would be 10.0.0.5, and the uml-side address would be 10.0.0.6 (note that 10.0.0.4 is the network address, and 10.0.0.7 is the broadcast address in this /30 network, so they cannot be assigned). The second virtual machine's management interface would use 10.0.0.9 (host-side) and 10.0.0.10 (uml-side), and so on. Note that, to maintain consistency, the offset value in this case must be multiple of four.

• If type is net, management addresses are assigned to each virtual machine in sequence beginning with the first non-network address plus the offset. In the example above, the first virtual machine would use 10.0.0.5, the second 10.0.0.6, the third 10.0.0.7 and so on. The IP address of the host's tap management device is defined in the hostip attribute of the <mgmt_net> tag. This address must be in the subnet defined by the network and mask types. If the offset is such that the host's management IP address falls in the range of possible addresses to be assigned to virtual machines, its address will be skipped. For example, if the host in the above example is configured with the address 10.0.0.6, then the virtual machines will receive the following addresses in order: 10.0.0.5, 10.0.0.7, 10.0.0.8, etc. An example of pre-simulation host configuration is found in the VNUML distribution under examples/tutorial_user.xml.

The offset attribute is intended to avoid address collision when using several concurrent simulations. See VNUML User Manual about concurrent simulations for details.

Management interfaces can be avoided in a particular virtual machine using <mng_if>no</mng_if>. However, you should be very careful using this feature and configure another access mechanism to the virtual machine (through virtual network from the host or through direct login). Note that type="none" is an implicit <mng_if>no</mng_if> for all virtual machines.

<mgmt_net>

Mandatory when <vm_mgmt> attribute type="net", forbidden otherwise. Unique. Empty tag.

This tag is used to configure behaviour of the the uml_switched management network when type="net" in <vm_mgmt> is used.

The tag has the following attributes:

• sock (mandatory). The path to the UNIX control socket associated with the uml_switch process that has been started for network management.
• hostip (mandatory). The IP address of the interface that is associated with the uml_switch process that has been started for network management. The address must be in the subnet defined by the network and mask attributes in the <vm_mgmt> tag.
• autoconfigure (optional). Allows the automatic configuration of the management socket and the associated network in the host, so user has not to bother with this error prone procedure. This attribute is only interpreted when root is running VNUML (because the socket creation and network configuration commands require root privileges) during the building topology (-t) and destroy (-d) modes:
  • building topology (-t): creates the TUN/TAP device (the value of the attribute is used as name; typically, autoconfigure="tap0") and starts the uml_switch for the management network (associated with the just created TUN/TAP device), creating the uml_switch UNIX socket in the process. See the mgmt_sock_create function in the code for details.
  • destroying topology (-d): kills the uml_switch for the management network, remove the socket file and removes the TUN/TAP. See the mgmt_sock_destroy function in the code for details.

<host_mapping>

Optional when <vm_mgmt> attribute is not type="none", forbidden in that case. Unique. Empty tag.

When used, virtual machine names (name attribute of <vm> tag) have to be mapped to the corresponding IPv4 private management address of that machine. This mapping is performed editing host /etc/hosts file. So, using <host_mapping> virtual machine can be accessed from the host with name instead IP address (for example, 'ssh -1 uml1' instead of 'ssh -1 192.168.0.2'). vnumlparser.pl maintains a section in the /etc/hosts file with the mappings from the running simulations, cleaning them when the simulations end. Users must not edit manually the VNUML section of /etc/hosts.Only root user can use this tag, due to it modifies /etc/hosts file, a root-owned file.

<tun_device>

Optional (default value: /dev/net/tun). Unique.

Specifies where the tun device used to create virtual network interfaces lives.The default tun device can be changed with --with-tun option of configure when building the VNUML package.

<vm_defaults>

Optional (default values specified below for each sub-tag). Unique.

This tag specifies default values to use in all virtual machines (specified indivually by <vm> tags). Its structure (the tags within it) is quite similar to the structure of <vm>. In particular, the <filesystem>, <mem>, <kernel>, <shell>, <basedir>, <mng_if>, <console>, <xterm>, <route>, <forwarding>, <user> and <filetree> can be used.

As general rule, the existence of a particular tag under <vm> overrides the one specified in <vm_defaults>. Follows a description of all each default, along with the implicit default value (used when no default value is specified in <vm_defaults>):

<exec_mode>

<vm_defaults>
    <exec_mode type="uml">mconsole</exec_mode>
    <exec_mode type="libvirt" subtype="kvm">cdrom</exec_mode>
    <exec_mode type="libvirt" subtype="kvm" os="windows">cdrom</exec_mode>
    <exec_mode type="libvirt" subtype="kvm" os="olive">sdisk</exec_mode>
</vm_defaults>

<console>

<vm_defaults>
    <console id="0" display="no"/>
    <console id="1" display="yes"/>
</vm_defaults>

To be revised:

• <filesystem>, unique, default value: PREFIX/vnuml/filesystems/root_fs_tutorial with type="cow". Types "direct" and "hostfs" are forbidden as default.
• <mem>, unique, default value: 32M. Since 1.8.9: the default has been increased to 64MB.
• <kernel>, unique, default value: PREFIX/vnuml/kernels/linux.
• <shell>, unique, default value: /bin/bash (it can be changed with --with-shell option of configure when building the VNUML package)
• <basedir>, unique, default value is the directory where the XML file of the specification is located.
• <mng_if>, unique, default is to use management interface.
• <console>, multiple. In the case of tags is both <vm_defauls> and <vm> they are merged and used together. In the case of two <console> with the same id attribute the one in <vm> overrides the other.
• <xterm>, unique, default is not to use xterm.
• <route>, multiple. In the case of tags is both <vm_defauls> and <vm> they are merged and used together. In the case of two <route> with the same type attribute and tag value (destination of the route) the one in <vm> overrides the other.
• <forwarding>, unique, default is not to forward.
• <user>, multiple. In the case of tags is both <vm_defauls> and <vm> they are merged and used together. In the case of two <user> with the same username attribute the one in <vm> overrides the other.
• <filetree>, multiple. In the case of tags is both <vm_defauls> and <vm> they are merged and used together. In the case of two exactly equals <filetree> (in root and seq attributes and tag value) the one in <vm> overrides the other.

In addition, <vm_defaults> has an optional attribute: exec_mode. This attribute is used as default execution mode, when no mode attribute is used in <exec> and <filetree>. If omitted, default exec_mode is "net".

<help>

Example:

    <help>
         <seq_help seq='start-www'>Start apache2 web server</seq_help>
         <seq_help seq='stop-www'>Stop apache2 web server</seq_help>     
    </help>

Virtual networks: <net>

Tag <net> configures virtual networks for the simulation. Each network created with <net> consists of a virtual interconnection point among machines (virtual or the host). Network configuration (IP address and mask) is not performed with <net>; it is performed with <if> and <hostif> interface description tags. The name attribute identifies the network. This name is used by the net attribute of <if> (and <hostif>) tag to specify the network to which the interface of the virtual machine (or host) interface is connected.

Since 1.8.5: "lo" is a reserved word and can not be used as net name.

Other attributes:

• mode. Mandatory. Two allowed values:
  • Virtual bridged base networks (with mode attribute set to "virtual_bridge"). Virtual network implementation in the host environment is performed using a virtual bridge created with 'brctl' command. User root privileges are needed to create this kind of network.
  • Uml switch based networks (with mode attribute set to "uml_switch"). Virtual network implementation in the host environment is performed using a uml_switch process. No user root privileges are needed to create this kind of network.
• type. Optional. Two types of networks are implemented:
  • LAN based networks (with type attribute set to "lan" or by default). This is a conventional Ethernet network. It can be seen as a broadcast interconnection point between the virtual machines to it connected.
  • PPP based networks (with type attribute set to "ppp"). This kind is intended to emulate a PPP link between two virtual machines. PPP networks have the following special characteristics:
    • Exactly two virtual machines must be connected to the PPP network (net attribute in a <if>)
    • 'pointopoint' attribute is used when configuring the network in the virtual machines (see ifconfig(8) man page).
    • A bandwidth for the link must be specified using <bw>
• For virtual bridged networks. The external attribute is related with the interconnection of the virtual network with external networks to which the host is connected. The value of this attribute must be the interface name in the host operating system (it can be an actual interface, such as "eth1" or one virtualized at the operating system level, such as "eth1.22") to which the virtual network will be connected. Additionally, if the vlan attribute is in use (set to a VLAN number) vnumlparser.pl manages the VLAN configuration. See VNUML User Manual for details.
• For uml_switch networks:
  • The hub attribute set to "yes" configures uml_switch process in hub mode (the default behaviour is as switch).
  • The sock attribute contains the file name of a socket on which a uml_switch is running. If the file exists and is read/writable, then instead of starting a new uml_switch process on the host, a symbolic link is created, pointing to the existing socket. This way, the root user can create switches and set their permissions ahead of time (as well as attach the uml_switch to a tap interface using the -tap option, allowing communication with external networks to which the host is connected).
  • The uml_switch_binary attribute set the path to the uml_switch binary (by default, the uml_switch binary is search in the enviromental PATH). It is useful using with <capture> tag, in order to mantain the new version of uml_switch along the traditional one.
  • Several attributes related with traffic capture. In order to use them, you need a special version of the uml_switch binary (therefore, you maybe need to use uml_switch_binary attribute). See Esteban's Martin (contrib/uml_router directory in the VNUML package) for details:
    • The capture_file attribute sets the file where the packets captured will be written. This file must not exist, in order to avoid remove valuable data (this condition is checked by the parser).
    • The capture_expression attribute establish the filter that will be applied to capture traffic. Only can be used with file attribute. These expressions use the tcpdump syntax.
    • The capture_dev attribute indicates the interface name that can be used with tools like ethereal to study network packets in real time. Filters expression does not affect to this capture, all packets will be captured. Only root can use this feature.

Notes:

• The capture_file, capture_expression and capture_dev attributes replaces the ones used with the <capture> interin tag (that is no longer used).

• Virtual bridge specific attributes are ignored in uml_switch networks and vice-versa.More information about types and modes can be found in the VNUML User Manual.

• It is possible to connect virtual machines of different concurrent simulations without problems as long as all simulations would be using the same exact <net> tags for the shared networks (including mode, type and sock).

• As many <net> tags as needed can be defined (including zero), but these names cannot be duplicated (value of the name attribute).

• Since version 1.8 there is a name length limit of 7 characters (this is not a limitation of vnumlparser.pl itself; it is because 'brctl show' truncates names if they are very long). Also, the name of a network may not end with "_Mgmt", as that suffix is reserved for management networks defined with the <mgmt_net> tag.

<bw>

Mandatory when <net> type is "ppp", forbidden otherwise. Unique.

Specifies the bandwidth that will be used in an emulated PPP link. The bandwidth limitation is established on the outgoing traffic of both virtual machines connected with the PPP using tc.

Warning:You must use a UML kernel with QoS management enabled and have the tc tool installed in your filesystem when using <bw>.

Virtual machines: <vm>

Each <vm> tag describes a virtual UML machine. It uses the name attribute to specify the name for the virtual machine (vnumlparser.pl uses this name to identify the machine). Version 1.8 has a name length limit of 7 characters (this is not a limitation of vnumlparser.pl itself; it is because 'brctl show' truncates names if they are very long).

The optional order attribute, that uses a positive integer value (for example, order="2"), establishes the order in which virtual machine will be processed (for example, which virtual machine will be boot/halt first). Virtual machines with no order are processed last, in the same order in which they appear in the VNUML file.

As many <vm> tags as needed can be defined (including zero), but there names cannot be duplicated (value of the name attribute). The number of virtual machines with management interfaces is limited to the management interfaces that can be configured, based on the settings of <vm_mgmt> . Anyway, if <automac> is in use there is a more restrictive limitation of 255 maximum virtual machines with 255 maximum interfaces each per simulation.

Within <vm> several tags configures the virtual machine environment.

<filesystem>

Optional (default specified with <vm_defaults>). Unique.

Each UML kernel needs a root filesystem. Different from a conventional Linux kernel booting, where the root filesystem usually is in a disk partition, the UML root filesystem lies in a file (or directory hostfs filesystems) on the host underlying filesystem. The absolute pathname of that file (or directory, for hostfs filesystems) is specified with the <filesystem> tag.

This tag uses type, to specify how to use the filesystem file:

• type="direct". <filesystem> value is that file that will be use to boot the virtual machine.
  Warning regarding persmissions: if you use direct mode, the filesystem file must have write permission for the user that boots the UML (this user is 'vnuml', at least other would be specified with the -u switch, see [../user/index.html#privilege_separation User Manual] for details). Otherwise, the UML apparently boots correctly but hangs mysteriously during the booting process.
• type="cow". <filesystem> value is a master filesystem, that will be used in a copied-on-write fashion (COW). The modifications file lies in the working directory of vnumlparser.pl (by default, ~/.vnuml/simulations/simulation_name/fs). This saves a lot of storage space, so COW mode is recommended to boot UMLs.
  

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. Therefore, it is advisable to purge (vnulmparser.pl -P) that simulations before (or event removing directly their directory under ~/.vnuml/simulations to be sure).

• type="hostfs". <filesystem> value is a hostfs directory where the user (root or non-root) that runs the vnumlparser.pl has read/write access. See the hostfs description at the UML Web page for additional information about this kind of filesystem.

The default working directory (~/.vnuml) can be changed at simulation time by using the -c switch.

Note that there are certain requirements for the filesystem (master or copy). See VNUML User Manual.

Note for old users: old value "copy" for type attribute was removed in DTD 1.7.

<mem>

Optional (default especified with <vm_defaults>). Unique.

Specifies the amount of RAM memory used in the virtual machine. Suffixes 'k', 'K', 'm' and 'M' can be used for (k|K)ilobytes and (m|M)egabytes.

<kernel>

Optional (default specified with <vm_defaults>). Unique.

Specifies the UML kernel file absolute path name to boot the virtual machine. Note that the file must be executable.

This tag allows several attributes (all of them optional):

• initrd. If the kernel is built with initrd support, then this attribute should indicate the location of the appropriate initrd. Otherwise, the initrd attribute should not be used.

• root. Specifies explicitly the device to use for the root filesystem.

• devfs. Specifies wheter mount devfs (for devfs capable kernels, with "mount") or not (with "nomount")

• modules. Specifies a directory in the host filesystem that replaces (using hostfs mounting) the /lib/modules directory in the virtual machine using that kernel.

• trace (allowed values: "on", "off"). If "on" is used, then UML verbose startup traces are shown in the terminal. Useful for debugging when there are problems with UML booting. If omitted, trace="off" is assumed.

If you are familiar with UML or kernel booting in general, note that some of this attributes directly map to the UML kernel booting statement (see UML kernel switches for some details), in particular:

• initrd maps to 'initrd=' switch
• root maps to 'root=' switch
• devfs maps to 'devfs=' switch
• trace="on" maps to 'stderr=1'

<shell>

Optional (default specified with <vm_defaults>). Unique.

Specifies which shell interpreter to use for command scripts generated by vnumlparser.pl.The default bash interpreter can be changed with --with-shell option of configure when building the VNUML package.

<basedir>

Optional (default specified with <vm_defaults>). Unique.

Set the root path used for <filetree> tags: the path specified in <filetree> is relative to the value in <basedir> (when the filetree path doesn't start with "/").

Note that if no <basedir> is defined, <filetree> not starting with "/" are interpreted relative to the place where the XML specification file is located.

The aim of this tag is to easily allow to move configuration files for virtual machines that are loaded using <filetree>. For example, let configurations for three virtual machines are under /tmp:

• /tmp/confs/host1 for virtual machine host1

• /tmp/confs/host2 for virtual machine host2

• /tmp/confs/host3 for virtual machine host3

In the VNUML file this could be specified using <basedir>:

...
<basedir>/tmp/confs</basedir>
...
<vm name="host1">
   ...
   <filetree root="/etc/program">host1</filetree>
   ...
</vm>
<vm name="host1">
   ...
   <filetree root="/etc/program">host2</filetree>
   ...
</vm>
<vm name="host1">
   ...
   <filetree root="/etc/program">host3</filetree>
   ...
</vm>
...

Now if the configurations are moved to other place (for example, mv /tmp/confs/* /root/confs), only the <basedir> needs to be changed (you don't need to touch <filetree> tags).

...
<basedir>/root/confs</basedir>
...
<vm name="host1">
   ...
   <filetree root="/etc/program">host1</filetree>
   ...
</vm>
<vm name="host1">
   ...
   <filetree root="/etc/program">host2</filetree>
   ...
</vm>
<vm name="host1">
   ...
   <filetree root="/etc/program">host3</filetree>
   ...
</vm>
...

<mng_if>

Optional (default specified with <vm_defaults>). Unique.

A <mng_if>no</mng_if> specifies that no management interface will be set and configured for this virtual machine. The network connection relies entirely on the virtual network, and it is up to the user to correctly configure the networks, so the virtual machine is routable from the host.Any other value (for example, <mng_if>yes</mng_if> or even <mng_if />) implies the use of the management interface. Values different from no only make sense when <mng_if>no</mng_if> is used within <vm_defaults> and the default configuration want to be overriden in a particular <vm> .

<console>

Optional. Multiple.

By default, each virtual machine is booted without any I/O channel so, appart networking (supposing it has been configued properly) there is no way to the user to interact with the virtual machine. This approach is fine for some hosts enviroments (for example, a server where no X server is available) but you maybe want a way of directly access to the virtual machine to login and introduce commands, as you will do in a conventional machine.

The <console> comes to solve this problem. It allows you to specify you want to access the virtual machine through a xterm, a tty line or a pts line. You can especify several consoles (each one with a different id attribute.

Examples of use:

• Output to a xterm (only if X environment is available in the host).

   <console id="0">xterm</console>

• Output to tty8 (ensure first that tty8 is not already in use in your system).

   <console id="0">tty:/dev/tty8</console>

• Output to pseudo-terminal. After UML booting, you will need to find out the pts dev file (through "uml_mconsole config con0") and create the appropriate screen connection (further information in screen(1)).

   <console id="0">pts</console>

• All communication channels at the same time:

   <console id="0">xterm</console>
   <console id="1">tty:/dev/tty8</console>   
   <console id="2">pts</console>

If you are familiar with UML, note that <console id="n"> maps to conn= switch in the UML kernel booting line. More information on this topic can be found in the UML Project web site.

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 differente xterm program with <xterm> (for example, gnome-terminal) is recommended.

<xterm>

Optional (default specified with <vm_defaults>). Unique.

Specify the command used to run the xterm for the virtual machine for <console> tags specifying xterm (note that if no <console id="n">xterm</console> is used, this tag is useless). It may be useful for using specific xterms or configure them with special parameters. For example:

   <xterm>gnome-terminal,-t,-x</xterm>

Since 1.6.2 (using UML kernel >= 2.6.12.3-bs9-1m): for xterm and gnome-terminal, you can specify a title for the terminal window.

• For xterm:

   <xterm>xterm,-T title,-e</xterm>

• For gnome-terminal:

   <xterm>gnome-terminal,-t title,-x</xterm>

<if>

Optional. Multiple.

This tag describes a network interface in the virtual machine. It uses two attributes: id and net.

Attribute id identifies the interface. The name of a virtual machine interface with id=n is ethn. If the network to which it is connected (the net attribute) is a virtual_bridge (the mode attribute of the corresponding <net>), or if the virtual machine is using private management (the type attribute of <vm_mgmt>), then the name of the corresponding interface, created on the host is name-ethn (where name is the name of the virtual machine). Note that with this schema, there aren't duplicated names. Read more about this in the VNUML User Manual.

Id values start with 1. Id 0 is reserved for the management interface. This interface is used by vnumlparser.pl to send commands to the virtual machines when executing remote command sequences (-x switch). It can also be used by the user along the life cycle of the simulation, if desired (the most common use is accessing virtual machines using SSH: 'ssh -1 uml1', for example).

Attribute net specifies the virtual network (using name value of the corresponding <net>) to which the interface is connected. Since 1.8.5, you can also use the reserved word "lo" to configure loopback interfaces (instead of conventional eth interfaces). In this case the id atribute is the loopback suffix (e.g., <if net="lo" id="3"> configures interface "lo:3").

Within <if> several tags can be used.

<mac>

Optional. Unique.

Specifies MAC address for the interface inside UML. If not used, vnumlparser.pl assigns one automatically (if <automac> is in use) or relies in UML to assign one (this is possible if the interface has a IPv4 address assigned; it is not possible if it only has IPv6 addresses).

To avoid problems, uses fe:fd: as the first two bytes of the MAC address and ensure that there are not duplicated MAC addresses in the union of interfaces of all concurrent simulations (at least, in interfaces connected to the same network). This can be achieved using <automac> tag (using appropriated offset values in the case of several concurrent simulations), without using <mac>.

This tag is also useful when you run virtual machines inside VMware. See this post in the vnuml-users list to know details.

Since 1.8.5: this tag is forbidden within <if> with name="lo" (because of defining a MAC address in a loopback interface has no sense).

<ipv4>

Optional. Multiple.

Specifies an IPv4 address for the interface. The mask can be specified as part of the tag value (for example, <ipv4>10.1.1.1/24</ipv4>) or using the optional mask attribute either in dotted or slashed notation (for example, <ipv4 mask="/24">10.1.1.1</ipv4> or <ipv4 mask="255.255.255.0">10.1.1.1</ipv4>).

If the mask is not specified (for example, <ipv4>10.1.1.1</ipv4>) 255.255.255.0 (equivalently /24) is used as default.

Using mask attribute and the mask prefix in the tag value at the same time (for example, <ipv4 mask="/24">10.1.1.1/24</ipv4>) is not allowed.

<ipv6>

Optional. Multiple.

Specifies an IPv6 address for the interface. The mask can be specified as part of the tag value (for example, <ipv6>3ffe::3/64</ipv6>) or using the optional mask attribute in slashed notation (for example, <ipv6 mask="/64">3ffe::3/64</ipv4>). Note that, different from <ipv4> , dotted notation is not allowed in <ipv6>.

If the mask is not specified (for example, <ipv6>3ffe::3/64</ipv6>) /64 is used as default.

Using mask attribute and the mask prefix in the tag value at the same time (for example, <ipv6 mask="/64">3ffe::3/64</ipv6>) is not allowed.

<route>

Optional. Multiple.

Specifies a static route that will be configured in the virtual machine routing table at boot build topology (-t switch) time. Really, it is not necessary to use this tag to configure routes, the same functionality can be obtained using the 'route' command in the UML environment.

The routes added with this tag are gateway type (gw). Two attributes are used: type (allowed values: "ipv4" for IPv4 routes or "ipv6" for IPv6 routes) and gw, that specifies the gateway address. The value of the tag is the destination (including mask, using the '/' prefix) of the route.

Note that the default IPv4 route is 0.0.0.0/0, while the default IPv6 route is 2000::/3 for global addresses (IPv6 define several types of addresses: global, site-local, link-local, etc, see RFC 2373).

Note for old users: the type allowed values were "inet" (instead of "ipv4") and "inet6" (instead of "ipv6") in VNUML DTD 1.6 and before.

<forwarding>

Optional (default specified with <vm_defaults>). Unique.

Activates IP packet fowarding for the virtual machine (packets arriving at one interface can be forward to another, using the information in the routing table). This tag uses the optional type attribute (default is "ip"): allowed values are: "ipv4", that enables forwarding for IPv4 only; "ipv6", that enables forwarding for IPv6 only; and "ip" that enables forwarding for both IPv4 and IPv6.

The forwarding is enabled setting the appropriate kernel signals under /proc/sys/net.

<user>

Optional. Multiple.

Allows the creation of users on the virtual machine at building topology (-t switch) time. It uses two attributes:

• The username attribute sets the user name. If this user already exists in the virtual machine, the user is not created again, only group additions can be made (this way users that already exist on the system won't lose the group membership to which they already belong. If a group membership needs to be revoked, then the user must perform this manually by logging in to the virtual machine).
• The group attributes set the effective group. This group must exist as a <group> tag. If no group attribute is specified, then the system default on the virtual machine will be used.

In the case where the value for username is root, no group changes will be made. However, the specified public keys in <ssh_key> (as child of <user>) will still be placed in the appropriate authorized_keys file.

Note that users are created withoug password, so conventional login will not work. However, <ssh_key> (as child of <user>) provides an effective workaround.

<group>

Optional. Multiple.

Specifies additional groups to which the user will be added. If the group does not exist, then it will be created on the virtual machine using groupadd.

<ssh_key>

Optional. Multiple.

The content of the SSH public key found in each <ssh_key> tag within the <user> environment will be placed in the $HOME/.ssh/authorized_keys file, where $HOME is the home directory for that user. If a key already exists, then it will not be added again.

<filetree>

Optional. Multiple.

Specifies a filetree (a directory, as well as all its files and subdirectories) in the host filesystem that will be copied to the virtual machine filesystem (overwriting existing files) during execution commands mode (-x mode, or the the deprecated -s and -p). This tag allows easily copying of entire configuration directories (as /etc) that are stored and edited from host when preparing simulations.

• If the directory starts with "/", then it is an absolute directory.
• If the directory doesn't start with "/", then it is relative to <basedir> tag; if no <basedir> is defined, it is relative to the directory where the XML specification file is located.

Three attributes are used:

• root. Specifies where (in the virtual machine filesystem) to copy the filetree.

• seq. The name of the commands sequence that triggers the copy operation when used in -x mode. Note that filetree copy is made before processing <exec> commands.

• mode (optional; default specific with exec_mode atribute in <vm_default>; allowed values: "net", "mconsole", "pts"). Define how files will be copied:
  • "mconsole". Files are copied using the uml_mconsole exec command and the hostfs shared directory (between host and virtual machine). This is the most direct and efficiente copying and doesn't need a management network, so it is recommended. This mode requires virtual machines implement the mconsole exec support in the kernel.
  • "net". Files are copyied using the management network (so, a management network has to be properly configured using <vm_mgmt>). This method was the one used in VNUML 1.7 and before and maintainted in newer versions for backward compatibility mainly.
  • "pts". Not developed yet.

• user (optional). Specifies the user used to perform the copy. If no user is specified, the root is used as default.
  

Warning: the use of the user attribute does not guarantee neither the creation of the user nor the installation of SSH keys that would avoid typing passwords. The <user> and <ssh_key> (as child of <user>) tags can be used to do that.

Note for old users: in VNUML 1.8, when attribute has been renamed to seq (to be coherent with <exec>). In addition, the "always" reserved word has no longer a special meaning.

<exec>

Optional. Multiple.

Specifies one command to be executed by the virtual machine during executing commands sequence mode (-x switch).

Attributes:

• seq (mandatory). It is a string that identifies the command sequence, to used in the -x parameter (for example, '-x sample@file.xml'). The relative order of the executed commands is the same order in which they appear in the VNUML file.

• type (mandatory; allowed values: "verbatim", "file"). Using "verbatim" specifies that the tag value is the verbatim command to be executed. Using "file", the tag value points (with absolute pathname) to a file (in the host filesystem) with the commands that will be executed (line by line).

• mode (optional; default specific with exec_mode atribute in <vm_default>; allowed values: "net", "mconsole", "pts"). Define how commands will be executed (note that this attribute is not allowed within <host>, commands in host are always executed direclty):
  • "mconsole". Commands are executed using the uml_mconsole exec command and the hostfs shared directory (between host and virtual machine). This is the most direct and efficiente execution method and doesn't need a management network, so it is recommended. This mode requires virtual machines implement the MCONSOLE_EXEC kernel option.
  • "net". Commands are executed using the management network (so, a management network has to be properly configured using <vm_mgmt>). This method was the one used in VNUML 1.7 and before and maintainted in newer versions for backward compatibility mainly.
  • "pts". Not developed yet.

• user (optional). It can be used in to specify the user that will execute the commands. If no user is specified root is used as default. Note that this attribute is not allowed within <host>, commands in host are always executed as root.

Warning: the use of the user attribute does not guarantee neither the creation of the user nor the installation of SSH keys that would avoid typing passwords. The <user> and <ssh_key> (as child of <user>) tags can be used to do that.

Example: given the following fragment of file file.xml

   ...
   <exec seq="sample" type="verbatim">/usr/local/bin/sample1.sh</exec>
   <exec seq="test" type="verbatim">/usr/local/bin/test1.sh</exec>
   <exec seq="sample" type="verbatim">/usr/local/bin/sample2.sh</exec>
   <exec seq="test" type="verbatim">/usr/local/bin/test2.sh</exec>
   ...

the following vnumlparser.pl command:

vnumlparser.pl -x sample@file.xml

will execute in the particular virtual machine or host the following commands:

/usr/local/bin/sample1.sh
/usr/local/bin/sample2.sh

Using type="verbatim" may be more direct. But, using "file" has some advantages:

1. A long list of commands can be put in the file, so the VNUML file keeps short.
2. A script can be specified.
3. Avoid "verbatim" limitations with commands that includes <, > and & characters, not allowed in a XML file.

Host configuration: <host>

This task deals with host configuration. It is optional, and if the host is not a participant part of the simulation, it should not be used.

Only root user can use this tag.

The <host> tag is similar to <vm> . In particular, tags <route>, <forwarding> and <exec> are used with the same semantics described previously (exception: user and mode attributes are forbbiden in <exec>). Additionally, there are several tags that only can be used inside <host>.

<hostif>

Optional. Multiple.

This tag is quite similar to <if> tag of the virtual machines. The semantic differences are described below:

• The net attribute is used with the same semantic, but the name of the interface in the host environment is the same as the value of the attribute. For example, with net="Network0" the interface name is Network0 (as a 'ifconfig Network0' would show it). Note that id attribute is not used.
• <mac> tag is not valid here.
• <ipv4> and <ipv6> do not have any difference.

Note that if a host physical interface is being used as external interface (is external in any <net> tag) and it will be used for accessing host, <hostif> must be used to defining its configuration. This is due to when adding a physical interface to the bridge that implements the virtual network, previous interface configuration is lost. See VNUML User Manual about external connections.

<physicalif>

Optional. Multiple.

Empty tag.This tag is used by vnumlparser.pl only during destroying topology mode (-d switch). When removing virtual networks defined by <net> tags, physical interfaces does not recover previous configuration automatically. If we want vnumlparser.pl recover this configuration automatically, a <physicalif> tag must be used for this interface. The attributes are: type ("ipv4" or "ipv6"), name (interface name), ip (interface IP address, including mask in the case of IPv6 interface -e.g., /64), mask (network mask, only makes sense with IPv4 interfaces, ignored other case) and gw (default gateway). Note that default gateway is not really interface configuration (it is routing configuration), but the default route is lost when the interface bound to it loses its network configuration, so in this case it is necessary to recover it.

As much as two <physicalif> can be defined per interface: one type="ipv4" and another type="ipv6".