UNIVERSITY OF ZAGREB

FACULTY OF ELECTRICAL ENGINEERING AND COMPUTING

DEPARTMENT OF TELECOMMUNICATIONS

IMUNES
Users Guide

Zagreb, 2004.
IMUNES: Users Guide
Table of Contents
1. Introduction...........................................................................................................1
Overview ............................................................................................................1
IMUNES objects ................................................................................................1
Document organization ......................................................................................2
2. Creating and editing experiments .......................................................................3
Starting IMUNES...............................................................................................3
Graphical User Interface ....................................................................................3
Menu bar....................................................................................................4
File menu ..........................................................................................4
Edit menu..........................................................................................5
View menu ........................................................................................5
Experiment........................................................................................5
Help...................................................................................................5
Toolbox ......................................................................................................5
Status bar ...................................................................................................6
Nodes..................................................................................................................6
Nodes manipulation...................................................................................7
Adding new nodes.............................................................................7
Selecting nodes .................................................................................7
Moving nodes ...................................................................................8
Deleting nodes ..................................................................................8
Configuring nodes .....................................................................................8
Attaching physical interfaces...................................................................10
Interface manipulation ....................................................................10
Assigning a physical interface ........................................................10
Links.................................................................................................................11
Link manipulation ...................................................................................11
Adding new links ............................................................................11
Deleting the link..............................................................................12
Configuring links .....................................................................................12
Example............................................................................................................13
3. Executing experiments........................................................................................16
Starting the simulation .....................................................................................16
Creation of nodes.....................................................................................16
Creation of links ......................................................................................17
Configuring nodes ...................................................................................17
Simulation ........................................................................................................18
Example............................................................................................................20
Stopping the simulation....................................................................................23
Shutting down netgraph nodes ................................................................24
Shutting down vimages ...........................................................................24

iii
Glossary ...................................................................................................................26
A. Network topology configuration file .................................................................28
Description .......................................................................................................28
Nodes................................................................................................................28
type ..........................................................................................................29
cpu ...........................................................................................................29
model .......................................................................................................29
network-config.........................................................................................29
hostname name ...............................................................................29
interface name.................................................................................29
router protocol ................................................................................30
ip route networkIP gatewayIP.........................................................30
iconcoords................................................................................................30
labelcoords...............................................................................................31
interface-peer ...........................................................................................31
Links.................................................................................................................32
duplicate ..................................................................................................32
ber ............................................................................................................33
nodes........................................................................................................33
bandwidth ................................................................................................33
delay ........................................................................................................33
B. Getting IMUNES ................................................................................................34
C. Installing IMUNES ............................................................................................35
Prerequisites .....................................................................................................35
Download .........................................................................................................35
Install................................................................................................................35
D. Online resources .................................................................................................37
Bibliography ............................................................................................................38

iv
List of Figures
2-1. Graphical user interface layout............................................................................4
2-2. Menu bar..............................................................................................................4
2-3. toolbox .................................................................................................................5
2-4. Status bar in the edit mode ..................................................................................6
2-5. Status bar in the exec mode .................................................................................6
2-6. LAN switch configuration parameters.................................................................8
2-7. Router configuration parameters .........................................................................9
2-8. Interface parameters...........................................................................................10
2-9. Creating new link...............................................................................................12
2-10. Link configuration parameters.........................................................................12
2-11. Topology ..........................................................................................................14
3-1. The status bar after transition from the edit to the exec mode...........................16
3-2. Error message ....................................................................................................17
3-3. Statusbar during the creation of a link...............................................................17
3-4. Status bar during the configuration of a node....................................................18
3-5. Toolbox during the simulation...........................................................................18
3-6. Consoles.............................................................................................................19
3-7. Topology ............................................................................................................20
3-8. Routing table of the router0...............................................................................21
3-9. Ping output.........................................................................................................22
3-10. Traceroute from pc4 to host2...........................................................................22
3-11. The result of stopping the simulation in a command line................................23
3-12. Imunes after hitting "terminate" ......................................................................24
A-1. Node configuration format................................................................................31

v
Chapter 1. Introduction

Overview
IMUNES is an Integrated MUltiprotocol Network Emulator / Simulator. As
invaluable tools in networked and distributed systems research, network emulators
offer a viable alternative to live experimental / testbed networks. We are developing
a network emulation framework based on the FreeBSD operating system kernel
partitioned into multiple lightweight virtual nodes, which can be interconnected via
kernel-level links to form arbitrarily complex network topologies. The concept of
using virtual nodes inside a kernel for fast network emulation is not entirely new, yet
previously published work generally advocated the implementation of kernel-level
virtual nodes with capabilities limited to only certain simple functions, such as
passing of network frames from one queue to another based on a static precomputed
path. Our work is based on a thesis that virtual nodes, which could offer the identical
rich set of capabilities as the standard kernel does, can be implemented very
efficiently by reusing the existing OS kernel code. Our model therefore provides
each node with an independent replica of the entire standard network stack, thus
enabling highly realistic and detailed emulation of network routers. It also enables
each virtual node to run a private copy of any unmodified user-level application,
including routing protocol daemons, traffic generators, analyzers, or application
servers. Furthermore, in later development phases, we expect to enable each virtual
node to support multiple network protocols concurrently, such as both IPv4 and
IPv6, which would bring us a step closer to allowing for emulation of true
multiprotocol networked environments.

