Tutorial

VNUML Tutorial

Authors: Ferm&iacute;n Gal&aacute;n (galan at dit.upm.es) David Fern&aacute;ndez (david at dit.upm.es) version 1.7, July 27th, 2006

Introduction
VNUML (Virtual Network User Mode Linux) is a general purpose virtualization tool designed to easily create complex network simulation scenarios based on User Mode Linux (UML) virtualization software. It has been initially developed in the context of Euro6IX research project to simulate IPv6 IX scenarios based on Linux and zebra routing daemon. However, it is a useful tool that can be used to simulate general Linux based network scenarios.

VNUML is aimed to help in testing network applications and services over complex testbeds made of several nodes (even tens) and networks inside one Linux machine, without involving the investment and management complexity needed to create it using real equipment.

This tutorial explains in detail how to use VNUML tool to simulate a simple networking scenario. It is intended as a hands-on approach for people that wants to start using VNUML tool, as well as an overview of the philosophy and features behind VNUML tool for people that do not want to install it yet.

Although VNUML hides from the user most of the details needed to use UML       virtualization software, a minimum knowledge about UML and how it works is needed. The reader is referred to UML Web site to gain that knowledge.

Throughout this document and the rest of the documentation, we refer to the machine where VNUML is running as the &quot;host&quot;. The Linux virtual machines that run over the host using UML virtualization software are typically referred as &quot;virtual machines&quot; or simply &quot;UMLs&quot;.

This tutorial covers VNUML language version 1.7 and vnumlparser.pl 1.7.X.

Tutorial Requirements
In order to properly follow this tutorial you need:



VNUML properly installed in your system. Use the most recent stable release. Please, refer to the VNUML Installation Guide for more details. UML kernel (we recomend the most recent stable one provided by the VNUML Project). Root_fs filesystem (we recomend the most recent stable one provided by the VNUML Project). X-window environment. Some steps in the tutorial will launch xterm terminals, so you need a X server. Be able to log as root in the host (for step 3 and step 4</a>).</li> The 10.0.x.x and 10.250.x.x address ranges are used in the VNUML specifications shown in this tutorial. If these ranges collide with assigned addresses in you host environment you must to change them to other prefixes.</li>

</ul>

Priviledges
Old versions of VNUML parser (previous to 1.6.0) were very root-focused. Fortunately, VNUML support for conventional users was highly improved in version 1.6.0.

There are three ways of using VNUML, depending of what privileges you want    to use: <ul>  Limited User Privileges. To run vnumlparser.pl without root privileges. The main limitation is that there is no network access to the virtual machines from/to host and, therefore, no access to the external network the host is connected to (if any). The only way to interact with the virtual machines is through direct login (typically, a xterm). As a consequence, vnumlparser.pl can not be used to automatically run command sequences on the virtual machines.</li>  User Privileges. To run vnumlparser.pl without root privileges, but use root privileges to enable host network access (management network) and access to external networks using the root as router/NAT (layer 3 interconnection). Command sequences can be run by vnumlparser.pl in the virtual machines using the management network.</li>  Full Root Privileges. To run vnumlparser.pl as root. This allow host configuration performed by vnumlparser.pl, private management, mapping of virtual machine names in /etc/hosts and direct connection of virtual machines to external networks the host is connected to (layer 2 interconnection).</li> </ul> The rest of the tutorial describe these three ways in detail, starting with  <a href="#limited_user_privileges">Limited User Privileges</a>, going to <a href="#user_privileges">User Privileges</a> and finally, <a href="#full_root_privileges">Full Root Privileges</a>.

Writing the VNUML Specification
VNUML tool is made of two main components: the VNUML language used for describing simulations in XML; and the interpreter of the language (vnumlparser.pl), that builds and manages the simulation, hiding all UML complex details to the user.

If you managed to successfully install VNUML parser and all related software packages, one of the hardest steps is over :). Now it is time to create the XML description of the scenario to be simulated using VNUML language (see <a href="../reference/index.html">VNUML Language Reference</a> for a complete  description of the language).

The specification of the tutorial scenario in VNUML language follows:



&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt; &lt;!DOCTYPE vnuml SYSTEM &quot;/usr/share/xml/vnuml/vnuml.dtd&quot;&gt;

&lt;vnuml&gt; &lt;global&gt; &lt;version&gt;1.7&lt;/version&gt; &lt;simulation_name&gt;tutorial-lu&lt;/simulation_name&gt; &lt;automac/&gt; &lt;vm_mgmt type=&quot;none&quot; /&gt; &lt;vm_defaults&gt; &lt;filesystem type=&quot;cow&quot;&gt;/usr/share/vnuml/filesystems/root_fs_tutorial&lt;/filesystem&gt; &lt;kernel&gt;/usr/share/vnuml/kernels/linux&lt;/kernel&gt; &lt;console id=&quot;0&quot;&gt;xterm&lt;/console&gt; &lt;/vm_defaults&gt; &lt;/global&gt; &lt;net name=&quot;Net0&quot; mode=&quot;uml_switch&quot; /&gt; &lt;net name=&quot;Net1&quot; mode=&quot;uml_switch&quot; /&gt; &lt;net name=&quot;Net2&quot; mode=&quot;uml_switch&quot; /&gt; &lt;vm name=&quot;uml1&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.0.3&quot;&gt;default&lt;/route&gt; &lt;/vm&gt; &lt;vm name=&quot;uml2&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.2&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.0.3&quot;&gt;default&lt;/route&gt; &lt;/vm&gt; &lt;vm name=&quot;uml3&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.3&lt;/ipv4&gt; &lt;/if&gt; &lt;if id=&quot;2&quot; net=&quot;Net1&quot;&gt; &lt;ipv4&gt;10.0.1.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.1.2&quot;&gt;10.0.2.0/24&lt;/route&gt; &lt;forwarding type=&quot;ip&quot; /&gt; &lt;/vm&gt; &lt;vm name=&quot;uml4&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net1&quot;&gt; &lt;ipv4&gt;10.0.1.2&lt;/ipv4&gt; &lt;/if&gt; &lt;if id=&quot;2&quot; net=&quot;Net2&quot;&gt; &lt;ipv4&gt;10.0.2.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.1.1&quot;&gt;default&lt;/route&gt; &lt;forwarding type=&quot;ip&quot; /&gt; &lt;/vm&gt; &lt;vm name=&quot;uml5&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net2&quot;&gt; &lt;ipv4&gt;10.0.2.2&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.2.1&quot;&gt;default&lt;/route&gt; &lt;/vm&gt; &lt;/vnuml&gt;

