VNUML Language Reference
version 1.4

Author:
Fermín Galán (galan@dit.upm.es)

October 23th, 2003



Virtual Network User Mode Linux
Contents

1. Introduction
2. Global definitions: <global>
   2.1. <version>
   2.2. <simulation_name>
   2.3. <ssh_key>
   2.4. <automac>
   2.5. <ip_offset>
   2.6. <netconfig>
   2.7. <host_mapping>
   2.8. <shell>
   2.9. <tun_device>
   2.10. <default_filesystem>
   2.11. <default_kernel>
   2.12. <basedir>
3. Virtual networks: <net>
4. Virtual machines: <vm>
   4.1. <filesystem>
   4.2. <mem>
   4.3. <kernel>
   4.4. <boot>
      4.4.1. <con0>
   4.5. <mng_if>
   4.6. <if>
      4.6.1. <mac>
      4.6.2. <ipv4>
      4.6.3. <ipv6>
   4.7. <route>
   4.8. <forwarding>
   4.9. <filetree>
   4.10. <start>
   4.11. <stop>
5. Host configuration: <host>
   5.1. <hostif>
   5.2. <physicalif>


1. Introduction

VNUML is a XML language. The DTD version 1.4 can be found here and is the absolute syntactic referente. This document will describe the semantics of the tags on this DTD.

As any other well-formed XML files, all VNUML files start with the following two lines:

<?xml version="1.0"?>
<!DOCTYPE vnuml SYSTEM "/usr/local/share/xml/vnuml/vnuml.dtd">

where location of the DTD file in the host filesystem must be specified (in the example above, this file is /usr/local/share/xml/vnuml/vnuml.dtd). In theory, it's also possible to use and URI, instead of a file in the filesystem.

Note that the default DTD file location is PREFIX/share/xml/vnuml/vnuml.dtd (/usr/local/share/xml/vnuml/vnuml.dtd if using the standard prefix in configure when building the VNUML package).

Note that DTD version 1.4 is a bit strict about the relative order of the tags.

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 VNUML file are <global> (describing global elements of the simulation), <net> (describing virtual networks), <vm> (virtual machine specification) and <host> (host configuration).



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

2.1. <version>

Required. Unique.

Specifies which VNUML languaje version is being used in the file. It's used to perform a sanity check againts the vnumlparser.pl that reads the file (VNUML files version 1.4 only can be parsed with vnumparser.pl version 1.4.x). For VNUML version 1.4 the value of this tag is:

<version>1.4</version>

2.2. <simulation_name>

Required. Unique.

Specifies simulation name. Each simulation must have a diferent name.

2.3. <ssh_key>

Optional. Unique.

When used, specifies the absolute filename of the host SSH public key. This key will be installed in /root/.ssh/authorized_keys (really, this is symlinked to /opt/authorized_keys, see VNUML User Manual) in the virtual machine's filesystem. It is needed to avoid being prompted about password while starting and stopping simulation modes, as well as non-forced destroying simulation mode (-s, -p, -r and -d switches of vnumlparser.pl). So, user interaction is minimal.

The version attribute can be used to choose the SSH version: "1" for SSHv1 or "2" for SSHv2.

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.

2.4. <automac>

Optional. Unique. Empty tag.

When used, MAC address for the virtual machines interfaces are generated automaticly, 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).

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 of several concurrent simulations using automac whose machines are connected among them, diferent offset values should be used in each simulation. In other case, it would happen that two virtual machines have the same MAC address, leading to wrong network configuration.

When <automac> is used with <mac> inside <if>, address specified in <mac> takes preference. Note that a wrong use of <mac> can cause duplicated address, becuase it would coincide with an automatic generated one.

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

2.5. <ip_offset>

Optional (default value: 0). Unique.

Specifies desired offset when generating IPv4 management private addresses (used for management interfaces, id 0).

By default, the first 2 bytes are hardwired to "192.168". If you want to override that, you need to use prefix attribute. For example, to use "10.60" you must use:

<offset prefix="10.60" />

In addition, the default offset is 0 so the addresses start from 192.168.0.1 (in general X.Y.0.1, if prefix is in use). You should use other offset value if private addresses in this range are already in use in the host enviroment or conflicts may arose. Note for each virtual machine 4 addresses are taken. To know how <ip_offset> value is exactly used, see get_admin_address functions in the vnumlparser.pl code.

Note that when using several concurrent simulations, the use of diferent <ip_offset> and/or different prefix values in each one is a must. See VNUML User Manual about concurrent simulations for details.

2.6. <netconfig>

Optional (default attributes values: stp="off" and promisc="on"). Unique. Empty tag.