IMUNES objects
In IMUNES there are two basic construction units: nodes and links. Internally they
are presented as kernel structures, capable of preforming functions of the nodes and
the links that they simulate. By using this kernel structures different topologies can
be simulated.
Nodes are further classified into two groups:

link layer nodes

Nodes with no network layer functions, capable of operating with packets on
link layer level. Representatives of this group are LAN switch and physical
interface.

network layer nodes

Nodes with implemented IP network stack, capable of operating with packets

1
 Chapter 1. Introduction

on network layer level. Router, pc and host nodes fall into this category.

The use of nodes will be described in the Section called Nodes in Chapter 2.
Different types of links can also be simulated. This is accomplished by changing the
link parameters, as it will be described in the Section called Links in Chapter 2.

Document organization
In the Chapter 2 there is a detailed description of how to create the desired topology
in IMUNES. This includes how to start IMUNES, followed by the GUI description
and the use of IMUNES before starting simulation. In IMUNES there are two basic
building units, nodes and links. Different types of nodes, links and there parameters
allow the simulation to be more realistic. All this types and parameters are described
in this chapter. There will also be an example of creating and configuring a simple
topology.
Chapter 3 explaines what happens when simulation starts and how to use simulation
and stop simulation. Two operating modes of IMUNES are specified, edit and exec
mode. The way of accessing the console of a particular node will also be described.
During the simulation all kinds of different programs available on the hosting
machine can be started from any simulated network layer node. The parameters of
the simulated links and nodes can be dynamically changed during the simulation. At
the end there is an example.

2
Chapter 2. Creating and editing experiments

Starting IMUNES
Installation of IMUNES is explained in Appendix C.
IMUNES usually runs under X11. The easiest way to start IMUNES is by writing
the following command in xterm command prompt:
# imunes
This will open an empty panel on which any desired topology can be drawn.
If the topology already exists (saved in IMUNES network topology configuration
file), by calling:
# imunes file_name.imn
the topology described in file file_name.imn will be displayed on the panel.
Existing topology can be changed before starting the simulation. The simulation is
started and stopped using Experiment menu (Execute / Terminate).
If no GUI is available (no X11), or there is no need for it, IMUNES can be run from
console: Appendix A
# imunes -b file_name.imn
Topology, described in file_name.imn, will be created in kernel and accessible
through vimage functionality [5]. The simulation is automatically started and there
is no edit mode.
The simulation can be stopped from command line with:
# imunes -b
(all kernel structures will be destroyed, detached or removed)

Graphical User Interface

IMUNES comes with a simple Tcl/Tk based graphical user interface console (Figure
2-1), which operates in two modes:

• edit mode
• exec mode
By starting IMUNES operating mode is set to edit mode.
Edit mode is the mode in which the topology can be modified by adding, deleting
and editing nodes or links. Exec mode is the mode in which the simulation runns.

3
 Chapter 2. Creating and editing experiments

For further changes of the topology operating mode must be reset to edit mode
(Experiment -> Terimate).

Figure 2-1. Graphical user interface layout

The name of the current network configuration file can be seen in the windows title.
Default extension used for IMUNES network configuration files is imn. The menu
bar is right under the file name (Figure 2-2).

Menu bar

Figure 2-2. Menu bar

File menu
New - create a new file
Open - open an existing file
Save - save new or opened file

4
 Chapter 2. Creating and editing experiments

Save As - save new or opened file using a different name

Print - print current topology
Exit - exit IMUNES
New, Open, Save and Exit commands have shortcuts which are displayed after the
name of the command in the menu.

Edit menu
Undo - undo the previous action, also reachable through Ctrl + Z command.
Redo - executes the action that was canceled, also reachable through Ctrl + Y command.

View menu
Submenu Show containing following items:

Show interface names - Show or hide interface names on the panel

Show IP addresses - Show or hide IP addresses on the panel
Show node labels - Show or hide node labels on the panel
Show link labels - Show or hide link labels on the panel.

Experiment
Execute - Create virtual nodes and links and start the simulation
Terminate - Stop simulation and destroy internal topology.

Help
About - Show copyright

Toolbox
On the left side there is a toolbox (figure 2-3).

5
 Chapter 2. Creating and editing experiments

Figure 2-3. toolbox

Available tools are (in the order from top to bottom): select, delete, link, router,
LAN switch, host, pc and physical interface. Router, host and pc represent network
layer nodes while LAN switch and physical interface represent link layer nodes.
They will all be explained in the Section called Nodes.

Status bar
On the bottom there is a status bar, divided into four fields. The first indicates
current configuration of the object under the mouse pointer. It is used in edit and
exec modes. During the transition from the edit to the exec mode and vice versa it
also indicates actions being performed in the background. The second and the third
field are used only in the exec mode for indication of the resources being used by
IMUNES. The last field shows the current operating mode. The following figures
represent status bar in the edit mode (Figure 2-4) and the exec mode (Figure 2-5).