Just copy the above XML code to a file named tutorial_limited_user.xml and save it (if you don&#39;t want to do the copy-paste, you can        find it in the examples directory after VNUML installation in        /usr/share/examples).

Some initial comments about this description file:

<ul> The <a href="../reference/index.html#global">&lt;global&gt;</a> section defines certain parameters and options that apply to the whole simulation. Within it, the <a href="../reference/index.html#vm_defaults">&lt;vm_defaults&gt;</a> tag defines some defaults for all virtual machines, like the kernel and filesystem. Note the <a href="../reference/index.html#console">&lt;console&gt;</a> tag, that defines that we want a xterm to interact with each virtual machine. </li>

Virtual networks are created using the <a href= "../reference/index.html#net">&lt;net&gt;</a> tag. Each network is identified by a name (e.g., "Net0") which is used later in virtual machines descriptions to define the network each virtual interface is connected to. </li>

Virtual machines (or UMLs) are created and described using the <a href= "../reference/index.html#vm">&lt;vm&gt;</a> tag. Inside &lt;vm&gt; section, several different tags can be included to define each UML characteristics. There are lot of tags that can be used in a virtual machine but, well, this is a tutorial :), so only the	     basic ones are shown here:

<ul> <a href="../reference/index.html#if">&lt;if&gt;</a> tag is             used to create and describe network interfaces (<a href=              "../reference/index.html#ipv4">&lt;ipv4&gt;</a> tag is used to set up the IP	      address; <a href=              "../reference/index.html#ipv6">&lt;ipv6&gt;</a> is supported also), </li> <a href= "../reference/index.html#route">&lt;route&gt;</a> tag is used to	     add static routes, and </li> <a href= "../reference/index.html#forwarding">&lt;forwarding&gt;</a> to enable forwarding. Note we use this tag in uml3 and uml4, the virtual machines that will act as routers (the others are end-systems).</li>

</ul>

</ul>

Building the Simulation
Once you have the VNUML specification written, you can build the scenario using "-t" switch of VNUML parser. That is:

bauer@host$ vnumlparser.pl -t tutorial_limited_user.xml -v

This command builds the virtual network topology described in tutorial_limited_user.xml file and boots all the virtual machines defined inside it. After the command execution, you will see a lot of output messages, showing what the parser is       exactly doing. That is because "-v" (verbose) switch is being used (we       recommend always using "-v" to see how things are going).

By default, the output of each UML is redirected to the null device; if you want to see that output (getting a even more verbose output) use &quot;-o&quot; switch (for       example &quot;-o /tmp/boot&quot;).

After a few seconds, you should see five xterms popping up in       sequence: each one correspond to one of the virtual machines defined in the simulation. After the booting process you would identify each one by the name in the login prompt (uml1, uml2, uml3, uml4 and uml5). VNUML allows several modes to       interact with the virtual machines, xterm is the only way allowed if        you don't have root privileges.

Be patient, because the boot process of each UML takes a while (think about how long it takes a conventional Linux kernel to boot;        virtualized ones can take even more). It can take easily several minutes to boot each UML, so it could take from 1 minute (or less!) to around 10-15 minutes to boot the tutorial scenario (time        depends greatly on the host machine characteristics). Maybe even you get the following prompt: Boot timeout for virtual machine uml1 reached. Abort, Retry, or Continue? [A/r/c]:

This use to mean that vnumlparser.pl has got tired of waitting for a       virtual machine. It could be that the virtual machine has not finishing booting yet (that means, the login prompt has not appeared yet). Try 'r' in that case. If the problem persists, contact the vnuml-user mailing list.

Testing the Simulation
You can log in the virtual machines as root user using xxxx (for times       the 'x' letter) as password. After logging, you can execute commands as in a conventional GNU/Linux machine. For example try: 'ls /', 'ifconfig', 'df -h' or 'uname -ra'. To check connectivity between virtual machines you can use ping or traceroute, as       shown in the examples below. For example, from uml1 try (you should see a similar trace, if everything is going right): uml1:~ # traceroute -n 10.0.2.2 traceroute to 10.0.2.2 (10.0.2.2), 30 hops max, 38 byte packets 1 10.0.0.3  1.282 ms  0.726 ms  0.678 ms 2  10.0.1.2  1.243 ms  1.462 ms  1.010 ms 3  10.0.2.2  1.396 ms  1.345 ms  1.303 ms            From uml5 try:

uml5:~ # traceroute -n 10.0.0.1 traceroute to 10.0.0.1 (10.0.0.1), 30 hops max, 38 byte packets 1 10.0.2.1  0.916 ms  0.743 ms  0.681 ms 2  10.0.1.1  1.072 ms  1.019 ms  1.009 ms 3  10.0.0.1  1.420 ms  1.363 ms  1.352 ms

You will see (using ifconfig) that the interfaces in the virtual machines starts with eth1, not with eth0 as usual. Actually the eth0 interface is reserved to the management network, <a href="#management_network">that will be described later</a>.

Releasing the Simulation Scenario
Once you have finished playing around with the simulation scenario, you can release it in a "polite way" by means of "-d" switch of VNUML parser.

bauer@host$ vnumlparser.pl -d tutorial_limited_user.xml -v

This sends a CAD (Ctrl+Alt+Delete) to each virtual machine, then you will see how the halting process begins. After waiting for a while (think that a conventional kernel can take a couple of minutes to halt, so a set of virtualized ones take quite a bit longer), the simulation scenario should be released (all virtual machines should have been halted, xterms closed and  virtual networks released).

After releasing the scenario in this way, you can recreate it with &quot;-t&quot;. Note that releasing a scenario does not mean that filesystems changes are lost. On the contrary, any change performed on them remains after the scenario has been released and restarted again. You can check it: 'touch /root/foo.bar' and you will see how the file /root/foo.bar remains next time you start using &quot;-t&quot; (the magic behind this resides in certain files under ~/.vnuml that stores user additions to the virtual machine filesystems: this files can be erases using the &quot;-P&quot;, keep reading :).

You can also use the -F switch in the releasing mode, as follows: bauer@host$ vnumlparser.pl -d tutorial_limited_user.xml -v -F Instead of sending the CAD signal to the virtual machines, this sends a HALT signal, that is stronger: the virtual kernel halts immediately. This could corrupt the virtual filesystems so you only should use it when plain -d has failed.

There is even a stronger way to release the simulation: the purge mode (-P), but it should only be used as a last-resort measure. See <a href="../user/index.html#how_to_destroy">VNUML User Manual</a> for more details when -d mode fails (including the purge mode -P). When you get familiar starting and releasing simulation, continue to main section in the tutorial: User Privileges.

User Privileges
In this mode, you are supposed to run vnumparser.pl as conventional user as in limited user mode, but you also have root access in order to run some commands as superuser (maybe using sudo). You will be able to connect the simulation to the host (this way virtual machines could reach Internet, if  the host acts as router/NAT) and execute automatically command sequences in the virtual machines, as will be described following.