Allows setting up the way vnumlparser.pl configures interfaces and bridges. It uses two attributes: stp (allowed values: "on" and "off") that enables/disables STP (Spanning Tree Protocol) for the virtual bridges created by the parser, and promisc (allowed values: "on" and "off") that enables/disables promiscuous mode for the interfaces set up by the parser.

2.7. <host_mapping>

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

2.8. <shell>

Optional (default value: /bin/bash). 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.

2.9. <tun_device>

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

Specifies whrere the tun device used to create virtualized network interfaces lives.

This tag is supported from vnumlparser.pl 1.3.1 and beyond. Version 1.3.0 silently ignores it (always use the default value, /dev/net/tun).

The default tun device can be changed with --with-tun option of configure when building the VNUML package.

2.10. <default_filesystem>

Optional (default value: PREFIX/vnuml/filesystems/root_fs_tutorial). Unique.

Set the default filesystem that will be used in virtual machines when the <filesystem> is missing. The type attribute set the default filesystem type: "cow" or "copy". Types "direct" and "hostfs" are not allowed in the <default_kernel> tag.

If no <default_filesystem> is present, the default filesystem is PREFIX/vnuml/filesystems/root_fs_tutorial (/usr/local/share/vnuml/filesystems/root_fs_tutorial if using the standard prefix in configure when building the VNUML package) and default type is "cow".

2.11. <default_kernel>

Optional (default value: PREFIX/vnuml/kernels/linux). Unique.

Set the default kernel that will be used in virtual machines when <kernel> tag is missing.

If no <default_kernel> is present, the default kernel is PREFIX/vnuml/kernels/linux (/usr/local/share/vnuml/kernels/linux if using the standard prefix in configure when building the VNUML package).

2.12. <basedir>

Optional (default value: /). Unique.

Set the root path used for <filetree> tags. The path specified in <filetree> is relative to the value in <basedir>.

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="/ect/program">host1</filetree>
   ...
</vm>
<vm name="host1">
   ...
   <filetree root="/ect/program">host2</filetree>
   ...
</vm>
<vm name="host1">
   ...
   <filetree root="/ect/program">host3</filetree>
   ...
</vm>
...

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

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


3. Virtual networks: <net>

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

Currenlty, two kind of networks are implemented:

  • Virtual bridged base networks (with type attribute set to "virtual_bridge" or by default when type attribute is not present). Virtual network implementation in the host enviroment is performed using a virtual bridge created with 'brctl' command. User root privilegies are needed to create this kind of networks.
  • Uml switch based networks (with type attribute set to "uml_switch"). Virtual network implementation in the host enviroment is performed using uml_switch process. No user root privilegies are needed to create this kind of networks.

Additional attributes:

  • 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, as "eth1" or a virtualized -at operating system level- one, as "eth1.22") to which the virtual network will be connected. Additionally, if 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 set to "yes" configures uml_switch process in hub mode (the default behaviour is as switch).

Virtual bridge specific attributes are ignored in uml_switch networks and vice versa.

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

As many <net> tags as needed can be defined (including zero), but there can not be duplicated names (value of the name attribute). Version 1.4 has a name length limit of 7 characters (this is not a limitation of vnumlparser.pl itself, the problem is due to 'brctl show' truncates names if they are very long).



4. Virtual machines: <vm>

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

The optional order attribute, that uses a positive integer value (for example, order="2"), establish 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 are described in the VNUML file.

As many <vm> tags as needed can be defined (including zero), but there can not be duplicated names (value of the name attribute). There is an additional limitation (due to get_admin_address function implementation in the vnumlparser.pl code) of a 2^14 simultaneous virtual machines (a really huge number!). Anyway, if <automac> is in use there is a more restrictive limitation of 255 maximum virtual machines with 255 maximum interfaces each one per simulation.

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

4.1. <filesystem>

Optional (default: <default_filesystem> value and attribute). Unique.

Each UML kernel needs a root filesysem. Diferent from a convetional Linux kernel booting, where the root filesystem usually is in a disk partion, 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. You need to be run vnumparser.pl as root in order to use this type of filesystem.
  • type="copy". <filesystem> value is a master filesystem, that will be copied to the working directory of vnunlparser.pl (by default, /var/vnuml/simulation_name), then booted. You need to be run vnumparser.pl as root in order to use this type of filesystem.
  • 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, /var/vnuml/simulation_name). This saves a lot of storage space, so COW mode is recommended to boot UMLs. You need to be run vnumparser.pl as root in order to use this type of filesystem.
  • type="hostfs". <filesystem> value is a hostfs directory where the user that run the vnumlparser.pl (root or no-root user) has read-write accesses. See hostfs description in UML webpage for additional information about this kind of filesystem.

If this tag is not present, the default filesystem is the one specified with <default_filesystem>.

The the default working directory (/var/vnuml) can be changed with --with-writedata option of configure when building the vnuml package.

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

4.2. <mem>