Figure 2-4. Status bar in the edit mode

Figure 2-5. Status bar in the exec mode

6
 Chapter 2. Creating and editing experiments

Nodes
In IMUNES there are two groups of nodes:

• network layer nodes

• link layer nodes

There are three different network layer node types: router, host and pc.

• Router is a node performing a routing function and running some routing

daemon.
• Host is using only static routing and has some services started by default. They
are portmap, inetd and netserver.
• PC is also using only static routes. No additional services are started during the
configuration.

There are two different link layer node types: LAN switch and physical interface

• LAN switch has no IP address. Any number of other types of nodes can be
connected to it. Two LAN switches can not be connected directly.
• Physical interface represents real physical interface used for communication of
the simulated network with external network.

Nodes manipulation

Adding new nodes

New nodes can be added to the panel simply by choosing the apropriate type of a
node in the toolbox and clicking on the desired place on the panel. Every subsequent
node can be added simply by clicking on the desired place on the panel. When all
nodes are placed it is recommended to change the active tool to "select".

Selecting nodes
For selecting nodes on the panel active tool must be set to select tool. One node can
be selected simple by clicking on it. Pressing the left mouse button on one point on
the panel and releasing it on some other point will select all the nodes inside
rectangle visable during this process. All the selected nodes have bordes aroud them.

7
 Chapter 2. Creating and editing experiments

Moving nodes
Existing nodes can be rearranged using the select tool. Moving is accomplished by
dragging the selected nodes to the new position and dropping it there (drag&drop
method). All links that are connected to selected nodes are also moved. Node labels
can also be rearranged using the same drag&drop method.

Deleting nodes
Nodes can be deleted using the delete tool. Clicking on the node while the delete
tool is active will delete that node. When deleting a node all links associated with
that node will also be deleted. Deleting two or more nodes at the same time is
accomplished by selecting the nodes and clicking on either one of them with the
active tool set to the delete tool.

Configuring nodes
Each node has a set of parameters associated with it. Parameters of a node can be
viewed or changed by double clicking on the node. Figure 2-6 shows parameters of
a LAN switch.
The first parameter is the Node name, and every node has it. The name of the node is
displayed on the label next to the node. It is not the name in DNS, so it can not be
used for communication between nodes. The same name can be used for more than
one node.
The name of the node is not a node identifier. The node identifier is in the form of
na, where a is a unique numerical value. This identifier is written in the network
topology configuration file (after the key word node).
Every node, if it is linked to some other node, has interfaces.
For each LAN switch interface the type of a queue can be selected. Available types
are: FIFO, DRR, and WFQ. It is also possible to change the packet dropping policy
from droptail to drophead. Another parameter available is a maximal queue length,
set to 50 packages by default. Parameters of a LAN switch as well as the different
values for the type of a queue, the dropping policy and the maximal queue size can
be seen on the Figure 2-6.

8
 Chapter 2. Creating and editing experiments

Figure 2-6. LAN switch configuration parameters

Interfaces of all the other nodes have some additional parameters. They have the
possibility of shutting down the interface or bringing it up. Every interface of a
router, PC or host also has an IP address. Allowed format for IP addresses is:
a.b.c.d/m, where m is the number of the bits masked for determining the subnet.
MTU can also be defined for every interface of a router, host or PC.
Static routes can be written for every network layer node. The format for writing
routes is: a.b.c.d/m gatewayIP. Routers have the option for using quagga [3] or static
routing model. Support for XORP [4] is under development. Currently default
dynamic routing protocol is RIPv2, but quagga [3] has the support for other routing
protocols, such as OSPF and BGP. Router configuration parameters are shown on
the Figure 2-7.

Figure 2-7. Router configuration parameters

9
 Chapter 2. Creating and editing experiments

Every PC, router or host has additional parameters for virtual image [2] that will be
created on its place in the kernel. The first parameter determinates the minimum
CPU load, the second maximum CPU load, and weight is the parameter that shows
how the virtual image will compete for CPU time. For more information on this
parameters check [5].

Attaching physical interfaces

Physical interface tool in the toolbox has the purpose of connecting a real (physical,
external) interface to the simulated node. Through this tool the simulated network
can communicate with an external network.

Interface manipulation
Interface can be manipulated in the following ways:

Adding a new physical interface

It is done in the same way as for any other node. Select the physical interface
tool and click on the desired place on the panel. New physical interface gets a
label UNASSIGNED. This label must be changed before the simulation can
be started (see "Assigning an interface")

Deleting a physical interface

Deleting the physical interface is done by selecting delete tool and clicking
over the interface that is to be deleted.

Connecting the physical interface

Physical interface can be connected to a router or a LAN switch by using
links. Interface can not be connected more than once. The connection can be
broken by deleting the link that is connecting it to the node.

Assigning a physical interface

As explained earlier newly created interface is considered unassigned. The process
of assigning an interface is similar to changing parameters of a node or a link. By
double clicking on the interface, the dialog box (Figure 2-8) appears.

10
 Chapter 2. Creating and editing experiments

Figure 2-8. Interface parameters

The name of the interface must be changed into the name of an existing physical
interface on the machine where the simulation is run (for example: lnc0). For every
existing physical interface 4096 different VLAN identifiers can be used. By using
different VLAN identifiers it is possible to connect one physical interface to more
than one node.
It is not allowed to have:

• more than one interface associated to the same physical interface and the same
VLAN identifier,
• interface that is not assigned,
• interface that is assigned to a nonexistent physical interface.

The other parameters of the physical interface are configured on the corresponding
interface of the node to which the physical interface is connected. When physical
interface is assigned to a router the queue type (FIFO, DRR, and WFQ), the packet
dropping policy (drophead, droptail) and the queue length are not available on that
interface.

Links
Every node can be connected to almost any other node by using links. Already
connected nodes can not be connected again (only one link between two nodes can
be made).

Link manipulation
Links can be created or deleted. The first node and the second node of a link can not
be changed. Deleting any node, that the link connects, will also delete the link.

11
 Chapter 2. Creating and editing experiments

Adding new links

For connecting two nodes (adding a new link), the link tool must be selected.
Pressing the left mouse button on the first node and releasing it on the second node
will create link between those two nodes. The Figure 2-9 shows link creation. If
mouse button is released with no node under it, new link will not be created. The
link between two LAN switches is not allowed. After all desired links are added, it
is recommended to change the active tool to select tool.

Figure 2-9. Creating new link

Deleting the link

Deleting links is similar to deleting nodes. The delete tool must be selected.
Clicking on the link that is to be deleted, removes it from the topology.

Configuring links
Different types of links can be simulated by changing the parameters of the link.
These parameters are accessed by double clicking on the link. On the Figure 2-10
these parameters can be seen.

12
 Chapter 2. Creating and editing experiments

Figure 2-10. Link configuration parameters

Bandwidth
It is measured in the number of bits per second (bps). By changing this
parameter we can simulate slow or fast links, and change transmition delay for
packages. The allowed values are between 100 and 109.

Delay
It is used for the simulation of a propagation delay which depends on the
length of a link and the link bandwidth. The delay is measured in us. The
allowed values are in between 0 to 107.

BER
It represents the probability of a bit error rate. This probability is equal to 1/N,
where N is the integer value entered in the BER field. Maximum 1012. If there
is no BER specified, or the value of BER is set to 0, then it is assumed that the
link is transmitting without error .

Duplicate
It represents the probability of occurrence of duplicate packages on the link. It
is measured in %. The allowed values are between 0 and 50.
Link that is used for the connection of a physical interface with a node is considered
ideal so it has no parameters, and thus can not be configured.

Example
In this section the procedure of creating a simple topology will be demonstrated.
The same topology will be used in the next section.
This topology will consists of two routers, one LAN switch, two PCs, one host and
one physical interface connected to a local network.

13
 Chapter 2. Creating and editing experiments

The described topology is created using following steps:

1. Select the router node tool and click on the panel on two different places. This
will create two new routers.
2. Select the host node tool and click on the empty space on the panel.
3. Select the LAN switch node tool and click on the panel, this will create a new
LAN switch on the panel.
4. Select the PC node tool from the toolbox and click on the panel on two
different places.
5. Select the physical interface tool and click on the panel. At this time all nodes
will be added to the panel.
6. Choose select tool from the toolbox and place (move) the created objects to the
desired places (as in the Figure 2-11).
7. Select the link tool and connect objects on the panel in the way they are
connected in the Figure 2-11.

When all nodes and links are added, it is the time to configure the topology.
The first thing to do is to assign the physical interface node to a real physical
interface. This is accomplished by double clicking on the physical interface node
and changing its name parameter to an existing physical interface name (run ifconfig
for viewing the list of existing interfaces). On Figure 2-11 the interface node is
assigned to the lnc0 physical interface.
Set the delay of the link connecting pc4 and lanswitch3 to 10ms:

1. Double click on the link connecting pc4 and lanswitch3.

2. Enter 10000 in the field for delay.
3. Select Apply.

14
 Chapter 2. Creating and editing experiments

Figure 2-11. Topology

15
Chapter 3. Executing experiments

Starting the simulation

Simulation can be started when the desired topology is generated. Simulation starts
by choosing Experiment -> Execute command. The operating mode is switched to
the exec mode.
During the translation from the edit mode to the exec mode all necessary objects are
created in the kernel.
In the exec mode no additional topology can be drawn.
Another way to start the simulation is by using -b option and the network topology
configuration file when starting IMUNES from a command line (as described in the
Section called Starting IMUNES in Chapter 2). If the simulation is started this way
then there is no GUI.
This is the list of the things that happen when starting the simulation:

1. Clean up - IMUNES checks if there are some objects left from the previous
simulation and cleans them up.
2. Creation of nodes - IMUNES creates simulated nodes and physical interfaces.
It is explained in more details in the Section called Creation of nodes.
3. Creation of links - links and interfaces are created and configured in this phase
(see the the Section called Creation of links).
4. Configuration of nodes - nodes are configured (see the the Section called
Configuring nodes).
5. After the configuration of all nodes and links has been finished the status bar
indicates how long it took to make all necessary objects in the kernel.

Figure 3-1. The status bar after transition from the edit to the exec mode

This process is the same for starting IMUNES without GUI and all status bar
comments are sequentially displayed on a console.

16
 Chapter 3. Executing experiments

Creation of nodes
There are no differences between a host, PC and router in this stage. Every one of
them is treated as an exact replica of hosting FreeBSD system with no active
processes. This virtual images are created using vimage functionality [5].
Virtual images are created only for the network layer nodes.
The physical interfaces are brought up. If the physical interface name in IMUNES
does not respond to the real physical interface name, or there are more then one
interfaces with the same name and the vlan identifier, simulation can not be started.
In that case the message like the one on the Figure 3-2 is displayed.

Figure 3-2. Error message

During the creation of nodes there is an appropriate message displayed in the status
bar.

Creation of links
Creation of links starts internally with the creation of interfaces in every node.
Different types of interfaces are added, depending on the type of connection (for
example: between a LAN switch and any other node, Ethernet type of the interface
is created). When all the interfaces are created, or added (in the case of physical
interface) to the node, links are created. The parameters of the links are used to
configure links. In this step also the configuration of all interfaces is made. This
means the packet dropping policy is enforced, the queue length and the type of a
queue is set.

Figure 3-3. Statusbar during the creation of a link

17
 Chapter 3. Executing experiments

Configuring nodes
For every host, router and PC the parameters for the CPU (min, max and weight) are
enforced and the loop back interface is created. MTU is also set.
In this step difference between a PC, router and host is made:

• Router - the routing model and the routing protocol are set. The kernel variable
net.inet.ip.forwarding is set to 1, so the forwarding of packages is enabled.
• Host - the programs portmap, inetd and netserver are started. Static routes are
set.
• PC - Static routes are set.
The status bar at this time is similar to the one on the Figure 3-4.

Figure 3-4. Status bar during the configuration of a node

Simulation
Once the simulation has started, no additional topology can be generated. Only the
select tool from toolbox is available for rearranging the topology (nodes can be
moved in the way described in the Section called Moving nodes in Chapter 2).
Nodes and links can not be added or deleted. The look of the toolbox during the
simulation is presented on the Figure 3-5.

18
 Chapter 3. Executing experiments

Figure 3-5. Toolbox during the simulation

On the previous figure, another thing can be noticed. In the status bar second and
third fields are filled. The second field represents the current CPU load, and must be
in some reasonable limits. In the third field the precentage of used mbufers and
clousters is presented. If this number reaches 100% then kernel variables
kern.ipc.nmbclusters and kern.ipc.nmbufs in the /boot/loader.conf file must be set to
larger values and the system should reboot for changes to make an effect.
The parameters of nodes and links can be changed. This is accomplished by double
clicking on the node or the link, and editing the dialog box that appears. The
parameters of the nodes are described in the Section called Configuring nodes in
Chapter 2, and the parameters of the links in the Section called Configuring links in
Chapter 2.
Execpt for limitations on options available during the edit mode, in the exec mode a
new option is available. By clicking the right mouse button on a network layer node
the console opens (On the Figure 3-6 open consoles for router0, host2 and PC4 can
be seen). For a router this console is the standard vtysh shell and for a host or PC the
csh shell. More than one console per node can be open at the same time.

19
 Chapter 3. Executing experiments

Figure 3-6. Consoles

By using the csh shell new processes can be started on each host or PC. The
available programs and processes are the same as for the FreeBSD system that hosts
IMUNES.
Console for each node can be also accessed if IMUNES is started without GUI with
command:
# vimage na
Where na is the unique identifier for a node. The value of the node identifier can be
found in the network topology configuration file, which is formatted as described in
Appendix A. By writing exit the control over the console is returned.

Example
In this section the topology from the Section called Example in Chapter 2 will be
simulated.
This topology is presented on the Figure 3-7.

20
 Chapter 3. Executing experiments

Figure 3-7. Topology

Simulation starts by hitting Experiment -> Execute. Now, when all necessary
kernel objects are created this topology can be used.
The routing table of router0 can be viewed by opening a vtysh console on router0
(right click on router0 icon), and typing the following command:
router0> show ip route
The output is presented on the Figure 3-8

Figure 3-8. Routing table of the router0

The output shows that there are three directly connected networks, the network
10.0.0.0/24 through the interface eth0, the network 10.0.1.0/24 through the interface
ser0 and the loopback network (127.0.0.0/8) connected through the loopback
interface lo0.

21
 Chapter 3. Executing experiments

There are also two routes obtained with RIP routing protocol. From this routes it can
be seen that the network 10.0.2.0/24 and the network 10.0.3.0/24 are reachable
through the router interface ser0, using the gateway 10.0.1.2.
Ping is the standard program used for testing network connectivity. Here it will be
used to show that simulated nodes can be reached from the node pc4:
# ping 10.0.0.2
The output is presented on the Figure 3-9

Figure 3-9. Ping output