Connecting Simulations to Host
The following is a variation of the tutorial_user_limited.xml file. Copy it to a file named tutorial_user1.xml and save it (if you don&#39;t want to  do the copy-paste, you can find it in the examples directory after VNUML  installation in /usr/share/examples).

&lt;?xml version="1.0" encoding="UTF-8"?&gt; &lt;!DOCTYPE vnuml SYSTEM "/usr/share/xml/vnuml/vnuml.dtd"&gt;

&lt;vnuml&gt; &lt;global&gt; &lt;version&gt;1.7&lt;/version&gt; &lt;simulation_name&gt;tutorial-u1&lt;/simulation_name&gt; &lt;automac/&gt; &lt;vm_mgmt type=&quot;none&quot; /&gt; &lt;vm_defaults&gt; &lt;filesystem type=&quot;cow&quot;&gt;/usr/share/vnuml/filesystems/root_fs_tutorial&lt;/filesystem&gt; &lt;kernel&gt;/usr/share/vnuml/kernels/linux&lt;/kernel&gt; &lt;console id=&quot;0&quot;&gt;xterm&lt;/console&gt; &lt;/vm_defaults&gt; &lt;/global&gt; &lt;net name=&quot;Net0&quot; mode=&quot;uml_switch&quot; /&gt; &lt;net name=&quot;Net1&quot; mode=&quot;uml_switch&quot; /&gt; &lt;net name=&quot;Net2&quot; mode=&quot;uml_switch&quot; /&gt; &lt;net name=&quot;Net3&quot; mode=&quot;uml_switch&quot; sock=&quot;/var/run/vnuml/Net3.ctl&quot; /&gt; &lt;vm name=&quot;uml1&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.0.3&quot;&gt;default&lt;/route&gt; &lt;/vm&gt; &lt;vm name=&quot;uml2&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.2&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.0.3&quot;&gt;default&lt;/route&gt; &lt;/vm&gt; &lt;vm name=&quot;uml3&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.3&lt;/ipv4&gt; &lt;/if&gt; &lt;if id=&quot;2&quot; net=&quot;Net1&quot;&gt; &lt;ipv4&gt;10.0.1.1&lt;/ipv4&gt; &lt;/if&gt; &lt;if id=&quot;3&quot; net=&quot;Net3&quot;&gt; &lt;ipv4&gt;10.0.3.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.1.2&quot;&gt;10.0.2.0/24&lt;/route&gt; &lt;forwarding type=&quot;ip&quot; /&gt; &lt;/vm&gt; &lt;vm name=&quot;uml4&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net1&quot;&gt; &lt;ipv4&gt;10.0.1.2&lt;/ipv4&gt; &lt;/if&gt; &lt;if id=&quot;2&quot; net=&quot;Net2&quot;&gt; &lt;ipv4&gt;10.0.2.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.1.1&quot;&gt;default&lt;/route&gt; &lt;forwarding type=&quot;ip&quot; /&gt; &lt;/vm&gt; &lt;vm name=&quot;uml5&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net2&quot;&gt; &lt;ipv4&gt;10.0.2.2&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.2.1&quot;&gt;default&lt;/route&gt; &lt;/vm&gt; &lt;/vnuml&gt;

The difference is the Net3 network in a <a href="../reference/index.html#net">&lt;net&gt;</a> tag, linked to the virtual machine uml3 in a <a href="../reference/index.html#if">&lt;if&gt;</a> tag. This is the network that will be used to get connectivity to the host. In order to have access to the host machine when running vnumlparser.pl as a non-privileged user, certain configurations must be performed by a privileged user prior to building the simulation scenario. In this example, the non-privileged user that will run vnumlparser.pl is bauer. As part of the VNUML install process, a non-privileged user vnuml was created (check it now with 'id vnuml'). This user is a member of the uml-net group, which owns the /dev/net/tun cloning device. It will own the uml_switch process that will be started for the Net3 network, so that this process won't need to be run by root. <ol> The user bauer must be a member of the vnuml group which owns the directory /var/run/vnuml, where the UNIX sockets for the uml_switch processes will be stored. (The command below looks intimidating, but really all it does is add the user bauer to the vnuml group, while preserving its current group membership; maybe you prefer simple edit the /etc/group file). Note: as group membership is not updated in running shells, after adding user bauer to vnuml group, user bauer has to start a new shell or xterm session before executing the simulation.</li> root@host# usermod -G vnuml,`groups bauer | sed 's/^.\+:space:*//;s/space:\\+/,/g'` bauer Create a TUN/TAP device owned by the vnuml user. This TUN/TAP device acts as the termination point for the host connection in the Net3 virtual network.</li> root@host# tunctl -u vnuml -t tap0 Set 'tap0' persistent and owned by uid 1037 Set an address for the host in the Net3 network (for example, 10.0.3.2) and configure a static route in the host to reach all the virtual machines using uml3 as gateway.</li> root@host# ifconfig tap0 10.0.3.2 netmask 255.255.255.0 up root@host# route -A inet add -net 10.0.0.0/16 gw 10.0.3.1 Start a uml_switch process, linked with the TUN/TAP device created previously (tap0) and owned by the vnuml user. The socket location is arbitrary. However, the /var/run/vnuml directory was created at installation for this purpose. The socket location will be used as the sock attribute in the <a href="../reference/index.html#net">&lt;net&gt;</a> tag for Net3.</li>

root@host# su -pc 'uml_switch -tap tap0 -unix /var/run/vnuml/Net3.ctl &lt; /dev/null &gt; /dev/null &amp;' vnuml

Give the vnuml group read/write privileges to the socket that is used. Note that the UNIX socket for the uml_switch process isn't created instantly, so if these commands are scripted, a minor wait (sleep) is necessary before setting permissions on the file. (Of course, the 'ls' commands are not really needed, but they are useful to check the chmod commands has been sucessfull).</li>

root@host# sleep 1 root@host# ls -l /var/run/vnuml/Net3.ctl srwxr-xr-x 1 vnuml vnuml 0 2005-07-29 11:48 /var/run/vnuml/Net3.ctl root@host# chmod g+rw /var/run/vnuml/Net3.ctl root@host# ls -l /var/run/vnuml/Net3.ctl srwxrwxr-x 1 vnuml vnuml 0 2005-07-29 11:48 /var/run/vnuml/Net3.ctl

Now that the /var/run/vnuml/Net3.ctl exists and is readable and writeable by bauer, you can start the simulation.

bauer@host$ vnumlparser.pl -t tutorial_user1.xml -v

You should see the xterms starting as usual. After they have finished booting, you could check that now the host is part of the simulation. From uml1 you can try: uml1:~ # traceroute -n 10.0.3.2 traceroute to 10.0.3.2 (10.0.3.2), 30 hops max, 38 byte packets 1 10.0.0.3  1.779 ms  2.572 ms  1.359 ms 2  10.0.3.2  1.785 ms  1.641 ms  1.744 ms

From uml5 you can try:

uml5:~ # traceroute -n 10.0.3.2 traceroute to 10.0.3.2 (10.0.3.2), 30 hops max, 38 byte packets 1 10.0.2.1  1.407 ms  0.857 ms  1.243 ms 2  10.0.1.1  1.265 ms  1.019 ms  0.980 ms 3  10.0.3.2  1.545 ms  3.156 ms  2.033 ms

From host try:

bauer@host$ traceroute -n 10.0.0.1 traceroute to 10.0.0.1 (10.0.0.1), 30 hops max, 40 byte packets 1 10.0.3.1  0.000 ms   0.000 ms   0.000 ms 2  10.0.0.1  0.000 ms   0.000 ms   0.000 ms bauer@host$ traceroute -n 10.0.2.2 traceroute to 10.0.2.2 (10.0.2.2), 30 hops max, 40 byte packets 1 10.0.3.1  0.000 ms   0.000 ms   0.000 ms 2  10.0.1.2  0.000 ms   0.000 ms   0.000 ms 3  10.0.2.2  0.000 ms   0.000 ms   0.000 ms

Virtual machines can reach the host this way. The scenario could be improved by configuring routing and NATing properly in the host, in order for virtual machines to reach any host on the Internet. Such a setup would be a layer 3 interconnection: the host acts as router/NAT between virtual machines and the external network. Details to configure NAT this way can be found <a href="#nat">later in this document</a>. A stronger interconnection (layer 2) can be implemented, so virtual machines are connected to the external network directly, but root privileges are needed. We describe <a href="#layer_2_interconnection">layer 2 interconnection later</a>.

To release the simulation: bauer@host$ vnumlparser.pl -d tutorial_user1.xml -v

When the simulation has been released, note that the uml_switch process for Net3 is still running, and its accompanying UNIX socket still exists in /var/run/vnuml/Net3.ctl. Also, the tap0 device is still configured, and its gateway still exists. As long as this setup remains, new simulation scenarios may be built using the same configuration without requiring it to be set up again.

When the user has finished running simulations that involve the network set up for Net3, the uml_switch process can be killed, and the socket removed:

root@host# kill `lsof -t /var/run/vnuml/Net3.ctl` /var/run/vnuml/Net3.ctl: 6280 root@host# rm /var/run/vnuml/Net3.ctl

Now the tap0 device may be deconfigured: root@host# ifconfig tap0 down root@host# tunctl -d tap0 Set 'tap0' nonpersistent

Generating SSH key
VNUML parser uses SSH to access and manage the UMLs. To avoid being asked for a password whenever this happens (quite often) you must generate a public key that will be installed automatically in the UMLs by the VNUML parser (<a href= "../reference/index.html#ssh_key">&lt;ssh_key&gt;</a> tag).

To create the public key just type:

bauer@host$ ssh-keygen -t rsa1

Select the default file to save the key (~/.ssh/identity). The passphrase is not relevant (although we recommend to use an empty passphrase,  in order no user input required whenever the key is used).

Anyway, the first time (and only once) that SSH is used, you will have to confirm the server key answering &#39;yes&#39; to the question you will be asked.

Management Network
The following is a variation of the tutorial_user_limited.xml file. Copy it to a file named tutorial_user2.xml and save it (if you don't want to  do the copy-paste, you can find it in the examples directory after VNUML  installation in /usr/share/examples).

&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt; &lt;!DOCTYPE vnuml SYSTEM &quot;/usr/share/xml/vnuml/vnuml.dtd&quot;&gt;

&lt;vnuml&gt; &lt;global&gt; &lt;version&gt;1.7&lt;/version&gt; &lt;simulation_name&gt;tutorial-u2&lt;/simulation_name&gt; &lt;ssh_version&gt;1&lt;/ssh_version&gt; &lt;ssh_key&gt;~/.ssh/identity.pub&lt;/ssh_key&gt; &lt;automac/&gt; &lt;vm_mgmt type=&quot;net&quot; network=&quot;10.250.0.0&quot; mask=&quot;24&quot;&gt; &lt;mgmt_net sock=&quot;/var/run/vnuml/Mgmt_net.ctl&quot; hostip=&quot;10.250.0.1&quot;/&gt; &lt;/vm_mgmt&gt; &lt;vm_defaults&gt; &lt;filesystem type=&quot;cow&quot;&gt;/usr/share/vnuml/filesystems/root_fs_tutorial&lt;/filesystem&gt; &lt;kernel&gt;/usr/share/vnuml/kernels/linux&lt;/kernel&gt; &lt;console id=&quot;0&quot;&gt;xterm&lt;/console&gt; &lt;/vm_defaults&gt; &lt;/global&gt; &lt;net name=&quot;Net0&quot; mode=&quot;uml_switch&quot; /&gt; &lt;net name=&quot;Net1&quot; mode=&quot;uml_switch&quot; /&gt; &lt;net name=&quot;Net2&quot; mode=&quot;uml_switch&quot; /&gt; &lt;vm name=&quot;uml1&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.0.3&quot;&gt;default&lt;/route&gt; &lt;exec seq=&quot;start&quot; type=&quot;verbatim&quot;&gt;nohup /usr/bin/hello &amp;lt;/dev/null &amp;gt;/dev/null 2&amp;gt;&amp;amp;1 &amp;amp; &lt;/exec&gt; &lt;exec seq=&quot;stop&quot; type=&quot;verbatim&quot;&gt;killall hello&lt;/exec&gt; &lt;/vm&gt; &lt;vm name=&quot;uml2&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.2&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.0.3&quot;&gt;default&lt;/route&gt; &lt;/vm&gt; &lt;vm name=&quot;uml3&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.3&lt;/ipv4&gt; &lt;/if&gt; &lt;if id=&quot;2&quot; net=&quot;Net1&quot;&gt; &lt;ipv4&gt;10.0.1.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.1.2&quot;&gt;10.0.2.0/24&lt;/route&gt; &lt;forwarding type=&quot;ip&quot; /&gt; &lt;/vm&gt; &lt;vm name=&quot;uml4&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net1&quot;&gt; &lt;ipv4&gt;10.0.1.2&lt;/ipv4&gt; &lt;/if&gt; &lt;if id=&quot;2&quot; net=&quot;Net2&quot;&gt; &lt;ipv4&gt;10.0.2.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.1.1&quot;&gt;default&lt;/route&gt; &lt;forwarding type=&quot;ip&quot; /&gt; &lt;/vm&gt; &lt;vm name=&quot;uml5&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net2&quot;&gt; &lt;ipv4&gt;10.0.2.2&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.2.1&quot;&gt;default&lt;/route&gt; &lt;/vm&gt; &lt;/vnuml&gt;

VNUML uses SSH to send command sequences to the virtual machines. The SSH protocol version and the SSH public key to be used are specified in the <a href="../reference/index.html#ssh_version">&lt;ssh_version&gt;</a> and <a href="../reference/index.html#ssh_key">&lt;ssh_key&gt;</a> tags, respectively. Note that the SSH key file is the one generated in the <a href="#generate_ssh_key">previous step</a>. In order to send commands to the virtual machines, a special kind of network is set up for management. There are two kind of management networks: private--establishes a peer-to-peer connection between the host and each one of the virtual machines (this requires that vnumlparser.pl be run as root); and net--a uml_switched network is used. This is set up with the type attribute in the <a href="../reference/index.html#vm_mgmt">&lt;vm_mgmt&gt;</a> tag. When using type =&quot;net&quot; the network and mask attributes specify a network address range that vnumlparser.pl will use to assign addresses to the virtual machines. The hostip attribute in the <a href="../reference/index.html#mgmt_net">&lt;mgmt_net&gt;</a> tag will be skipped in that range, reserved for use by the host. Let's see how the whole thing is working. As root, set up a tap device and start the uml_switch process (similar to what was done in the <a href="#connecting_sim_host">previous example</a>): root@host# tunctl -u vnuml -t tap0 Set 'tap0' persistent and owned by uid 1037 root@host# ifconfig tap0 10.250.0.1 netmask 255.255.255.0 up root@host# su -pc 'uml_switch -tap tap0 -unix /var/run/vnuml/Mgmt_net.ctl &lt; /dev/null &gt; /dev/null &amp;' vnuml root@host# sleep 1 root@host# chmod g+rw /var/run/vnuml/Mgmt_net.ctl

Next, build the simulation: bauer@host$ vnumlparser.pl -t tutorial_user2.xml -v

After logging in to the xterms, you can check using ifconfig that an additional interface is configured in each machine: the eth0 interface. All virtual machines are connected to the host (and between them, as side effect), with the following addresses:

You can login in each virtual machine from host using SSH. For example, to log in uml3:

bauer@host$ ssh -1 root@10.250.0.4 Last login: Fri Jun 16 10:33:46 2006 Linux (none) 2.6.15.7-bs3-tls-xt-2m #1 Wed Jul 19 15:23:08 CEST 2006 i686

The programs included with the Debian GNU/Linux system are free software; the exact distribution terms for each program are described in the individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent permitted by applicable law. uml3:~# Note that, given that you can SSH to each virtual machine from host, you don't need xterms (just remove the <a href="../reference/index.html#console">&lt;console&gt;</a> tag in the VNUML file) if you configure the management network properly. This is very useful when you have a lot of virtual machines in your simulation (ten or more) and don't want to be overwhelmed by the xterms.

Command Sequences
Once the simulated scenario is up and running, you can get access to each virtual machine using ssh and execute the commands you desire. You could, for example, manually start a web or ftp server inside uml1 and uml5 virtual machines. You could also start routing daemons in uml3 and uml4 in order to set-up dynamic routing for the scenario. You could even start automatically such services from the init scripts in the root filesystem being used, although that would probably require the use of a different filesystem for each UML.

However, in order to be able to easily create and reproduce simulation scenarios, a simple and powerful way to specify the commands that each virtual machine has to execute to start the scenario is needed, as well as the commands to stop the simulation and return the virtual machine to a known state.

That is basically what VNUML offers: a way to automate the execution of commands in the virtual machines and host using the execute commands mode (-x switch). By means of the <a href="../reference/index.html#exec">&lt;exec&gt;</a> tag included inside each virtual machine definition, you can specify the commands that will be executed. Commands are grouped using a command sequence identifier, specified in the seq attribute of the <a href="../reference/index.html#exec">&lt;exec&gt;</a> tag. In this tutorial we will to consider two command sequences: &quot;start&quot; and &quot;stop&quot;.

To show this functionality in this tutorial we will use the /usr/bin/hello program included in the tutorial root filesystem. It is just a quite simple program whose only function is to output &#39;hello&#39; word to file /tmp/hello every 10 seconds (it is only for testing purposes, we suppose you&#39;ll use VNUML for more useful tasks :).

In order to test it, look at the lines at the end of uml1 description in tutorial_user2.xml:

&lt;exec seq=&quot;start&quot; type=&quot;verbatim&quot;&gt; nohup /usr/bin/hello &amp;lt;/dev/null &amp;gt;/dev/null 2&amp;gt;&amp;amp;1 &amp;amp; &lt;/exec&gt; &lt;exec seq=&quot;stop&quot; type=&quot;verbatim&quot;&gt;killall hello&lt;/exec&gt;

Basically, we have specified the following command to be executed in uml1 whenever the simulation is started (note that &lt;, &gt; and &amp; characters had to  be escaped in XML files):

nohup /usr/bin/hello &lt;/dev/null &gt;/dev/null 2&gt;&amp;1 &amp; (Why not simply use &#39;nohup /usr/bin/hello &amp;&#39;? There are ssh related problems that force to redirect standard input and output; look at <a href= "../user/index.html#ssh_hang">VNUML User Manual</a> for more details).

And the following one to be executed in uml1 whenever the simulation is stopped:

killall hello

Start the simulation using:

bauer@host$ vnumlparser.pl -x start@tutorial_user2.xml -v

Note that the process is much shorter than when building the simulation scenario (mode -t). Check the existence and growing of /tmp/hello file in uml1: the hello daemon is working.

uml1:~ # tail -f /tmp/hello Hello! Current date: Thu Jul 20 10:14:43 UTC 2006 Hello! Current date: Thu Jul 20 10:14:53 UTC 2006 Hello! Current date: Thu Jul 20 10:15:04 UTC 2006 Hello! Current date: Thu Jul 20 10:15:14 UTC 2006 Hello! Current date: Thu Jul 20 10:15:25 UTC 2006 Hello! Current date: Thu Jul 20 10:15:35 UTC 2006 Hello! Current date: Thu Jul 20 10:15:45 UTC 2006

In a similar way you can stop the simulation (killing the hello daemon) with:

bauer@host$ vnumlparser.pl -x stop@tutorial_user2.xml -v

Access again to uml1 and check that hello daemon is not working now (&#39;ps axw | grep hello&#39; for example) and that /tmp/hello file has stopped growing. Once you have finished playing around with the simulation scenario, release it as usual:.

bauer@host$ vnumlparser.pl -d tutorial_user2.xml -v As with the <a href="#connecting_sim_host">previous example</a>, in order to reset to the original state, the uml_switch process will need to be killed and its accompanying UNIX socket removed. Also the tap device will need will need to be deconfigured and removed.

root@host# kill `lsof -t /var/run/vnuml/Mgmt_net.ctl` /var/run/vnuml/Mgmt_net.ctl: 13746 root@host# rm /var/run/vnuml/Mgmt_net.ctl root@host# ifconfig tap0 down root@host# tunctl -d tap0 Set 'tap0' nonpersistent

Host Configuration
The <a href="../reference/index.html#host">&lt;host&gt;</a> tag, that can be only be used if root runs vnumlparser.pl allows to automate host configuration. For example, the following example ( tutorial_root1.xml ) is functionally equivalent to tutorial_user1.xml (<a href="#connecting_sim_host">described here</a>), but vnumlparser.pl deals with the tap0 creation and uml_switch starting. Note also that sock attribute in <a href="../reference/index.html#host">&lt;host&gt;</a> Net3 is not used. &lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt; &lt;!DOCTYPE vnuml SYSTEM &quot;/usr/share/xml/vnuml/vnuml.dtd&quot;&gt;

&lt;vnuml&gt; &lt;global&gt; &lt;version&gt;1.7&lt;/version&gt; &lt;simulation_name&gt;tutorial-r1&lt;/simulation_name&gt; &lt;automac/&gt; &lt;vm_mgmt type=&quot;none&quot; /&gt; &lt;vm_defaults&gt; &lt;filesystem type=&quot;cow&quot;&gt;/usr/share/vnuml/filesystems/root_fs_tutorial&lt;/filesystem&gt; &lt;kernel&gt;/usr/share/vnuml/kernels/linux&lt;/kernel&gt; &lt;console id=&quot;0&quot;&gt;xterm&lt;/console&gt; &lt;/vm_defaults&gt; &lt;/global&gt; &lt;net name=&quot;Net0&quot; mode=&quot;uml_switch&quot; /&gt; &lt;net name=&quot;Net1&quot; mode=&quot;uml_switch&quot; /&gt; &lt;net name=&quot;Net2&quot; mode=&quot;uml_switch&quot; /&gt; &lt;net name=&quot;Net3&quot; mode=&quot;uml_switch&quot; /&gt; &lt;vm name=&quot;uml1&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.0.3&quot;&gt;default&lt;/route&gt; &lt;/vm&gt; &lt;vm name=&quot;uml2&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.2&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.0.3&quot;&gt;default&lt;/route&gt; &lt;/vm&gt; &lt;vm name=&quot;uml3&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.3&lt;/ipv4&gt; &lt;/if&gt; &lt;if id=&quot;2&quot; net=&quot;Net1&quot;&gt; &lt;ipv4&gt;10.0.1.1&lt;/ipv4&gt; &lt;/if&gt; &lt;if id=&quot;3&quot; net=&quot;Net3&quot;&gt; &lt;ipv4&gt;10.0.3.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.1.2&quot;&gt;10.0.2.0/24&lt;/route&gt; &lt;forwarding type=&quot;ip&quot; /&gt; &lt;/vm&gt; &lt;vm name=&quot;uml4&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net1&quot;&gt; &lt;ipv4&gt;10.0.1.2&lt;/ipv4&gt; &lt;/if&gt; &lt;if id=&quot;2&quot; net=&quot;Net2&quot;&gt; &lt;ipv4&gt;10.0.2.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.1.1&quot;&gt;default&lt;/route&gt; &lt;forwarding type=&quot;ip&quot; /&gt; &lt;/vm&gt; &lt;vm name=&quot;uml5&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net2&quot;&gt; &lt;ipv4&gt;10.0.2.2&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.2.1&quot;&gt;default&lt;/route&gt; &lt;/vm&gt; &lt;host&gt; &lt;hostif net=&quot;Net3&quot;&gt; &lt;ipv4&gt;10.0.3.2&lt;/ipv4&gt; &lt;/hostif&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.3.1&quot;&gt;10.0.0.0/16&lt;/route&gt; &lt;/host&gt; &lt;/vnuml&gt;

To build, test and release the example use the usual commands:

root@host# vnumlparser.pl -t tutorial_root1.xml -v (...) root@host# traceroute -n 10.0.0.1 traceroute to 10.0.0.1 (10.0.0.1), 30 hops max, 40 byte packets 1 10.0.3.1  0.000 ms   0.000 ms   0.000 ms 2  10.0.0.1  0.000 ms   0.000 ms   0.000 ms root@host# traceroute -n 10.0.2.2 traceroute to 10.0.2.2 (10.0.2.2), 30 hops max, 40 byte packets 1 10.0.3.1  0.000 ms   0.000 ms   0.000 ms 2  10.0.1.2  0.000 ms   0.000 ms   0.000 ms 3  10.0.2.2  0.000 ms   0.000 ms   0.000 ms root@host# vnumlparser.pl -d tutorial_root1.xml -v (...)

Private Management
You can use type =&quot;private&quot; in <a href="../reference/index.html#vm_mgmt">&lt;vm_mgmt&gt;</a> to establish peer-to-peer connection between the host and each one of the virtual machines (/30 networks). The <a href="../reference/index.html#mgmt_net">&lt;mgmt_net&gt;</a> tag is not used in this case. The following example ( tutorial_root2.xml ) is functionally equivalent to tutorial_user2.xml (<a href="#executing_commands">described here</a>), but using private management.



&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt; &lt;!DOCTYPE vnuml SYSTEM &quot;/usr/share/xml/vnuml/vnuml.dtd&quot;&gt;

&lt;vnuml&gt; &lt;global&gt; &lt;version&gt;1.7&lt;/version&gt; &lt;simulation_name&gt;tutorial-r2&lt;/simulation_name&gt; &lt;ssh_version&gt;1&lt;/ssh_version&gt; &lt;ssh_key&gt;~/.ssh/identity.pub&lt;/ssh_key&gt; &lt;automac/&gt; &lt;vm_mgmt type=&quot;private&quot; network=&quot;10.250.0.0&quot; mask=&quot;24&quot;&gt; &lt;host_mapping /&gt; &lt;/vm_mgmt&gt; &lt;vm_defaults&gt; &lt;filesystem type=&quot;cow&quot;&gt;/usr/share/vnuml/filesystems/root_fs_tutorial&lt;/filesystem&gt; &lt;kernel&gt;/usr/share/vnuml/kernels/linux&lt;/kernel&gt; &lt;console id=&quot;0&quot;&gt;xterm&lt;/console&gt; &lt;/vm_defaults&gt; &lt;/global&gt; &lt;net name=&quot;Net0&quot; mode=&quot;uml_switch&quot; /&gt; &lt;net name=&quot;Net1&quot; mode=&quot;uml_switch&quot; /&gt; &lt;net name=&quot;Net2&quot; mode=&quot;uml_switch&quot; /&gt; &lt;vm name=&quot;uml1&quot;&gt; &lt;console id=&quot;0&quot;&gt;xterm&lt;/console&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.0.3&quot;&gt;default&lt;/route&gt; &lt;exec seq=&quot;start&quot; type=&quot;verbatim&quot;&gt;nohup /usr/bin/hello &amp;lt;/dev/null &amp;gt;/dev/null 2&amp;gt;&amp;amp;1 &amp;amp; &lt;/exec&gt; &lt;exec seq=&quot;stop&quot; type=&quot;verbatim&quot;&gt;killall hello&lt;/exec&gt; &lt;/vm&gt; &lt;vm name=&quot;uml2&quot;&gt; &lt;console id=&quot;0&quot;&gt;xterm&lt;/console&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.2&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.0.3&quot;&gt;default&lt;/route&gt; &lt;/vm&gt; &lt;vm name=&quot;uml3&quot;&gt; &lt;console id=&quot;0&quot;&gt;xterm&lt;/console&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.3&lt;/ipv4&gt; &lt;/if&gt; &lt;if id=&quot;2&quot; net=&quot;Net1&quot;&gt; &lt;ipv4&gt;10.0.1.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.1.2&quot;&gt;10.0.2.0/24&lt;/route&gt; &lt;forwarding type=&quot;ip&quot; /&gt; &lt;/vm&gt; &lt;vm name=&quot;uml4&quot;&gt; &lt;console id=&quot;0&quot;&gt;xterm&lt;/console&gt; &lt;if id=&quot;1&quot; net=&quot;Net1&quot;&gt; &lt;ipv4&gt;10.0.1.2&lt;/ipv4&gt; &lt;/if&gt; &lt;if id=&quot;2&quot; net=&quot;Net2&quot;&gt; &lt;ipv4&gt;10.0.2.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.1.1&quot;&gt;default&lt;/route&gt; &lt;forwarding type=&quot;ip&quot; /&gt; &lt;/vm&gt; &lt;vm name=&quot;uml5&quot;&gt; &lt;console id=&quot;0&quot;&gt;xterm&lt;/console&gt; &lt;if id=&quot;1&quot; net=&quot;Net2&quot;&gt; &lt;ipv4&gt;10.0.2.2&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.2.1&quot;&gt;default&lt;/route&gt; &lt;/vm&gt; &lt;/vnuml&gt;

The address assignment is as follows:

Previously to build the simulation, you have to generate the SSH public key for the root user, as described in the <a href="#generate_ssh_key">generate ssh key section</a> of this tutorial. Otherwise, vnumlparser.pl will complaint about the ~/.ssh/idenity.pub file.

The example uses the <a href="../reference/index.html#host_mapping">&lt;host_mapping&gt;</a> tag, only allowed to root. This tag enables virtual machine name mapping in /etc/hosts while the simulation is running:

root@host# vnumlparser.pl -t tutorial_root2.xml -v ... root@host# cat /etc/hosts ... 10.250.0.2 uml1 10.250.0.6 uml2 10.250.0.10 uml3 10.250.0.14 uml4 10.250.0.18 uml5 ... root@host# vnumlparser.pl -d tutorial_root2.xml -v ... root@host# cat /etc/hosts ...
 * 1) BEGIN: tutorial-r2
 * 2) topology built: lun jul  4 21:48:08 CEST 2005
 * 1) END: tutorial-r2
 * 1) BEGIN: tutorial-r2
 * 2) topology destroyed: lun jul  4 22:04:16 CEST 2005
 * 3) END: tutorial-r2