Optional (default value: 32M). Unique.

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

4.3. <kernel>

Optional (default: <default_kernel> value and attribute). Unique.

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

If this tag is not present, the default kernel is the one specified with <default_kernel>.

Due to limitations of the current version, kernel name need to have the token 'linux' include. For example:

   <kernel>/usr/local/bin/linux-2.4.18-um51</kernel>

is a valid name, but

   <kernel>/usr/local/bin/mykernel</kernel>

it isn't.

4.4. <boot>

Optional. Unique.

This tag describes a set parameters that will be appended to the kernel command line used to boot the UML kernel. Note that vnumlparser.pl gives little (or even nothing) semantic value to this parameters: it just passes it to the UML kernel transparently.

Within <boot> several tags can be used.

4. 4. 1. <con0>

Optional. Unique.

The value of this tag will be passes as "con0=" parameter in the UML boot command line. Detailed information about con0 is given at UML Project web site.

Examples of use:

  • Output to a xterm (only if X11 enviroment is available in the host).
       <con0>xterm</con0>
    
  • Output to tty8 (ensure firts that tty8 is not already in use in your system).
       <con0>tty:/dev/tty8</con0>
    
  • 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 appropiate screen connection (further information in screen(1)).
       <con0>pts</con0>
    

4.5. <mng_if>

Optional. Unique.

A <mng_if>no</mng_if> specifies that no management interface will be set and configured for this virtual machines. Network connection relies enterely in virtual networks and is up to the user set right router to reach virtual machines.

4.6. <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. Interface id=n has name ethn in the UML enviroment and name-ethn in the host enviroment (where name is the name of the virtual machine owner of the interface). 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 that connects point-to-point UML with host. This interface is used by vnumlparser.pl while starting and stopping simulation modes, as well as non-forced destroying topology mode (-s, -p, -r and -d switches of vnulparser.pl). It can 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 ulm1', for example).

Attribute net specifies the virtual network (using name value of the corresponding <net>) to which the interface is connected.

Within <if> several tags can be used.

4. 6. 1. <mac>

Optional. Unique.

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

To avoid problems, uses fe:fd: as firt two byes 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 appropiated offset values in the case of several concurrent simulations), without usign <mac>.

4. 6. 2. <ipv4>

Optional. Multiple.

Specifies an IPv4 address for the interface. It uses the optional attribute mask (which default is "255.255.255.0", class C address) to set the mask to apply.

4. 6. 3. <ipv6>

Optional. Multiple.

Specifies an IPv6 address for the interface. Note that there is not mask attribute in this case: the mask have to be specified as a suffix using '/' (for example 3ffe:ffff::3/64, for a 64-bits mask).

4.7. <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 enviroment.

The routes added with this tag are gateway type (gw). Two attributes are used: type (allowed values: "inet" for IPv4 routes or "inet6;" for IPv6 routes) and gw, that specifies the gateway address. The value of the tag is the destination (including mask, usign '/' 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).

4.8. <forwarding>

Optional. 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 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 appropiated kernel signals under /proc/sys/net.

4.9. <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, overwritting existing files. That directory is relative to <basedir> tag; if no <basedir> is defined, <filetree> is an absoute directory path.

This tag allows easyly copying of entire configuration directories (as /etc) that are stored and edited from host when preparing simulations.

Two atributes are used:

  • root. Specifies where (in the virtual machine filesystem) to copy the filetree.
  • when. Allowed values: "start", "stop" or "always". Using "start" copy is made when starting simulation (-s switch). Using "stop" copy is made when stopping simulation (-p switch). Using "always" copy is made in both cases.
  • Note that filetree copy is made before processing <start> or <stop> commands.

4.10. <start>

Optional. Multiple.

Specifies one command to be executed by the virtual machine during starting simulation mode (-s switch). The relative order of the executed commands is the same order in which they appear in the VNUML file.

This tag uses type attribute with two allowed values. 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).

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

  1. A long list o 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 & characted, not allowed in a XML file.

4.11. <stop>

Optional. Multiple.

The syntax of this tag is the same as <start> and the only semactic diference is that the command is executed during stopping simulation mode (-p switch).



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

The <host> tag is quite similar to <vm>. Tags <route>, <forwarding>, <start> and <stop> are used with the same semantics described previously. Aditionally, there are several tags that only can be used inside <host>.

5.1. <hostif>

Optional. Multiple.

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

  • The net attribute is used with the same semantic, but the name of the interface in the host enviroment 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 brigde that implements the virtual network, previous interface configuration is lost. See VNUML User Manual about external connections.

5.2. <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 automactly. If we want vnumlparser.pl recover this configuration automactly, 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 gategay is not really interface configuration (it is routing configuration), but the default route is lost when the interface bound to it lost its network configuration, so in this case it is neccessary recover it.

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




Last update: