VNUML Language Reference
version 1.2

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

July 29th, 2003

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>
3. Virtual networks: <net>
4. Virtual machines: <vm>
   4. 1. <filesystem>
   4. 2. <mem>
   4. 3. <if>
      4. 3. 1. <mac>
      4. 3. 2. <ipv4>
      4. 3. 3. <ipv6>
   4. 4. <route>
   4. 5. <forwarding>
   4. 6. <filetree>
   4. 7. <start>
   4. 8. <stop>
5. Host configuration: <host>
   5. 1. <hostif>
   5. 2. <physicalif>

[Home]

1. Introduction

VNUML is a XML languaje. The DTD version 1.2 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 "/var/vnuml/vnuml.dtd">

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

It's possible to avoid DTD validation (althought it is strongly not recomended due to vnumlparser.pl heavy relies in that the VNUML source file is well-formed) using -k switch when calling parser. Note that DTD version 1.2 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 dos 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.2 only can be parsed with vnumparser.pl version 1.2.x). For VNUML version 1.2 the value of this tag is:


<version>1.2</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 v1 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.

To generate the public key uses the following command in the host:


ssh-keygen -t rsa1

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 offset is 0 so the addresses start from 192.168.0.1. 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> value 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').

NOTE: vnumlparser.pl versions 1.2.1 and before only edit /etc/hosts file adding the mapping while building topology mode (switch -t). The map entries are not deleted while destroying simulation mode (switch -d): manual edition is required. Anyway, the accumulation of duplicated entries in /etc/hosts is no problem, beyond the growing size of the file.

2. 8. <shell>

Optional (default value: /bin/bash). Unique.

Specifies which shell interpreter to use for command scripts generated by vnumlparser.pl.

3. Virtual networks: <net>

Tag <net> is an empty tag, that uses three attributes: name, external y vlan. The main attribute is name, that specifies network name. 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.

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). Virtual network implementation in the host enviroment is performed using virtual bridges created with 'brctl' command.

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.

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.

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

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>

Required. 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 on the host underlying filesystem. The absolute pathname of that file is specified with the <filesystem> tag.

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

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. <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. 3. 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. 3. 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. 3. 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. 4. <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. 5. <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. 6. <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. 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:

4. 7. <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. 8. <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:

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: name (interface name), ip (interface IP address), mask (network mask) 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.


Last update:
[Home]