Therefore, you can use 'ssh -1 uml1' instead of 'ssh -1 10.250.0.2', for example: more intuitive!

Layer 2 interconnection
Previously, we stated that is possible to connect a virtual machine directly to the host external network (layer 2 interconnection). To do so, a special kind of virtual network, specified with attribute type =&quot;virtual_bridge&quot; in <a href="../reference/index.html#net">&lt;net&gt;</a> tag. In addition, the name of the physical interface in the host is specified with the external attribute. The following VNUML description ( tutorial_root3.xml ) is a variation of tutorial_user1.xml (<a href="#connecting_sim_host">described here</a>), that directly connects uml3 with the host external network, using IP 192.168.0.150 (of course, you have to change this address to one with meaning in your host external network).



&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt; &lt;!DOCTYPE vnuml SYSTEM &quot;/usr/share/xml/vnuml/vnuml.dtd&quot;&gt;

&lt;vnuml&gt; &lt;global&gt; &lt;version&gt;1.7&lt;/version&gt; &lt;simulation_name&gt;tutorial-r3&lt;/simulation_name&gt; &lt;automac/&gt; &lt;vm_mgmt type=&quot;none&quot; /&gt; &lt;vm_defaults&gt; &lt;filesystem type=&quot;cow&quot;&gt;/usr/share/vnuml/filesystems/root_fs_tutorial&lt;/filesystem&gt; &lt;kernel&gt;/usr/share/vnuml/kernels/linux&lt;/kernel&gt; &lt;console id=&quot;0&quot;&gt;xterm&lt;/console&gt; &lt;/vm_defaults&gt; &lt;/global&gt; &lt;net name=&quot;Net0&quot; mode=&quot;uml_switch&quot; /&gt; &lt;net name=&quot;Net1&quot; mode=&quot;uml_switch&quot; /&gt; &lt;net name=&quot;Net2&quot; mode=&quot;uml_switch&quot; /&gt; &lt;net name=&quot;Net3&quot; mode=&quot;virtual_bridge&quot; external=&quot;eth0&quot;/&gt; &lt;vm name=&quot;uml1&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.0.3&quot;&gt;default&lt;/route&gt; &lt;/vm&gt; &lt;vm name=&quot;uml2&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.2&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.0.3&quot;&gt;default&lt;/route&gt; &lt;/vm&gt; &lt;vm name=&quot;uml3&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.3&lt;/ipv4&gt; &lt;/if&gt; &lt;if id=&quot;2&quot; net=&quot;Net1&quot;&gt; &lt;ipv4&gt;10.0.1.1&lt;/ipv4&gt; &lt;/if&gt; &lt;if id=&quot;3&quot; net=&quot;Net3&quot;&gt; &lt;ipv4&gt;192.168.0.150&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.1.2&quot;&gt;10.0.2.0/24&lt;/route&gt; &lt;forwarding type=&quot;ip&quot; /&gt; &lt;/vm&gt; &lt;vm name=&quot;uml4&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net1&quot;&gt; &lt;ipv4&gt;10.0.1.2&lt;/ipv4&gt; &lt;/if&gt; &lt;if id=&quot;2&quot; net=&quot;Net2&quot;&gt; &lt;ipv4&gt;10.0.2.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.1.1&quot;&gt;default&lt;/route&gt; &lt;forwarding type=&quot;ip&quot; /&gt; &lt;/vm&gt; &lt;vm name=&quot;uml5&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net2&quot;&gt; &lt;ipv4&gt;10.0.2.2&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.2.1&quot;&gt;default&lt;/route&gt; &lt;/vm&gt; &lt;host&gt; &lt;hostif net=&quot;Net3&quot;&gt; &lt;ipv4&gt;192.168.0.39&lt;/ipv4&gt; &lt;/hostif&gt; &lt;physicalif name=&quot;eth0&quot; ip=&quot;192.168.0.39&quot; mask=&quot;255.255.255.0&quot; gw=&quot;192.168.0.1&quot; /&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;192.168.0.1&quot;&gt;default&lt;/route&gt; &lt;/host&gt; &lt;/vnuml&gt;

The <a href="../reference/index.html#host">&lt;host&gt;</a> section is not mandatory, but very recommended due to the virtual bridging set up process during &quot;-t&quot; deconfigures the physical interface in the host. The <a href="../reference/index.html#ipv4">&lt;ipv4&gt;</a> and <a href="../reference/index.html#route">&lt;route&gt;</a> tags ensures the host remains properly configured by vnumlparser.pl after &quot;-t&quot; mode (we are supposing that the host address in eth0 is 192.168.0.39 and the default gateway in the external network 192.168.0.1).

During virtual bridge releasing during &quot;-d&quot;, the external connection is also deconfigured. To restore configuration the <a href="../reference/index.html#physicalif">&lt;physicalif&gt;</a> tag is needed. After building the simulation you can check that uml3 reach the gateway and the host interface in the external network:

uml3:~# ping -c 1 192.168.0.1 PING 192.168.0.1 (192.168.0.1) 56(84) bytes of data. 64 bytes from 192.168.0.1: icmp_seq=1 ttl=150 time=0.629 ms

--- 192.168.0.1 ping statistics --- 1 packets transmitted, 1 received, 0% packet loss, time 0ms rtt min/avg/max/mdev = 0.629/0.629/0.629/0.000 ms uml3:~# ping -c 1 192.168.0.39 PING 192.168.0.39 (192.168.0.39) 56(84) bytes of data. 64 bytes from 192.168.0.39: icmp_seq=1 ttl=64 time=31.1 ms