As presented on the Figure 3-9 from 10 packets transmitted, all 10 was received, and
none was lost. The average RTT is 26.153, which is very close to the expected RTT
of 25.578ms for the given propagation and transmition delay.
The last program used to demonstrate the network connectivity is treaceroute. This
program shows the most probable hops that a packet has made on his way to the
destination. The use of this program is simple, just writing:
# traceroute ipaddr
in the console results in the list of hopes and three RTT for every hop.
To use treceroute from pc4 to host2 a console must be open on pc4. From the Figure
3-7 it can be seen that the only path from pc4 to host2 is through lanswitch3, router1
and router0. Writing:
# traceroute 10.0.0.2

results in displaying the following list. The LAN switch has no network layer so it
won’t be displayed in the list of hops.

22
 Chapter 3. Executing experiments

Figure 3-10. Traceroute from pc4 to host2

Stopping the simulation

Simulation that was started with a GUI stops by choosing Experiment ->
Terminate command. The operating mode is switched back to the edit mode.
During the translation from the exec to the edit mode all kernel objects, used by
simulation, are destroyed.
Stopping the simulation that was started from a command line (by using -b option
and a network topology configuration file when calling IMUNES) is accomplished
by calling imunes with -b option (without any other arguments).
# imunes -b

Figure 3-11. The result of stopping the simulation in a command line

The process of stopping the simulation can be divided into two basic actions:

23
 Chapter 3. Executing experiments

• Shutting down netgraph nodes

• Shutting down vimages

Shutting down netgraph nodes

Every link, interface (virtual or physical) or LAN switch represents one netgraph
node. All of the netgraph nodes are being shut down at this time. The message,
displayed in the status bar or on the console, uses only netgraph node and it’s
internal name for informing of links, interfaces and LAN switches detachment,
destruction or reassignment.
The format for the netgraph node name of the link is na-nb, where a and b are
identifiers of the nodes that are connected with the link.
The format for the netgraph node name of the interfaces is IfcName@nb. IfcName is
the name of the interface and b is the identifier of the node to which this interface is
attached.
LAN switch netgraph node name is in the form of na, where a is the identifier of the
LAN switch node.

Shutting down vimages

Every PC, host or router is represented in the kernel with a corresponding vimage
[2]. The process of shutting down vimages is divided into following steps:

• Killing all processes attached to any vimage.

• Deleting all temporary files created by the simulation.
• Deleting every vimage.
• Restoring original files like /etc/resolv.conf.

After all nodes, links and interfaces are shut down the status bar indicates how long
it took for imunes to stop the simulation (Figure 3-12).

24
 Chapter 3. Executing experiments

Figure 3-12. Imunes after hitting "terminate"

25
Glossary
Bit Error Rate

Represents the probability of occurring an error on one bit during the

transmition.

Border Gateway Protocol

An inter-Autonomous System routing protocol. Its primary function is to

exchange the network reachability information with other BGP systems. Those
information are sufficient for constructing a graph of the autonomous system
connectivity.
See Also: Routing Information Protocol, Open Shortest Path First.

Deficit Round Robin

A modified weighted round robin scheduling discipline. It can handle packets

of a variable size without knowing their mean size. It serves packets at the head
of every nonempty queue which deficit counter is greater than the packet’s size.
If it’s lower, then the deficit counter is increased by some given value called
quantum. Deficit counter is decreased by the size of packets being served.
See Also: Weighted Fair Queuing.

Explicit Congestion Notification

Addition to the active queuing management. Instead of dropping the packet, a

notification is being sent to the sender. The source responds like the packet is
being dropped.
See Also: Random Early Detection.

First In First Out

One of the queuing algorithms. The packet that came first is the one that is
transmitted first.
See Also: Weighted Fair Queuing.

Head dropping

Static queue management algorithm. The packages are dropped from the front
of the queue when the queue overflows.
See Also: Tail dropping.

26
Maximum Transmission Unit

The maximum number of bytes of data that can be transmitted through the link
without performing IP fragmentation.

Open Shortest Path First

Routing protocol. The packet is routed thorough the path with the minimum
cost (shortest path).
See Also: Routing Information Protocol, Border Gateway Protocol.

Random Early Detection

Active queue management algorithm. The packages are dropped with some
probability before the queue overflows. The probability of packet dropping is
calculated on the time-averaged queue length.
See Also: Explicit Congestion Notification.

Routing Information Protocol

Routing protocol. The packet is routed thorough the path with the minimum
number of hops.
See Also: Open Shortest Path First.

Tail dropping

Static queue management algorithm. The packages are dropped from the tail of
the queue when the queue overflows.
See Also: Head dropping.

Weighted Fair Queuing

One of the fair queuing algorithms. The packet is classified and assigned to one
queue. The queue is served in a weighted round robin manner.
See Also: Deficit Round Robin, First In First Out.

27
Appendix A. Network topology configuration file

Description
The IMUNES network topology configuration file consists of a list of nodes and a
list of links. This file can be created in two ways:

• using IMUNES GUI,

• using text editor.

When using the IMUNES GUI, the topology displayed and configured can be saved
in a new or an existing network topology configuration file, under the desired name.
On the other hand, if no GUI is available it can be wrote in any textual editor.
The main format of network topology configuration file contains sections concerning
nodes and sections concerning links. Written in the terms of regular expesions:
file := [nodes]*[linkes]*

