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).
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. 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: Required. Unique. Specifies simulation name. Each simulation must have a diferent name. 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: Anyway, the first time that the key is used, confirmation is requested. Further information
in ssh-keygen(1) and ssh(1) man pages. 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: 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). 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. 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. 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. Optional (default value: /bin/bash). Unique. Specifies which shell interpreter to use for command scripts generated by vnumlparser.pl. 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). 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. 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. 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. 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. 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>. 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. 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). 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). 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. 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: Note that filetree copy is made before processing <star> or <stop> commands. 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: 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). 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>. 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. 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.2. Global definitions: <global>
2. 1. <version>
<version>1.2</version>
2. 2. <simulation_name>
2. 3. <ssh_key>
ssh-keygen -t rsa1
2. 4. <automac>
fe:fd:0:Z:X:Y
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]