--- 192.168.0.39 ping statistics --- 1 packets transmitted, 1 received, 0% packet loss, time 0ms rtt min/avg/max/mdev = 31.162/31.162/31.162/0.000 ms

Configuring NAT
This section describes a procedure to configure NAT in the host for the scenarios described in section 3 of this tutorial, althought it could be easily adapted to others VNUML scenarios using layer 3 interconnection at host. The procedure has been provided thanks to Carlos Sanmartín. How to configure NAT? Well, we can use iptables(8), included in linux       kernels from 2.4.x We can have included into kernel or load it with a       module:

root@host:~# modprobe ipt_MASQUERADE

It will load ip_tables, ip_conntrack and iptable_nat.

Let's follow next steps: <ol> We have to enable forwarding into kernel, for managing packets which target isn't is our host.

root@host:~# echo 1 > /proc/sys/net/ipv4/ip_forward

For same configuration at any startup, we can add to /etc/sysctl.conf:

net.ipv4.ip_forward=1 </li>

<li>We have to enable NAT rule, for translating virtual machines addresses to host output interface IP address (we suppose eth0 is the output interface):

root@host:~# iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE

</li>

<li>Finally, we have to add a default route for managing outgoing     packages, at uml3:

root@uml3:~# route add default gw 10.0.3.2

