VNUML Language
Reference
|
|
Contents | |
1. Introduction 2. Global definitions: <global> 2.1. <version> 2.2. <simulation_name> 2.3. <ssh_version> 2.4. <ssh_key> 2.4. <automac> 2.6. <netconfig> 2.7. <vm_mgmt> 2.7.1. <mgmt_net> 2.7.2. <host_mapping> 2.8. <tun_device> 2.9. <vm_defaults> 3. Virtual networks: <net> 3.1. <bw> 4. Virtual machines: <vm> 4.1. <filesystem> 4.2. <mem> 4.3. <kernel> 4.4. <shell> 4.5 <basedir> 4.6. <mng_if> 4.7 <console> 4.8 <xterm> 4.9. <if> 4.9.1. <mac> 4.9.2. <ipv4> 4.9.3. <ipv6> 4.10. <route> 4.11. <forwarding> 4.12. <user> 4.12.1. <group> 4.12.2. <ssh_key> 4.13. <filetree> 4.14. <exec> 5. Host configuration: <host> 5.1. <hostif> 5.2. <physicalif> Appendix: Changes |
|
1. Introduction | |
The VNUML language uses XML. The DTD version 1.7 (that comes with the VNUML package, in the data/ directory) is the absolute syntactic reference. This document will describe the semantics of the tags on this DTD. As with any other well-formed XML files, all VNUML files start with the following two lines: <?xml version="1.0"?> <!DOCTYPE vnuml SYSTEM "/usr/share/xml/vnuml/vnuml.dtd"> where the location of the DTD file in the host filesystem must be specified (in the example above, this file is /usr/share/xml/vnuml/vnuml.dtd). In theory, it's also possible to use a URI, instead of a file in the filesystem. The /usr/share/xml/vnuml/vnuml.dtd location is the one used
by the .deb VNUML package. If you installed from source .tgz
you would be using PREFIX/share/xml/vnuml/vnuml.dtd, where
PREFIX is /usr/local if using Note that DTD version 1.7 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 language version is being used in the file. It's used to perform a sanity check against the vnumlparser.pl that reads the file (VNUML files version 1.7 only can be parsed with vnumparser.pl version 1.7.x). For VNUML version 1.7 the value of this tag is: <version>1.7</version> 2. 2. <simulation_name>Required. Unique. Specifies simulation name. Each simulation must have a different name. 2. 3. <ssh_version>Optional (default is 1). 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> 2. 4. <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 remote command execution is performed (in particular when the the -x, switch is passed to vnumlparser.pl), 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. Note for old users: the version attribute in <ssh_key> in version 1.5 and before has been replaced by <ssh_version>. 2. 5. <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). 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). 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.<vm_mgmt>Optional. Unique. This tag configures several aspects related to the management interface of the virtual machines. This interface is used by vnumlparser.pl to send commands to the virtual machines when executing remote command sequences (-x, -s (deprecated), -p (deprecated), and -r switches to vnumlparser.pl). It also can be used by the user to access the virtual machine through SSH. The tag has the following attributes:
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:
The offset attribute is intended to avoid address collision when 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. Note for old users: version 1.5 and before used type="private" implicitly. Note also that the <ip_offset> global tag is no longer used: use the network, mask and offset attributes instead. 2. 7. 1.<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:
2. 7. 2.<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. Note for old users: in version 1.5 and before <host_mapping> was child of <global>, now is child of <vm_mgmt>. 2. 8. <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 2. 9. <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 <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>):
|
|
3. 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. Other attributes:
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 there names cannot be duplicated (value of the name attribute). Version 1.7 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). 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. 3. 1. <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>. |
|
4. 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.7 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. 4. 1. <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:
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. 4. 2. <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. 4. 3. <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):
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:
4. 4. <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 4. 5. <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>. 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:
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 ... <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> ... 4. 6. <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 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>. 4. 7. <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:
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. 4. 8 <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.
<xterm>xterm,-T title,-e</xterm> <xterm>gnome-terminal,-t title,-x</xterm> 4. 9. <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. Within <if> several tags can be used. 4. 9. 1. <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. 4. 9. 2. <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. 4. 9. 3. <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. 4. 10. <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. 4. 11. <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. 4. 12. <user>Optional. Multiple. Allows the creation of users on the virtual machine at building topology (-t switch) time. It uses two attributes:
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. 4. 12. 1. <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. 4. 12. 2. <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. 4. 13. <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). That directory is relative to <basedir> tag; if no <basedir> is defined, <filetree> is an absolute directory path. This tag allows easily copying of entire configuration directories (as /etc) that are stored and edited from host when preparing simulations. Three attributes are used:
4.14. <exec>Optional. Multiple. Specifies one command to be executed by the virtual machine during executing commands sequence mode (-x switch). The attribute seq 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. This tag also 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). 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:
The optional attribute user can be used in <exec> tags within <vm> 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. |
|
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. 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 attribute is forbbiden in <exec>). Additionally, 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 differences 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 bridge 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 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". |
|
Apendix: Changes | |
This appendix summarizes main changes introcuded in DTD since 1.6, in the hope it could be useful for old users to adapt their VNUML specifications to the newest DTD releases. Changes introduced VNUML DTD 1.7
Changes introduced VNUML DTD 1.6
|
|
|