Nodes
Nodes are entered by using a node identifier. After the node identifier, there is an
open bracket that is closed after the last entry concerning that node.
Inside the brackets following things can be found in described order:

nodes :=
node node_identifier {
type host|router|PC|lanswitch|rj45
[cpu {{ min min_value } { max max_value } { weight weight_value }}]
[model quagga]
network-config {
[hostname] name
[interface ifc_name
[drophead]
[shutdown]
[fair-queue|drr-queue]
[ip address a.b.c.d/m]
[queue-len n]
[mtu n]]+
[router protocol
-- CISCO style cofiguration of routers]

28
 Appendix A. Network topology configuration file

[ip route networkIP gatewayIP]

[iconcoords {a b}
labelcoords {a b}]
[interface-peer {ifc node}]*
}

type
type host | router | PC | lanswitch | rj45
This parameter is required. Allowed values are: host, PC, router, lanswitch or
rj45.

cpu
cpu := cpu {{min min_value} {max max_value} {weight
weight_value}}
This parameter is optional. It defines minimum and maximum CPU load, and the
weight.

model
This parameter is optional. The currently allowed value is quagga

network-config
This parameter is required. It represents CISCO style [7] configuration of a network
. It contains some sections (listed below), that can be divided by "!".

hostname name
Defines the name of the host. It is optional.

interface name
Defines the name of the interface, and interface configuration parameters. They are
the following:

29
 Appendix A. Network topology configuration file

drophead
Dropps packets from the front of the queue. If nothing specified, the droptail
packet policy is assumed.

shutdown
On start of the simulation the interface will be shutdown. If nothing specified,
it is assumed the interface is up.

fair-queue

The interface queuing algorithm is set to the Weighted Fair Queuing. This
option can not be used together with drr-queue option. If no fair-queue
and no drr-queue option is specified, fifo queuing algorithm is assumed.

drr-queue
The interface queuing algorithm is set to the Deficit Round Robin. This option
can not be used together with fair-queue option. If no fair-queue or no
drr-queue option is specified, the First In First Out queuing algorithm is
assumed.

ip address a.b.c.d/m

The IP address is set to a.b.c.d and subnet mask is set to m bits.

queue-len n
The queue length is set to the numeric value n.

mtu n

The value of Maximum Transmission Unit is set to the numeric value n.

router protocol
The routing protocol is set to protocol. Additional parameters are the same as for
CISCO [7] routers. This parameter is optional and usually set only for a router type
of nodes.

ip route networkIP gatewayIP

Additional static ip routes. This parameter is optional and usually set for a host or a
PC types of nodes. networkIP is in the format a.b.c.d/m, and gatewayIP in the
format a.b.c.d.

30
 Appendix A. Network topology configuration file

iconcoords
This parameter is optional for simulations started without the GUI and required for
simulations with the GUI. It saves the position of the node icon on the panel. The
format or this option is the following:
iconcoords {a b}
a and b are numbers in the format n.0, where n is a numerical value representing the
number of pixels from the left top corner of the panel in the GUI of IMUNES (a -
width, b - height).

labelcoords
This parameter is optional for simulations started without the GUI and required for
simulations with the GUI. It saves the position of the node label on the panel. The
format of this option is the following:
labelcoords {a b}
a and b are numbers in the format n.0, where n is a numerical value representing the
number of pixels from the left top corner of the panel in the GUI of IMUNES (a -
width, b - height).

interface-peer
This parameter is used for every interface of the node. The format of this option is
the following:
interface-peer {ifc node}
ifc is the name of the interface and node is the name of the peer node (the node is
connected to the interface).

31
 Appendix A. Network topology configuration file

Figure A-1. Node configuration format

Links
Links are entered by using the link keyword followed by the link unique identifier
in the form of la, where a is a numerical value. The parameters of the link (except
for the link identifier) are listed together in the section that starts with an open
bracket, and ends with close bracket. The parameters of the links are the following:

links :=
link link_identifier {
[duplicate n]
[ber n]
nodes {na nb}
bandwidth n
[delay n]
}

duplicate
This parameter determents the packet duplicate percentage as a numerical value. It is
entered in the following format:

32
 Appendix A. Network topology configuration file

duplicate n
Where n is the percentage of the duplicated packets on the network. This parameter
is optional.

ber
Ber represents the Bit Error Rate.It is entered in the following format:
ber n
Where probability of the Bit Error Rate is calculated as 1/n. This parameter is
optional.

nodes
This parameter consists of two node identifiers, representing the end nodes for the
link. The format of this parameter is the following:
nodes {na nb}
The na and nb stand for the identifiers of the end nodes. This parameter is required.

bandwidth
This parameter represents the bandwidth of the simulated link in the bits per second
unit. The format is the following:
bandwidth n
Where n is a numerical value of the bandwidth. This parameter is required.

delay
This parameter represents the delay on the link. It is in the following format:
delay n

Where n is the delay measured in us. This parameter is optional.

33
Appendix B. Getting IMUNES
There are two alernatives for getting IMUNES:

• Using bootable CD,

• Installing on FreeBSD 4.10-RELEASE (-STABLE most probably won’t do!).
The process of installing IMUNES is described in Appendix C.
Using bootable CD should be straightforward, and most importantly it doesn’t need
and won’t touch anything on your disk drives.
Just download ISO image of bootable CD:
limunes-latest.iso.gz1
Burn this image and boot the system from CD.
From the menu select IMUNES.
This will automaticaly start X11 and IMUNES with GUI. There still might be a few
problems in correctly autoconfiguring X11, so be warned that you may need to
spend some extra time to get it running. You can select Configure X11 from
menu, and select one of the presented options (configuration using xf86cfg, comand
line xf86config, repeat autoconfiguration or insert mode lines in XF86Config). If
this dosn’t help there is a shell for manual configuration.
After using IMUNES reboot the system and remember to remove the bootable CD
from your CD-ROM drive.

Notes
1. http://www.tel.fer.hr/imunes/dl/limunes-20041130.iso.gz

34
Appendix C. Installing IMUNES
IMUNES runns only under FreeBSD 4.10-RELEASE (-STABILE most probably
won’t do!).
If you don’t have FreeBSD 4.10-R installed, for all informations about installing it,
visit www.FreeBSD.org [8]

Prerequisites
The following standard FreeBSD packages are prerequisites for running IMUNES:

tcl-8.4.6,1
tk-8.4.6,1
expect-5.38.0_3
quagga-0.96.4_5
netperf-2.2.4

They can be installed by using packages or ports ([9] - for more informations on
installation using packages or ports).

Download
After ensuring all the prerequisites are installed download the files bellow.
IMUNES uses patched FreeBSD 4.10-R kernel, so in the next step you will have to
patch and rebuild krenel. Download the latest IMUNES patch to /usr/src:
4.10-R-latest.diff.gz1
And to any other folder the following files:

vimage-20040209.tgz 2
ng_pipe-20041024.tgz 3
imunes-20040916.tgz 4

Install
The downloaded kernel patch provides the ability to simultaneously maintain
multiple network stack instances within a single running kernel. For more
informations check [10].
Type on the console:

# cd /usr/src
# mkdir sys/modules/if_ve

35
 Appendix C. Installing IMUNES

# gzcat 4.10-R-20041122.diff.gz | patch

Rebuild the kernel in the usual way using your own kernel configuration file or using
LIMUNES kernel configuration file. If you want to use your own kernel
configuration file remove anything related to INET6 or IPSEC. Using LIMUNES
kernel configuration file some devices may not work properly and you may add
some additional support as long as it is not related to INET6 or IPSEC [11].
After building and installing the kernel, reboot and go to the folder containing
vimage-20040209.tgz and install vimage:

# tar -xzvf vimage-20040209.tgz

# cd vimage
# make; make install

Install ng_pipe-20041024.tgz:

# tar -xzvf ng_pipe-20041024.tgz

# cd ng_pipe
# make; make install

Install imunes-20040916.tgz

# tar -xzvf imunes-20040916.tgz

# cd imunes
# ./install.sh

Notes
1. http://www.tel.fer.hr/imunes/dl/4.10-R-latest.diff.gz
2. http://www.tel.fer.hr/imunes/dl/vimage-20040209.tgz
3. http://www.tel.fer.hr/imunes/dl/ng_pipe-20041024.tgz
4. http://www.tel.fer.hr/imunes/dl/imunes-20040916.tgz

36
Appendix D. Online resources
For now there is only one mailing list: imunes@tel.fer.hr1. For subscription visit
http://mail.tel.fer.hr/mailman/listinfo/imunes

Notes
1. mailto:imunes@tel.fer.hr
2. http://mail.tel.fer.hr/mailman/listinfo/imunes

37
Bibliography

[1] Operating System Support for Integrated Network Emulation in IMUNES1,

Marko Zec, Miljenko Mikuc, Proceedings of the 1st Workshop on Operating
System and Architectural Support for the on demand IT InfraStructure /
ASPLOS-XI, Boston, October 2004.

[2] Implementing a Clonable Network Stack in the FreeBSD Kernel2, Marko Zec,
Proceedings of the 2003. USENIX Annual Technical Conference, San
Antonio, Texas, June 2003.

[3] Quagga3 - routing model .

[4] XORP4 - The eXtensible Open Router Platform at ICSI 5.

[5] vimage functionality man pages.

[6] ng_pipe functionality man pages .

[7] CISCO6.

[8] FreeBSD site7.

[9] FreeBSD documentation of installation using packages or ports8.

[10] Simultaneously mantaining multiple network stack instances9.

[11] FreeBSD documentation on building kernel10.

Notes
1. http://tel.fer.hr/zec/papers/zec-mikuc-04.pdf
2. http://fer.hr/zec/papers/zec-03.pdf
3. http://www.quagga.net
4. http://www.xorp.org
5. http://www.icsi.berkeley.edu
6. http://www.cisco.com
7. http://www.FreeBSD.org
8. http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/ports.html
9. http://www.tel.fer.hr/zec/vimage/index.html
10. http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig-
building.html

38