</ol>

It looks like this: uml3:~# route Kernel IP routing table Destination    Gateway         Genmask         Flags Metric Ref    Use Iface 10.0.0.0       *               255.255.255.0   U     0      0        0 eth1 10.0.1.0       *               255.255.255.0   U     0      0        0 eth2 10.0.2.0       10.0.1.2        255.255.255.0   UG    0      0        0 eth2 10.0.3.0       *               255.255.255.0   U     0      0        0 eth3 default        10.0.3.2        0.0.0.0         UG    0      0        0 eth3

Now, we can try:

uml1:~# ping -c 1 www.google.es PING www.l.google.com (66.249.93.104) 56(84) bytes of data. 64 bytes from 66.249.93.104: icmp_seq=1 ttl=235 time=56.7 ms

--- www.l.google.com ping statistics --- 1 packets transmitted, 1 received, 0% packet loss, time 0ms rtt min/avg/max/mdev = 56.781/56.781/56.781/0.000 ms

Enjoy it!

For further information, please visit: the <a href="http://www.tldp.org/HOWTO/html_single/Masquerading-Simple-HOWTO">Masquerading Simple HOWTO</a>.

Additional Tips
In addition to the basic tutorial you can try the following tips:

<ul>

<li>Improve performance. A virtualized kernel runs slower than a conventional one. Anyway, UML provides a mechanism of improving efficiency using SKAS mode. Different from previous versions of vnumlparser.pl, version 1.3.0 and beyond works fine with SKAS: you just need to compile a host kernel with SKAS support enabled. <a href="http://user-mode-linux.sourceforge.net/skas.html">More information</a> in the UML Project Web site.</li> <li>Capture traffic in virtual networks. You can use a patched version of uml_switch (look in the contrib/uml_router/ directory inside VNUML package) that, once compiled and installed, can be used to capture traffic in selected virtual networks. This is a powerfull feature, allowing capturing the traffic in simulation experiments for later study (capturing to a file) or even in real time with software tools like Ethereal (although this needs root privilegies). Please have a look to the capture_* attributes of <a href="../reference/index.html#capture">&lt;net&gt;</a> tag to know how to configure it. In addition, you will find a variation of the tutorial for limited user using capture features in the tutorial_limited_user_capture.xml that comes with the VNUML examples).

... &lt;net name=&quot;Net1&quot; mode=&quot;uml_switch&quot; uml_switch_binary=&quot;/usr/local/bin/uml_switch4capture&quot; capture_expression=&quot;icmp&quot; capture_file=&quot;/tmp/net1.pcap&quot; /&gt; ...

</li> <li>Adding users and groups in the virtual machines. In the examples shown so far, there is only one user in the virtual machines: the root user. However, vnumlparser.pl can add users to the virtual machines using <a href="../reference/index.html#user">&lt;user&gt;</a> tag. Try          replacing the following vm section for uml1 in the tutorial_limited_user.xml file (or use the tutorial_limited_user2.xml file that comes with the VNUML examples):

... &lt;vm name=&quot;uml1&quot;&gt; &lt;if id=&quot;1&quot; net=&quot;Net0&quot;&gt; &lt;ipv4&gt;10.0.0.1&lt;/ipv4&gt; &lt;/if&gt; &lt;route type=&quot;ipv4&quot; gw=&quot;10.0.0.3&quot;&gt;default&lt;/route&gt; &lt;user username=&quot;yoda&quot; group=&quot;jedi&quot;&gt; &lt;group&gt;jedi&lt;/group&gt; &lt;group&gt;lightside&lt;/group&gt; &lt;/user&gt; &lt;user username=&quot;anakin&quot; group=&quot;sith&quot;&gt; &lt;group&gt;sith&lt;/group&gt; &lt;group&gt;darkside&lt;/group&gt; &lt;/user&gt; &lt;/vm&gt; ...

Once built the simulation, you can check how the yoda and anakin users are created in uml1:

uml1:~# id yoda uid=1002(yoda) gid=1003(jedi) groups=1003(jedi),1004(lightside) uml1:~# id anakin uid=1001(anakin) gid=1001(sith) groups=1001(sith),1002(darkside)

</li>

<li>UML kernel and filesystem selection. In the examples shown so far, the kernel and UML filesystem for all the virtual machines is set up with the <a href="../reference/index.html#vm_defaults">&lt;vm_defaults&gt;</a>. However, you can specify a different UML kernel using <a href="../reference/index.html#kernel">&lt;kernel&gt;</a> and <a href="../reference/index.html#filesystem">&lt;filesystem&gt;</a> tags in a per-vm basis.</li>

</ul>

Execution Logs (1.7.0)
The following logs were taken while performing this tutorial at morfeo (Debian system running 2.6.10-skas3-7), using verbose switch (-v) of       vnumlparser.pl version 1.7.0. UMLs run 2.6.10-1m.

Building topology:

root@morfeo# vnumlparser.pl -t tutorial.xml -v TODO

Executing commands (start):

root@morfeo# vnumlparser.pl -x start@tutorial_plus.xml -v TODO

Executing commands (stop):

root@morfeo# vnumlparser.pl -x stop@tutorial_plus.xml -v TODO

Destroying topology:

root@morfeo# vnumlparser.pl -d tutorial_plus.xml -v TODO