IMUNES Manual

Version 1.0 21 September, 2012

Contents

1 Introduction 1.1 Document overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 User Interface Layout 2.1 Toolbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 Menubar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.1 File Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.2 Edit Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.3 Canvas Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.4 View Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.5 Tools Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3 3 4 5 5 5 6 7 7 8 9 9 9

2.2.6 Topogen Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.7 Widgets Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.8 Events Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.2.9 Experiment Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.2.10 Help Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3 Quick Intro 11

3.1 Simple Network Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.1.1 Building a simple network . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.1.2 Conguring a simple network . . . . . . . . . . . . . . . . . . . . . . . 13 3.1.3 Simulating a simple network . . . . . . . . . . . . . . . . . . . . . . . 19 3.2 Conguration les management . . . . . . . . . . . . . . . . . . . . . . . . . 22 3.2.1 Saving a virtual network conguration . . . . . . . . . . . . . . . . . . 22 3.2.2 Opening a virtual network conguration . . . . . . . . . . . . . . . . . 23 4 Advanced Usage 24

4.1 Extended Network Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 4.1.1 Canvas Management . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 4.1.2 Attaching a physical interface . . . . . . . . . . . . . . . . . . . . . . . 27 4.1.3 Attaching to a running experiment . . . . . . . . . . . . . . . . . . . . 27 4.2 Additional Conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.2.1 Custom conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.2.2 IPsec conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.3 Additional Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 4.3.1 Splitting a link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 4.3.2 Generating a network topology . . . . . . . . . . . . . . . . . . . . . . 29 1

4.3.3 IPv4 address pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 4.3.4 Routing protocol defaults . . . . . . . . . . . . . . . . . . . . . . . . . 36 4.4 Customizing Look . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 4.4.1 Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 4.4.2 Canvas background image . . . . . . . . . . . . . . . . . . . . . . . . 38 4.4.3 Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 4.5 User-congurable Event Scheduling . . . . . . . . . . . . . . . . . . . . . . . 43 4.5.1 Principle of operation . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 4.5.2 Conguring events with events editor . . . . . . . . . . . . . . . . . . . 44 4.5.3 Conguring events through conguration le . . . . . . . . . . . . . . . 46 4.6 Starting and terminating a simulation through CLI . . . . . . . . . . . . . . . . 46 4.7 Managing virtual nodes (jails) - jls, jexec . . . . . . . . . . . . . . . . . . . . . 46 4.7.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 4.8 Himage tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 4.8.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 4.9 Hcp tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 4.9.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 4.10 Example (himage and hcp) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 A Installation 50

A.1 Installation of IMUNES on FreeBSD . . . . . . . . . . . . . . . . . . . . . . . 50 A.1.1 Installing FreeBSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

A.1.2 Step by step guide through the FreeBSD installation . . . . . . . . . . 50 A.1.3 Installing the FreeBSD X11 system - GUI . . . . . . . . . . . . . . . . 51 A.1.4 Installing IMUNES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 A.1.5 Recompiling the FreeBSD kernel with VIMAGE support . . . . . . . . . 53 A.1.6 Running IMUNES on FreeBSD . . . . . . . . . . . . . . . . . . . . . . 54 A.2 Running IMUNES with VMware Player . . . . . . . . . . . . . . . . . . . . . . 54 A.2.1 Installing VMware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 A.2.2 Downloading the VMware image . . . . . . . . . . . . . . . . . . . . . 54 A.2.3 Running the VMware image . . . . . . . . . . . . . . . . . . . . . . . 54

A.3 Installation of the IMUNES GUI on Linux . . . . . . . . . . . . . . . . . . . . . 55 A.4 Installation of the IMUNES GUI on Windows . . . . . . . . . . . . . . . . . . . 56 B Troubleshooting 57

B.1 Terminating all active experiments . . . . . . . . . . . . . . . . . . . . . . . . 57 B.1.1 Cleaning up hanging ZFS mounts . . . . . . . . . . . . . . . . . . . . 57 B.2 Restoring original ZFS snapshot . . . . . . . . . . . . . . . . . . . . . . . . . 57 B.3 Obtaining kernel panic traces . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 C IMUNES network conguration le 59

Introduction

IMUNES is an Integrated Multiprotocol Network Emulator / Simulator of IP based networks. Virtual nodes in IMUNES are multiple network stack instances that are formed through special FreeBSD kernel modications. Virtual nodes can be linked either with other virtual nodes or with the physical network interface through simulated links. All virtual nodes share a single place for their application binaries and libraries. The main strengths of this tool are high scalability, performance and delity.

1.1

Document overview
This document is intended to be a manual for users that are getting started with IMUNES, likewise for the ones that want to know more about its advanced features. This manual is divided into three main parts: User Interface Layout, Quick Intro and Advanced Usage. The rst part, User Interface Layout, gives detailed description of IMUNES graphical user interface. The second part, Quick Intro, is intended to prepare beginners to get a working network simulation in a short time. It gives detailed explanations for building, conguring and simulating a simple network. At the end it gives instructions related to IMUNES conguration les. The third part, Advanced Usage, gives instructions for extending the network topology built in the rst section. It also explains the usage of additional tools and conguration possibilities. It proceeds with features for customizing look, such as annotations, background image and icon size. At the end it gives instructions related to event scheduling, starting and terminating simulation through command-line interface and himage command.

User Interface Layout

IMUNES can be used either through the simple Tcl/Tk based graphical user interface (GUI) or through the command line interface (CLI). We will run IMUNES on FreeBSD with some kind of X11 window manager and explain the main GUI components. If X11 is not running you can start it using startx command. To run IMUNES GUI use imunes command. IMUNES GUI is a simple Tcl/Tk based management console, allowing specication and management of virtual network topologies. Its main parts are the work space in the middle, called canvas, the menubar on the top, the toolbox on the left side and the statusbar at the bottom (Figure 2.1)

Figure 2.1: IMUNES GUI

The default working mode after the initial start (or after creating a new virtual network conguration le with the File New option from the menubar) is edit mode. The edit mode is used to build and congure network topologies, contrary to the execute mode whose purpose is the network simulation. The network simulation will be explained later in the Section 3.1.3.

2.1. Toolbox

2. User Interface Layout

2.1

Toolbox
The toolbox, placed on the left side of the GUI, contains tools for building network topologies and tools for adding annotations (Figure 2.2). These tools are all available in the edit mode. In the execute mode these tools, except the Select tool, are shaded and can not be used.

Figure 2.2: Toolbox tools

Each toolbox item shown in Figure 2.2, from left to right, is described below. Selecting elements:

Select tool - The default tool for selecting and moving elements.
Building the network topology:

Link - Tool that is used to create network links between nodes. Hub - The link layer element that forwards every incoming packet to all of its ports and, thus, to every connected node. LAN switch - The link layer element that forwards incoming packets to connected nodes using the table of destination addresses and its ports. Router - The network layer element that is capable of packet forwarding using the routes obtained by dynamic routing protocols (available through quagga or xorp by default installation or any other standard FreeBSD routing daemon). Host - The network layer element that does not forward packets and has static routes. It starts standard network services, via portmap and inetd. PC - The network layer element that also does not forward packets and has static routes. Unlike host, it does not start any network services. Physical interface (RJ45) - Tool that provides the possibility to connect a virtual node with the physical interface.
Adding annotations:

Text - Tool for adding a new text on the canvas. Oval - Tool for adding a new oval on the canvas. Rectangle - Tool for adding a new rectangle on the canvas.

2.2

Menubar
The menubar consists of menus that provide access to various functions (Figure 2.3). Some options from the menubar are automatically disabled in the execute mode.

Figure 2.3: Menubar

2.2.1

File Menu
The File menu contains options for conguration les management (Figure 2.4).

2.2. Menubar

2. User Interface Layout

Figure 2.4: File menu

New - Create a new virtual network conguration le. Open - Open an existing IMUNES network conguration le (.imn) by selecting it from the invoked File Open dialog. Save, Save As - Save the current virtual network topology in IMUNES network conguration le format (.imn). Print - Print the current canvas using Tcl/Tk PostScript and send it through the pipe to the default printing command (lpr ) (that can also be changed, (e.g > lename)). Print to le - Print all canvases to PDF or PostScript le. Close - Close the virtual network conguration le. NOTE: If the experiment is not explicitly terminated it remains running. Quit - Exit the IMUNES GUI. Recently used les - A list of recently used les. Clicking on one of the les opens that conguration le.

2.2.2

Edit Menu
The Edit menu contains options for handling elements on the canvas.

Figure 2.5: Edit menu

Undo - Undo the last change on the canvas reverting it to an older state. Redo - Reverse the undo command. Cut, Copy, Paste - Cut or copy elements from source and paste them to destination. Select all - Select a whole network topology. Select adjacent - Select nodes connected to the selected node(s). This feature is also available through the node menu.

2.2. Menubar

2. User Interface Layout

2.2.3

Canvas Menu
The Canvas menu contains options for canvas management.

Figure 2.6: Canvas menu

New - Create a new empty canvas. Rename - Rename the current canvas through the invoked dialog. Delete - Delete the current canvas. Resize - Resize the current canvas through the invoked dialog. Background image - Change background on the current canvas (see Section 4.4.2). Previous, Next, First, Last - Switch between available canvases.

2.2.4

View Menu
The View menu contains options for showing / hiding links and nodes parameters on the canvas, options for changing icon size, zooming options, etc.

Figure 2.7: View menu

Icon size - Change the size (normal or small) of all network elements (see Section 4.4.3).
7

2.2. Menubar

2. User Interface Layout

Show [network element parameter] - Show or hide information such as interface names, IPv4/IPv6 addresses, etc. These options are usually saved in the .imn les, providing consistent look of scenarios running on different computers. Show IPsec Cong - Show or hide information about IPsec conguration in the conguration window of network layer elements. Show ZFS snapshots - Show or hide the conguration of different virtual images from network layer nodes. Show Topology Tree - Show or hide the tree with a list of all network topology elements. Show Background Image - Show or hide background image. Show Annotations - Show or hide annotations (text, oval, rectangle). Show Grid - Show or hide grid. Zoom In, Zoom Out - Magnify (Zoom In) or reduce (Zoom Out ) the size of the display. Themes - Choose one of the themes from the submenu. Each theme represents a collection of styles, where a style describes the appearance (or appearances) of a Ttk widget class.

2.2.5

Tools Menu
The Tools menu contains the network topology management tools.

Figure 2.8: Tools menu

Auto rearrange all - Automatically rearrange position of all network elements on canvas. Auto rearrange selected - Automatically rearrange position of the selected group of network elements. Align to grid - Arrange all network elements on canvas aligning them to grid. Randomize MAC bytes - Randomizes the 4th and 5th byte of the automatically generated MAC address. IPv4 address pool - Set variable-mask IPv4 address pool through the invoked dialog in order to replace default 10.0.0.0/24 address pool (see Section 4.3.3). This will be applied to all the subsequentially created network layer elements. Routing protocol defaults - Set the routing protocol defaults (routing model and protocols) through the invoked dialog (see Section 4.3.4). This will be applied to all selected routers (if any) at the time of change, as well as to all the subsequentially created ones. ns2 imunes converter - Convert a le from ns2 network conguration le format to IMUNES network conguration le format (.imn)

2.2. Menubar

2. User Interface Layout

2.2.6

Topogen Menu
The TopoGen menu contains options for simple and fast specication of various network topologies (see Section 4.3.2).

Figure 2.9: Topogen menu

2.2.7

Widgets Menu
The Widgets menu contains options for displaying information about the virtual network.

Figure 2.10: Widgets menu

None - Do not show any information about the virtual network. ifcong - Show network interfaces parameters. To see these parameters, place the mouse pointer on the virtual node. Routing table - Show the routing table. To see the routing table, place the mouse pointer on the virtual node. Custom... - Allows the specication of the command that will be executed inside a virtual node. The result of the command will be displayed inside the widget. Route - Show the route from the node x to the node y. To see the route, click on the node x and then place the mouse pointer on the node y.

2.2.8

Events Menu
The Events menu - This menu is used to congure event scheduling.

Figure 2.11: Events menu

Start scheduling - Start the scheduling of events. Stop scheduling - Stop the scheduling of events.
9

2.2. Menubar

2. User Interface Layout

Event editor - Schedule events on the links through the opened editor.

2.2.9

Experiment Menu
The Experiment menu is used to start and terminate an experiment. It also enables to attach to a running experiment.

Figure 2.12: Experiment menu

Execute - Start an experiment and switch to the execute mode. In the process of starting an experiment, IMUNES creates and congures the virtual network. All events during that process will be shown in the statusbar. Terminate - Terminate an experiment and switch to the edit mode. During the termination process, IMUNES will shut down all network elements and it will terminate active services on each node. The termination is nished when the message about the successful cleanup shows up in the statusbar. Attach to experiment - This option opens opens a window with the list of running experiments on the current computer. It allows to resume running experiments that are shown in the Attach to experiment window shown in Figure 4.9.

2.2.10

Help Menu
The Help menu contains the option About that invokes the About dialog box for viewing version information.

Figure 2.13: Help menu

10

Quick Intro

3.1

Simple Network Scenario

In this section we will show how to build, congure and simulate the following simple network topology: Personal computers (ofce-pc1 and ofce-pc2 ) from the network 192.168.1.0/24 are connected to the LAN switch (ofce-switch) which is connected to the router (ofce-router ). The server (ofce-host ) from the network 192.168.2.0/24 is directly connected to the router (ofce-router ). Personal computers from the rst network have route only to the network 192.168.2.0/24. The server from the second network has the default route. Quagga routing is enabled on the router in order to be able to serve and receive dynamic route updates.

3.1.1

Building a simple network

After running IMUNES on FreeBSD with some kind of X11 window manager (see Section 2), we will build previously described network using tools from the toolbox (see Section 2.1).

Adding and deleting network elements

To draw a node click on the corresponding node tool and then click on the work space to place it. To connect nodes click on the Link tool, then click and hold on the source node and go to the destination node. Now draw a router, a host, a LAN switch and two PCs. Using the Link tool connect the LAN switch to the router and then connect each PC to the LAN switch. Connect the host directly to the router. The created network topology should look like the one in Figure 3.1.

11

3.1. Simple Network Scenario

3. Quick Intro

Figure 3.1: Simple network topology

When nodes are connected with the Link tool (the direction does not matter), the source node, the destination node and the link get precongured parameters automatically. When a node or a link is selected, some of the congured parameters are shown on the left side of the statusbar placed at the bottom of the window (Figure 3.2).

Figure 3.2: Node parameters in the statusbar

Some of the parameters can be visible on the canvas: interface names (link layer: e0, e1, e2 and network layer: eth0, eth1), IPv4/IPv6 addresses of network layer elements (PC, host, router), node names (n0, n1, n2, n3, n4) and link labels (e.g bandwidth). You can manipulate with the visibility of nodes and links parameters from the View menu (Figure 3.3). In this simple scenario we do not want for IPv6 addresses to be visible, so we will turn the Show IPv6 Addresses option off.

Figure 3.3: Show or hide nodes and links parameters

12

3.1. Simple Network Scenario

3. Quick Intro

To delete the network element select it using the Select tool and then use the Delete keyboard button. You can also delete it by making a right click on it and making a left click on the Delete label in the popped up menu. The node deletion is automatically followed by the deletion of associated links.

Rearranging network elements

You can change position of the network element (node or link) and/or the node name. To move both the network element and its name select the network element with the Select tool and drag it to the designated position. To move only the node name select it with the Select tool and drag it to the designated position. Using the Select tool you can also move around a group of connected nodes which can be selected using the Ctrl keyboard button in addition to the left click. To select the whole network topology use Select All option from the Edit menu. For automatic rearranging of all network elements or rearranging the selected group of network elements use Rearrange and Rearrange All options from the Tools menu. To stop the rearranging process click with the Select tool.

3.1.2

Conguring a simple network

Although precongured parameters of network elements are usually sufcient to start a simulation (automatically provided IPv4/IPv6 addresses, the default static route on the PC and the host and routing model and protocols parameters on the router as well), in this scenario we will set up our own parameters. To open the network element conguration window:

make a right click on the network element and select the Congure label from the popped up menu (Figure 3.4)
or

make a double click on the network element

Figure 3.4: Congure a network element

Network elements conguration parameters can be also changed through the topology tree. To show the topology tree turn on the Show Topology Tree option from the View menu. The tree with a list of network topology elements (nodes and links) will be shown on the right side of the window (Figure 3.5). To open the network element conguration window make a double click or use the Enter keyboard button on node, interface or link label in the topology tree.

13

3.1. Simple Network Scenario

3. Quick Intro

Figure 3.5: Changing conguration parameters through the topology tree

Depending on the type of a network element, there are four types of conguration windows:

a hub/LAN switch conguration window a PC/host conguration window a router conguration window a link conguration window

Hub/LAN switch conguration window

The hub/LAN switch conguration window, as well as the conguration windows of other node types, contains a node name eld. Besides that it contains only link layer interface parameters. We will change the LAN switch name and data packet scheduling method (from precongured First In First Out (FIFO) data packet scheduling method to Weighted Fair Queuing (WFQ) method). Change the node name to ofce-switch. To change data packet scheduling method select the link layer interface e0 from the list of interfaces, choose WFQ option from the Queue menu and click on the Apply button (Figure 3.6).

14

3.1. Simple Network Scenario

3. Quick Intro

Figure 3.6: LAN switch conguration window

Packet scheduling method is now applied and you can see new queuing discipline for interface e0 in the column Queue disc (Figure 3.7).

Figure 3.7: LAN switch conguration window with applied changes

Repeat the same procedure for the other link layer interfaces. Changed conguration is already applied so you can close the conguration window with the Cancel button but you can also use the Apply and Close button.

PC/host conguration window

The PC/host conguration window consists of three subwindows. Each of them is associated with one of the following tabs: Conguration, Interfaces and IPsec (Figure 3.8).

Figure 3.8: Tabs in the PC/hub conguration window

Besides a node name eld, PC/host conguration window contains routing parameters and custom conguration parameters (in the window associated with the Conguration tab), net15

3.1. Simple Network Scenario

3. Quick Intro

work interface parameters (in the window associated with the Interfaces tab) and IPsec parameters (in the window associated with the IPsec tab). We will change the node name, network interface parameters and routing parameters. Change the host node name to ofce-host and PC node names to ofce-pc1 and ofcepc2. To change IPv4 address make a left click on the Interfaces tab, select interface eth0 from the list of interfaces, change the IPv4 address eld and click on the Apply button (Figure 3.9). We will change the host IPv4 address eld to 192.168.2.5/24 (now it belongs to 192.168.2.0/24) and PC IPv4 address elds to 192.168.1.5/24 and 192.168.1.7/24 (now they belong to network 192.168.1.0/24). IP address elds require the CIDR notation, so the IPv4 address is followed by a slash and a network length.

Figure 3.9: Changing IPv4 address

Static routes PC and host both use static routing. The precongured routing table contains only the default route. Every static route, as well as the default route, consists of: 1. the destination network: an IP address which is followed by a slash and a network prex and 2. the next hop network interface IP address (which is an IP address without a slash and without a network prex). If the route syntax is wrong, that route will be silently ignored. We will add the static route on ofce-pc1 and ofce-pc2 for the network 192.168.2.0/24 through the gateway 192.168.1.1 (Figure 3.10).

Figure 3.10: Adding the static route on the PC

16

3.1. Simple Network Scenario

3. Quick Intro

On ofce-host we will change default gateway address to 192.168.2.1 (Figure 3.11).

Figure 3.11: Adding the static route on the PC

IPv6 addresses and default routes (placed below IPv4 addresses and routes) can be deleted. To apply the changed conguration and close the conguration window click on the Apply and Close button.

Router conguration window

The router conguration window, in addition to elds from PC/host conguration window, contains the part for choosing the routing model and protocols. We will only change the node name and network interface parameters. Change the node name to ofce-router and IPv4 addresses on both network interfaces: 192.168.1.1/24 on the network interface eth0 and 192.168.2.1/24 on the network interface eth1. Routing models and protocols There are three possible routing models: 1. the xorp model (eXtensible Open Router Platform) 2. the quagga model 3. the static model In the case of xorp and quagga routing models there are options for enabling/disabling RIP, RIPng, OSPFv2 and OSPFv3. By default, all new quagga or xorp router instances will have both RIPv2 and RIPng enabled. The defaults can be changed with the Tools Routing protocol defaults option from the menubar, which will be applied to all selected routers (if any) at the time of change, as well as to all the subsequentially created ones (see Section 4.3.4). In the case of static routing model router uses routes from the static routes eld that has the same syntax as the static routes eld in the PC/host conguration window. We will leave the default router model - quagga with RIP and RIPng protocols enabled, OSPFv2 and OSPFv3 protocols are disabled (Figure 3.12).

Figure 3.12: Routing models and protocols

Link conguration window

The link conguration window offers the possibility to congure the link bandwidth (between 0 and 109 bps), the propagation delay (between 0 and 107 s), the probability of a bit error 17

3.1. Simple Network Scenario

3. Quick Intro

rate (between 0 and 10-12 ) and the probability of package duplication (between 0 and 50%). There are also display properties: the link width (line thickness between 1 and 8) and the link color (red, green, blue, yellow, magenta, cyan or black).

Figure 3.13: Link conguration window

Default values are as follows: the link which transmits packets without errors and without any possibility for the packet duplication with the unlimited link bandwidth and the zero propagation delay. The link width is set to value 2 and the link color is red. We will leave default values on all links except on the link between ofce-switch and ofcerouter (Figure 3.14). On that link we will set up the delay of 30 s. Delay will be tested during the network simulation with the traceroute tool (see Section 3.1.3).

Congured network topology

Congured network topology should look like the one in Figure 3.14.

18

3.1. Simple Network Scenario

3. Quick Intro

Figure 3.14: Congured network topology

3.1.3

Simulating a simple network Starting an experiment

After the network topology is completely built and properly congured, we will start an experiment with the Experiment Execute option from the menubar and IMUNES will switch from the edit mode to the execute mode. In the process of starting an experiment, IMUNES creates and congures the virtual network. That will take a few seconds and all events during that process will be shown in the statusbar placed at the bottom of the window. NOTE: Although you can draw network topology on any system that supports Tcl/Tk (Linux, FreeBSD, Windows, Mac OS X, Solaris), an experiment can only be started on FreeBSD operating system with root permissions (Figure 3.15 and Figure 3.16)!.

Figure 3.15: Starting an experiment in Windows

19

3.1. Simple Network Scenario

3. Quick Intro

Figure 3.16: Starting an experiment in FreeBSD without root permissions

In addition to congured parameters, each node will be set with the loop back interface, a router will have the kernel forwarding enabled, while on a host portmap and inetd will be started. Information about the time spent instantiating the network topology is shown in the statusbar (Figure 3.17).

Figure 3.17: Message about the instantiation of the network topology

In the right corner of the statusbar you can also see that IMUNES now works in the execute mode.

Options from the node and the link menu

To open the node menu in the execute mode use the right click on the node. Note that the menu in the execute mode is different from the menu in the edit mode. It offers the possibility to open the shell window (X terminal with a Unix shell), Wireshark network sniffer and Opera browser or to Stop / Start the network element. It is also possible to select the node connected to this node (Select adjacent ) and to change node icon(Node icon).

Figure 3.18: Network-layer node menu in the execute mode

Note that both the node and the link menu in the execute menu offer the possibility to open the conguration window (Congure label). From the node conguration window in the execute mode it is possible to change only the node name. Other node parameters such as link layer interface parameters, network interface parameters and routing parameters can be changed from shell window on each node. To change those parameters from the node conguration window stop the node (using the Stop label), change parameters and then again start the node (using the Start label).

20

3.1. Simple Network Scenario

3. Quick Intro

On the other side, from the link conguration window in the execute mode it is possible to change the following link parameters: link bandwidth, the propagation delay, the probability of a bit error rate and the probability of package duplication. It is also possible to change display properties: the link width and the link color. We will now check if the virtual network topology is properly congured. Open the shell window (e.g /bin/sh) on the network element (e.g ofce-pc1).

To check the network interface eth0 parameters type the following command: ifconfig eth0. The result is shown in Figure 3.19.

Figure 3.19: Shell window on ofce-pc1, network interface parameters

To check static routes type the following command: netstat -nrf inet. The result is shown in Figure 3.20.

Figure 3.20: Shell window on ofce-pc1, static routes

To test if a particular network element is reachable (e.g ofce-host ) type the following command: ping 192.168.2.5. The result is shown in Figure 3.21. To stop transmitting packets press Control-C keyboard button.

Figure 3.21: Shell window on ofce-pc1, pinging ofce-host

We will test delay on the link between ofce-switch and ofce-router, which is set to 30 s using the traceroute tool:

In the shell window on ofce-pc1 type the following command: traceroute 192.168.1.1. The result is shown in Figure 3.22.

21

3.2. Conguration les management

3. Quick Intro

Figure 3.22: Shell window on ofce-pc1, traceroute to ofce-router

In the shell window on ofce-host type the following command: traceroute 192.168.2.1. The result is shown in Figure 3.23.

Figure 3.23: Shell window on ofce-host, traceroute to ofce-router

Terminating an experiment
To terminate an experiment and switch from the execute mode to the edit mode use the Experiment Execute option from the menubar. During the termination process, IMUNES will terminate active services on each node and shut down all network elements (links and nodes with both virtual and physical interfaces). The termination is nished when the message about the successful cleanup shows up in the statusbar (Figure 3.24).

Figure 3.24: Message about the successful cleanup

3.2
3.2.1

Conguration les management

Saving a virtual network conguration
After the virtual network is successfully built, congured and tested, it can be saved with File Save or File Save As options from the menubar. The virtual network topology is saved in IMUNES network conguration le format (.imn).

Figure 3.25: File Save dialog

The structure of the conguration le is simple and suitable for changing with a text editor (see Appendix C). 22

3.2. Conguration les management

3. Quick Intro

3.2.2

Opening a virtual network conguration

To open an existing IMUNES network conguration le use the File Open option from the menubar and select it from the invoked File Open dialog.

Figure 3.26: File Open dialog

The other way to open an imn le is to start IMUNES with that le as an argument: imunes

simple-topology.imn

23

Advanced Usage

4.1

Extended Network Scenario

In this section we will show how to extend the simple network topology (see Section 3.1). We will explain the additional possibilities of building and conguring the extended network scenario: The simple network topology is placed in the ofce-canvas while the additional elements are placed in the roadwarrior-canvas. The roadwarrior-canvas consists of a router (roadwarriorrouter ), a PC (roadwarrior ) and a physical interface. The roadwarrior-router is connected to the ofce-router on the ofce-canvas through the 192.168.3.0/24 network, the PC is in the 161.53.19.0/24 network whereas the physical interface is in the 161.53.20.0/24 network. We will now extend the simple network from the last chapter by adding the roadwarriorrouter, roadwarrior and the physical interface all placed on another canvas. To open an existing IMUNES network conguration le use File Open from the menubar or start IMUNES with the imn le as an argument: imunes simple-network.imn. Check that you are in the edit mode. If not, switch with Experiment Terminate.

4.1.1

Canvas Management
To facilitate building of complex and large network topologies IMUNES lets you divide the network topology into a set of network layers. These network layers are called canvases. Canvas management consists of two main elements:

Canvas menu in the menubar (Figure 2.6) List of canvas tabs at the bottom of the main window, above the statusbar (Figure 4.1)

Figure 4.1: Canvas Tabs

To add a new canvas use the Canvas New option from the menubar or double click on the empty space in the canvas tabs list at the bottom of the window. You can rename the canvas with the Canvas Rename option from the menubar or double click on the canvas tab in the canvas tabs list. (Figure 4.2) Similarly the Canvas Delete option deletes the active canvas.

Figure 4.2: Canvas rename dialog

There is also the option Canvas Resize that allows you to dene a custom canvas size in pixels. The default canvas size is 900*620 pixels. (Figure 4.3)

24

4.1. Extended Network Scenario

4. Advanced Usage

Figure 4.3: Canvas resize dialog

Canvas selection can be done with the options from the Canvas menu (Previous, Next, First, Last ) or simply by clicking the tab with the canvas name on it. Rename the existing canvas Canvas0 into ofce-canvas. Add a new canvas, rename it into roadwarrior-canvas and select it as the active canvas. This canvas is empty so we will add a router by selecting the router tool and clicking on the empty canvas. Rename this router into roadwarrior-router. Switch to the ofce-canvas. Now we will connect the ofce-router and the roadwarrior-router.To do that, right click on the ofce-router and select Create link to roadwarrior-canvas roadwarrior-router option (Figure 4.4) from the popped up menu. This will create a link between roadwarrior-router and ofce-router.

Figure 4.4: Create link to

On the ofce-router set the eth2 interface IPv4 address to 192.168.3.1/24. On the roadwarrior-router set the eth0 interface IPv4 address to 192.168.3.2/24. We will add another PC to the roadwarrior-canvas, name it roadwarrior and connect it with the roadwarriorrouter. On the roadwarrior set the eth0 IPv4 address to 161.53.19.100/24. On the roadwarrior-router set the eth1 IPv4 address to 161.53.19.1/24. The roadwarrior-router uses the same dynamic routing model (quagga) as the ofce-router and we do not need to congure anything else on the router. The roadwarrior uses static routes and we will need to change the default route gateway in static routes eld of the roadwarrior conguration window to 0.0.0.0/0 161.53.19.1. Finally, the congured network topology should look like the following (Figure 4.5 and Figure 4.6):

25

4.1. Extended Network Scenario

4. Advanced Usage

Figure 4.5: ofce-canvas

Figure 4.6: roadwarrior-canvas

26

4.1. Extended Network Scenario

4. Advanced Usage

Both the roadwarrior and roadwarrior-router can be easily moved from roadwarrior-canvas to ofce-canvas with the Move To ofce-canvas from the node menu. The link between roadwarrior-router and ofce-router, as well as any other link, can be deleted with the Delete option from the Link menu. To open the link menu, use the right click on the link and choose the Delete option. When we are done with network conguration, we can start the experiment with Experiment Execute from the menubar. We can now check that the roadwarrior can ping both networks (192.168.1.0/24, 192.168.2.0/24) and additionally, that the network 192.168.1.0/24 does not have an access to the roadwarrior, but it has access to the 192.168.2.0/24 network.

4.1.2

Attaching a physical interface

The Physical interface tool from the toolbox provides the possibility to attach a physical interface to a virtual node. This way the virtual network is able to communicate with nodes from the external network. We will now add the physical interface to the roadwarrior-canvas. To add a physical interface to the canvas select the Physical interface tool and click on the canvas. Physical interface nodes can be connected either with the LAN switch or the router. Connect the newly created physical interface with virtual node roadwarrior-router using the Link tool from the toolbox or the Create link to option from the node menu. The newly created physical interface node is unassigned and in the node name eld it contains UNASSIGNED. Open the physical interface conguration window with a double click or make a right click on it and select the Congure option. Fill the Physical interface eld with the name of the designated physical interface, e.g. eth0, obtained from ifconfig -a command ran on the physical machine (outside IMUNES). (Figure 4.7) The name of the physical interface will appear in the node name label. (Figure 4.8)

Figure 4.7: Physical interface confgiuration dialog

Figure 4.8: Physical interface node label

Check that roadwarrior-router has a properly congured IP address on the network interface connected to the physical interface. Additionally, check that routes which route packets between virtual network and the external network through the physical interface exist in both the external network and in the virtual network (on roadwarrior-router ). Save this conguration to a new le by selecting the Save as option from the File menu. Name the le extended-topology.imn.

4.1.3

Attaching to a running experiment

IMUNES gives you the possibility to run multiple independent experiments on one physical computer. Therefor we added the possibility of attaching to running experiments through the IMUNES GUI. In the Experiment menu select the option Attach to experiment. A dialog similar to 4.9 is opened. Here you can select on which experiment you would like to attach. 27

4.2. Additional Conguration

4. Advanced Usage

You can attach to all experiments, those that were started using batch mode and those that were executed from the GUI. The window shows the following experiment parameters:

Experiment ID Filename of the topology Time when the experiment was started. Experiment screenshot (only if it was started through the GUI)
To attach to the you can double-click its entry or use the Resume selected experiment button.

Figure 4.9: Attach to experiment window

4.2
4.2.1

Additional Conguration
Custom conguration
The conguration window of each network layer node (PC, host and router) has also the Custom startup conguration eld. The current startup conguration is generated with the Generate button. In order to view or edit the generated startup conguration click on the Edit button. In case of a PC, host or router with the static routing model, the default conguration consists of ifcong and route commands. NOTE: After starting the network simulation, the new/custom conguration will be considered only if Custom startup conguration is enabled. This is done by selecting the enabled radiobutton in the Custom startup conguration eld.

4.2.2

IPsec conguration
In the conguration window of the network layer elements (router, host and PC) you can also congure parameters referring to the IPsec protocol. When you open the conguration window, beside other tabs, youll see the IPsec tab (Figure 4.10). With the Add SA/SP button you can add a new Security Association/Security Policy. You can also edit an existing SA/SP by selecting it from the list of saved SAs/SPs.

28

4.3. Additional Tools

4. Advanced Usage

Figure 4.10: IPsec conguration

Through this dialog only manual IPsec conguration is possible. It is disabled by default. All IPsec conguration parameters are written to the setkey.conf le. If there happen to be some syntax errors in the setkey.conf le, it will be shown in the error window after starting the experiment.

4.3
4.3.1

Additional Tools
Splitting a link
Links can be split in two separate parts and each part can change its position after selecting it with the Select tool. Make a right click on the link and than make a left click on the Split label in the popped up menu to split the link in two halves. Separated link parts can be merged back with the Merge option from the link menu. This feature is shown in Figure 4.11.

Figure 4.11: Split link

4.3.2

Generating a network topology

TopoGen menu from the menubar enables easier and faster generation of network topologies (Figure 4.12). This function can be used to generate following topologies: Chain, Star, Cycle, Wheel, Cube, Clique, Bipartite or Random.

29

4.3. Additional Tools

4. Advanced Usage

Figure 4.12: TopoGen menu

Some examples can be seen in Figure 4.13, Figure 4.14 and Figure 4.15. In order to generate a topology rst select the network layer nodes (router, host or PC) from the toolbox and then the desired topology type e.g. bipartite graph K(2,3) (see Figure 4.14).

Figure 4.13: Star topology

30

4.3. Additional Tools

4. Advanced Usage

Figure 4.14: Bipartite topology

Figure 4.15: Wheel topology

31

4.3. Additional Tools

4. Advanced Usage

In case of random topology an additional information is needed, so beside the number of the nodes it is also necessary to specify the number of links. The nodes in the random topology will be randomly connected with the number of links specied before. An example of generating a random topology: 1. Select the router tool from the toolbox. 2. Choose the random topology: TopoGen Random 3. Choose the desired number of nodes and links e.g. n = 6; m = 5, where n is the number of nodes and m the number of links in the generated network topology (Random R(6,m) R(6,5)). The result is shown in Figure 4.16.

Figure 4.16: Random topology

Using the TopoGen tool you can generate topologies containing one type of node (router, host or PC). In that case new nodes of the same type are created and placed on the canvas. Another option is to add new nodes to canvas and then connect them using the topology generator: 1. Add nodes to the canvas (dont have to be same type). 2. Select nodes that should be included in the new topology 3. Make a right click on one of the selected nodes and choose the option Create Link to from the menu. Then choose the option Selected and select one of the offered topologies (Chain, Star, Cycle, Clique or Random). An example is shown in Figure 4.17.

32

4.3. Additional Tools

4. Advanced Usage

Figure 4.17: Example of creating a network topology with existing nodes

33

4.3. Additional Tools

4. Advanced Usage

4.3.3

IPv4 address pool

IPv4 address pool option from the Tools menu is used for replacing default 10.0.0.0/24 address pool. Choosing that option invokes a dialog shown in Figure 4.18.

Figure 4.18: IPv4 address pool dialog

In order to replace default 10.0.0.0/24 address pool set variable-mask IPv4 address pool through the invoked dialog. CIDR notation is required, so the IPv4 address needs to be followed by a slash and a network length. To apply changes click on the Apply button. The given address pool will be applied to all the subsequentially created network layer elements (Figure 4.19).

Figure 4.19: IPv4 address pool example

In order to apply the given address pool to selected elements, make a right click on the network layer element and choose the option IPv4 autorenumber from the popped up menu. In example shown in Figure 4.20 we have set IPv4 address pool to 160.153.1.1/24, selected all network elements and selected the option IPv4 autorenumber from the node menu to apply the given address pool to selected elements.

34

4.3. Additional Tools

4. Advanced Usage

Figure 4.20: IPv4 autorenumber example

35

4.4. Customizing Look

4. Advanced Usage

4.3.4

Routing protocol defaults

In the Tools menu you can nd the Routing protocol defaults option. Selecting this option invokes a popup window shown in Figure 4.21. Just to remind you, settings referring to routing protocols can be also changed in the router conguration window. The difference is that changes made there are applied only to the router that is being congured. This tool in contrary makes it possible to apply changes to one or more selected routers. If there is no router selected than the changes will be applied to subsequentially created routers. Note that this option will be disabled when the experiment starts.

Figure 4.21: Router defaults window

4.4
4.4.1

Customizing Look
Annotations
To emphasize some parts of the network topology you can add various graphic elements to the canvas. These elements are divided into three groups:

Text Oval Rectangle

Each of these elements have their own tools in the toolbox: Text tool (Figure 4.22), Oval tool (Figure 4.23) and Rectangle tool (Figure 4.24).

Figure 4.22: Text tool

Figure 4.23: Oval tool

Figure 4.24: Rectangle tool

To add an annotation to the canvas, select the appropriate tool and click where you want to add the annotation. A popup window will be shown. There you can dene how will the annotation look. When created, annotations can be moved around on the canvas. This is done by using the select tool. Click on the annotation and then drag it to its destination. 36

4.4. Customizing Look

4. Advanced Usage

Text
The text annotation lets you dene the following options(Figure 4.25):

Font - which system font, size and style you want to use Text color - color of the text in RGB values

Figure 4.25: Text conguration window

Oval
Both the oval and the rectangle annotation include the text option, explained in the previous paragraph. Whereas the text size is dened in the text conguration window, the size of the oval annotation is dened by dragging the cursor on the canvas while keeping the left mouse button pressed. When the annotation size seems to be ne, release the mouse button. The oval conguration window will popup (Figure 4.26). The oval annotation lets you dene the following additional options(Figure 4.26):

Fill color - color of the annotation ll in RGB values. Border color - color of the annotation border in RGB values. Border width - width of the annotation border.

Figure 4.26: Oval conguration window

Rectangle
The rectangle conguration window has the same options as the oval conguration window. The rectangle size is dened the same way as the size of the oval. The rectangle annotation lets you dene the following additional options (Figure 4.27):

Radius of the bend at the corners - denes roundness of the rectangle edges.

37

4.4. Customizing Look

4. Advanced Usage

Figure 4.27: Rectangle conguration window

We will now show the usage of annotations on the le simple-topology.imn (Figure 4.28.

Figure 4.28: Annotations example

4.4.2

Canvas background image

The options for changing the canvas background image are accessible through the Canvas and View menu and through the menu that is opened with a right click on the empty canvas (Figure 2.6 and Figure 4.29).

Figure 4.29: Background image menu

38

4.4. Customizing Look

4. Advanced Usage

All options related to the canvas background are accessible in the Background image menu (Figure 4.29):

Show background - Show or hide the canvas background. Change background - Opens the Change canvas background window (Figure 4.30). Remove background - Removes the background from the current canvas. Set background from - Sets the background from an another canvas.
To set a canvas background you need to open the Change canvas background window (Figure 4.30).

Figure 4.30: Change canvas background

This window is divided into two main parts:

Left pane with the canvas background options

Field and button for choosing the background image Image setting options Image alignment options Additional information if imagemagick is not present (Figure 4.31)

Right pane with canvas and image information and preview

Canvas size information Image preview Image size information

Figure 4.31: Warning if ImageMagick is not present

When the image is selected there are four image setting modes that can be chosen:

Use original/cropped image - If the image is smaller it will be placed in the position
39

4.4. Customizing Look

4. Advanced Usage

dened by the image alignment. If the image is larger it will be cropped. The image alignment will dene which part of the image will be taken as the background.

Stretch/shrink image - If the image is smaller it will be stretched without changing the proportions. If the image is larger it will be shrunk without changing the proportions. The image alignment will dene which part of the image will be taken as the background. Adjust canvas to image - The canvas will be resized to the image size and then the background image will be set. Adjust image to canvas - The image will be forcibly resized to the canvas size with changed proportions if needed.

Settings canvas background images

We will use the extended topology example (extended-topology.imn) to set canvas background images. On the ofce-canvas we will set a background image. Then we will go to the roadwarrior-canvas and set that same image using the Set background from ofcecanvas option (Figure 4.32).

Figure 4.32: Set background from menu

The nal result is shown in Figure 4.33 and Figure 4.34.

Figure 4.33: Canvas background example on ofce-canvas

40

4.4. Customizing Look

4. Advanced Usage

Figure 4.34: Canvas background example on roadwarrior-canvas

4.4.3

Icons
IMUNES lets you choose custom node icons. First select the nodes whose icons you want to change. Then right click on the selection and then go to the Node icon Change node icons option (Figure 4.35). This menu has also the Set default icons option that sets the default node icon for the selected icons.

Figure 4.35: Node icon menu

The Change node icons option opens the Set custom icon window (Figure 4.36).

41

4.4. Customizing Look

4. Advanced Usage

Figure 4.36: Set custom icon

This window is divided into two main parts (Figure 4.36):

Left pane with for choosing custom icons

List of library and custom icons on the top. Every icon that has been used or is being used in the project will be available at the end of the list, and will be given a generic name (e.g. img0, img5). Field and button for choosing the custom icon

Right pane with the icon preview and icon size information
We will now open the extended-topology.imn le and set a custom icon. We will choose the library icon iprewall.gif for the roadwarrior-router. The nal result is shown on Figure 4.37.

Figure 4.37: Changed roadwarrior-router icon

42

4.5. User-congurable Event Scheduling

4. Advanced Usage

Icon size
If you want to emphasize the information about nodes, interfaces and links instead of node icons you can change the icon size through the View Icon size option (Figure 4.38).

Figure 4.38: Icon size menu

Lets take the simple-topology.imn example and set the icon size to small. (Figure 4.39) Currently, only two sizes are available, normal and small. Otherwise, custom icons can be used.

Figure 4.39: Icon size example

4.5

User-congurable Event Scheduling

This section describes a feature for scheduling of arbitrary deterministic and stochastic events during experiment execution.

4.5.1

Principle of operation
The control plane in IMUNES is extended to retain control over the experiment execution after initial topology instantiation, allowing for user-scheduled events to inuence selected parameters during run time.

43

4.5. User-congurable Event Scheduling

4. Advanced Usage

The current implementation allows for the event scheduler to assume control over selected link properties such as:

bandwidth delay bit error rate packet duplication visual attributes

line width line color The event scheduler supports two general classes of schedulable events: one-time changes and periodic functions. One-time events update the selected parameter at requested point in time, leaving that parameter constant throughout rest of the experiment execution, or until another event updates it to a new value at some later point in time. Periodic functions allow for time-variant functions to be applied to selected parameters by specifying those functions as single events. Subsequently scheduled events acting upon the same parameter will cancel the current periodic function and replace it with either a constant value or another periodic function.

4.5.2

Conguring events with events editor

Events can be specied in the Events editor (Figure 4.40). To open the Events editor select the Events Events editor option. The editor is divided into two elements. The left side element contains a list of all links. The right side element contains events congured on the selected link. This dialog allows you to edit events on that link. To save the event scheduling conguration you need to click on Apply button. The events editor gives you the possibility to start or stop the event scheduling during experiment execution. This can be also done from the Events menu in the menubar.

Figure 4.40: Events editor

Each event entry occupies a single line of text, consisting of four elds: deadline, target parameter, function and function parameters. The rst eld, deadline, is specied as an integer number of seconds since experiment instantiation. The second eld, target parameter, may be one of the following: bandwidth, delay, ber, duplicate, width or color. The remainder of the line is further parsed as a function. The type of the function is determined by the leading keyword, which may be either const, ramp, rand or square. When saving the conguration through the events editor a syntax check will be performed. If the syntax is wrong the 44

4.5. User-congurable Event Scheduling

4. Advanced Usage

conguration will not be saved and a popup dialog will show the rst line that has a syntax error.

Const
The const function accepts one parameter, the target value. After the deadline time the parameter will constantly be equal to the target value.

Ramp
Behavior of the ramp function is determined by three arguments: initial value, delta, and period, which are all integers. The rst argument represents the initial function value. The second is the delta value, which may be both positive or negative, which is added to the previous value of the function at each period. The third argument is the period, determining how often will the delta value be added to the current function value.

Rand
The rand function is determined by three arguments: lower bound, upper bound, and period; all of which are integers. The function will assume a random value between lower and upper bound after each period (in seconds) expires.

Square
Finally, the square function has three arguments as well: low value, high value, and period; all integer numbers. The resulting function will ip from low value to high and vice versa after each period (in second) expires.

Example
The following example illustrates a possible event scheduling scenario:

link l1 { nodes n1 n2 events { 30 bandwidth ramp 128000 8000 2 30 delay rand 80000 120000 8 60 delay square 100000 200000 10 60 ber const 1 90 ber const 0 120 delay const 0 } }
At t = 30 s, bandwidth of link l1 will be set to 128 Kbps, and will continue to grow at a rate of 8 Kbps each 2 s. Also at t = 30 s, the delay will begin assuming a random value between 80 ms and 120 ms, and will continue to change the setting to new random values in the same range each 8 s. At t = 60 s, the delay will cease to assume random values, and instead it will begin to oscillate between two discrete values, 100 ms and 200ms, each 10 s. Also at t = 60 s, the bit error rate (BER) will be set to 1, resulting in all frames traversing the link to be silently dropped. At t = 90 s, the BER is reset back to 0, allowing for all frames to traverse the link without articial losses. At t = 120 s, the oscillation of the delay parameter will stop, and delay will be reset to 0 ms for the rest of the experiment execution time.

45

4.6. Starting and terminating a simulation through CLI

4. Advanced Usage

The current time is shown on the status bar after the zoom value. (Figure 3.17)

4.5.3

Conguring events through conguration le

NOTE: It is advised to use the Events editor to congure event scheduling because it includes a syntax check. In the case of conguring events through conguration le, the wrong syntax will be silently ignored. IMUNES experiments are dened via plain-text conguration les, which currently describe virtual nodes and links, as well as additional objects related only to GUI visual properties and annotations. The other way to congure events is manual editing of an existing conguration le. The example bellow shows a conguration section describing a virtual link in an IMUNES experiment. The link l0 connects virtual nodes n0 and n1, has the bandwidth constraint set to 128 Kbps, and has the thickness of the line representing the link in the GUI set to 6 pixels. All of the mentioned properties are directly controllable via the IMUNES GUI. The conguration for link l0 also includes an empty placeholder for schedulable events, meaning that no events have been programmed for this link.

link l0 { width 6 nodes {n0 n1} bandwidth 128000 events { } }

The events section in the conguration le accepts the same commands as does the Events editor in the GUI.

4.6

Starting and terminating a simulation through CLI

In addition to the FileOpen option to open an .imn le and the ExperimentExecute option used to initiate the virtual network topology in the GUI, the simulation can be initiated through the command-line interface (CLI) with the following command:

# imunes -b simple-network.imn
Using IMUNES through GUI, the ExperimentTerminate option is used for shutting down the simulation and cleaning up the virtual network topology from the kernel. The CLI alternative for the latter is the following command:

# imunes -b -e experimentId
The parameter exeperimentId represents the experiment identier. In order to get the experiment identier you can use the himage command. With himage -l you will get a list of identiers of all started experiments.

4.7

Managing virtual nodes (jails) - jls, jexec

The FreeBSD jail mechanism allows partitioning of a FreeBSD-based computer system into several independent smaller systems called jails. This mechanism enables creation of a safe environment, separate from the rest of the system. Processes created inside a jail are limited within that jail environment. Each jail is a virtual environment running on the host machine, having its own le system, processes, set of users, networking subsystem of the FreeBSD kernel and a few other things. Two main commands exist in FreeBSD for manging and conguring previously created jails:

jexec - executes a command inside an existing jail

46

4.8. Himage tool

4. Advanced Usage

jls - lists jails.

A virtual image or vimage is a jail with its own independent network stack instance. Every process, socket and network interface present in the system is always attached to one, and only one, virtual network stack instance (vnet). During system bootup sequence a default vnet is created to which all the congured interfaces and user processes are initially attached. The jexec command allows for execution of arbitrary processes in a targeted virtual image.

jexec jname command ...

The jexec command starts the selected command and its arguments in the jail jname. To nd out the names of started jails the jls command is used:

jls [-hnqsv] [parameter ...]

Since the default jls command doesnt list names of jails a better output is provided using the command:

jls -h jid name host.hostname

Also, the command jls -v gives a more detailed output.

4.7.1

Examples
Execute the ifconfig command in the jail with the jail name n1:

# jexec n1 ifconfig
Execute the csh command in the IMUNES virtual node named host1: First we need to nd out the jail ID or jail name to execute the wanted command:

# jls -h jid name host.hostname | grep host1

The rst parameter output is the jail ID, the second is the jail name and the last is the hostname. To execute the command you need the jail ID or jail name:

# jexec jid csh # jexec jname csh

4.8

Himage tool
The jls and jexec commands can be impractical for creating scripts for topologies since the output of the jls command is needed for starting the jexec command. The jexec command cant take the hostname of the jail as an argument, it can only take the jail name or jail id. The jail name is created from the IMUNES experiment ID and the node identier (not hostname). Every experiment started in IMUNES has a different randomly generated experiment ID to enable execution of multiple experiments at once. IMUNES comes with the himage tool that enables the usage of hostnames when starting commands in virtual nodes. The himage tool starts the jexec command with the appropriate jail name so that the user doesnt have to search for it. The himage command has the following options:

himage vi_hostname command ... - executes the command in the virtual node with the specied hostname. If no command is specied it starts an interactive shell. himage -v vi_hostname - gets the jail node name of the virtual node with the specied hostname himage -n vi_hostname - gets the node identier for the specied hostname. himage -e vi_hostname - gets the experiment ID in which the virtual node with the specied hostname is running.

47

4.9. Hcp tool

4. Advanced Usage

himage -j vi_hostname - gets the jail ID in which the virtual node with the specied hostname is running. himage -l - gets the experiment list.

4.8.1

Examples
Example of usage of the command himage on a node with the hostname "pc" to get a list of running processes:

# himage pc ps ax
If there are multiple experiments running and there are nodes with the same hostnames in these experiments the himage command accepts the following node specication where vi_hostname is specied as hostname@eid, where eid is the experiments ID.

# himage hostname@eid command ...

i.e:

# himage pc@i3d05a ps ax
where i3d05a is the experiment ID of the running experiments. To nd out which experiments are running the himage -l command can be used as well as jls -h jid name host.hostname. Execute the ifconfig command the IMUNES node named server:

# himage server ifconfig

4.9

Hcp tool
While the himage command is used for running programs inside virtual nodes the hcp is used to copy les directly to the lesystem of running mobile nodes, thus simplifying deployment of conguration les for starting various services on virtual nodes. Usage of the command hcp:

hcp [cp_command_options] [vi_hostname1:]filename [vi_hostname2:]filename

The hcp command invokes the cp command with the specied options. If the vi_hostname1 is specied the script copies a le from the virtual node, otherwise it copies a le from the local folders. The second vi_hostname2 species on which node the rst le will be copied, if not specied the le is copied to the local folders.

vi_hostname is specied in the same way as in the himage command, hostname or hostname@eid.

4.9.1

Examples
Copy le dhcpd.conf from a local folder to the virtual node DHCP:

# hcp dhcpd.conf DHCP:/usr/local/etc/

Copy le message.txt from the virtual node PC to a local folder:

# hcp PC:/root/message.txt .
Copy le index.html from the virtual node HOST to the virtual node HTTP:

# hcp HOST:/usr/local/www/data/index.html HTTP:/usr/local/www/data/

4.10

Example (himage and hcp)

This is an example of starting an DHCP server through a script with the provided conguration le dhcpd.conf. Kill the server if its started:

48

4.10. Example (himage and hcp)

4. Advanced Usage

# himage DHCP killall -9 dhcpd

Copy the conguration le:

# hcp dhcpd.conf DHCP:/usr/local/etc/

Create the .leases le dened in dhcpd.conf:

# himage DHCP touch /var/db/dhcpd.leases

Start the sever with the copied conguration le:

# himage DHCP dhcpd -cf /usr/local/etc/dhcpd.conf

49

Appendix A

Installation

A.1
A.1.1

Installation of IMUNES on FreeBSD

Installing FreeBSD
A comprehensive and explanatory guide for installing conguring and using FreeBSD can be found here:

http://www.freebsd.org/doc/handbook/
Section 2 of the handbook describes the installation of the FreeBSD operating system:

http://www.freebsd.org/doc/handbook/install.html
You can choose to install FreeBSD with two different architectures:

i386 - 32-bit - works on most personal computers. amd64 - 64-bit - works on newer computers that support 64-bit processing. Adds support for more RAM.

A.1.2

Step by step guide through the FreeBSD installation

1. Insert the FreeBSD-8.2-RELEASE or FreeBSD-8.3-RELEASE (i386 or amd64) medium on startup. Boot from it. 2. Country Selection - Choose your country (i.e. United States). Press OK. 3. Main Menu - Choose the "Standard" installation. Press Select. 4. Message - Press OK. 5. FDISK Partition Editor - Press C to create a slice: (a) A minimum of 20GB is needed for FreeBSD. Type 20G to create a 20GB slice. Press OK. (b) A screen with the number 165 appears. Press OK. (c) Position on the created partition (probably named ad0s1). (d) Press S to set the created partition bootable. 6. FDISK Partition Editor - Position on the "unused" space beneath the created partiton. Press C to create another slice: (a) A minimum of 5GB is needed for ZFS. Type 5G to create a 5GB slice. Press OK. (b) A screen with the number 165 appears. Press OK. (c) Remember the name of this partition (probably named ad0s2). This name will be later used for conguring ZFS. 7. FDISK Partition Editor - Press Q to nish. 8. Boot Manager - Select the "Standard" option. Press OK. 9. Message - Press OK. 10. FreeBSD Disklabel Editor - While the partition "ad0s1" (the 20GB one) is selected press A to automatically distribute system partitions on it. 11. FreeBSD Disklabel Editor - The result should look similar to this:

Part

Mount

Size
50

A.1. Installation of IMUNES on FreeBSD

Appendix A. Installation

ad0s1a ad0s1b ad0s1d ad0s1e ad0s1f

/ swap /var /tmp /usr

1024MB 2006MB 5099MB 1024MB 11326MB

12. FreeBSD Disklabel Editor - Press Q. 13. Choose Distributions - Select the "6 User" distribution. 14. FreeBSD Documentation Installation Menu - Select "en" and then "X Exit". 15. Ports collection installation - Select "Yes". 16. Choose Distributions - Select the "X Exit" to exit. Press OK. 17. Choose Installation Media - Select "1 CD/DVD Install from a FreeBSD CD/DVD". 18. Continue through the Installation - Select "Yes". 19. Wait until the installation is over. 20. Message - Press OK. 21. Congure any ethernet devices? - Select "Yes". (a) Select the wanted ethernet device, i.e. em0. (b) IPv6 conguration - Select "No". (c) DHCP conguration - Select "Yes". (d) Enter the hostname, i.e. IMUNES1. (e) Select "OK". 22. Network gateway - Select "No". 23. Install inetd services - Select "No". 24. Allow SSH login - Select "Yes". 25. Allow anonymous FTP access - Select "No". 26. NFS server - Select "No". 27. NFS client - Select "No". 28. Customize system console settings - Select "No". 29. Set time zone - Select "No". 30. Congure mouse - Select "No". 31. Browse package collection - Select "No". 32. Add additional user accounts - Select "No". 33. Message - Set root password - Press "OK". Enter password. Re-enter password. 34. Visit the general conguration menu - Select "No". 35. Main Menu - Select the "X Exit Install" option by using the "Tab" key. 36. Are you sure you want to exit? - Select "Yes". 37. Message - Reboot - Press "OK".

A.1.3

Installing the FreeBSD X11 system - GUI

Login into the machine as root. Edit the le /etc/rc.conf with an editor i.e. vi and add the following lines at the end of the le:

hald_enable="YES" dbus_enable="YES"

51

A.1. Installation of IMUNES on FreeBSD

Appendix A. Installation

zfs_enable="YES"
Save changes and exit.

# pkg_add -r xorg bash xpdf vim geany zip unzip xterm firefox
You can choose between multiple desktop environments:

Gnome2-lite - complete, user-friendly desktop # pkg_add -r gnome2-lite XFCE 4 - lightweight desktop environment # pkg_add -r xfce4 IceWM - extremely lightweight window manager, low resource usage # pkg_add -r icewm
After the installation of one or multiple window manager we need to congure which will be used. Edit the le .xinitrc in the user folder and add a line depending on which window manager you want to use:

Gnome2-lite exec gnome-session XFCE 4 exec startxfce4 IceWM exec icewm-session

Reboot the machine by issuing the reboot command:

# reboot
After the machine has rebooted, log in and issue the startx command to start the chosen window manager:

# startx

A.1.4

Installing IMUNES
First we need to install the packages needed for IMUNES. To do this execute the following command:

# pkg_add -r tk86 ImageMagick tcllib libimg wireshark

After all the packages are installed we need to use the second partition we prepared during the installation (the one with the size 5GB, probably named ad0s2). This partition will be used to store the data that will be in the virtual nodes. For this purpose we will create a ZFS pool on the second partition with the command zpool create assuming that the second partition is named ad0s2:

# zpool create vroot /dev/ad0s2

Now we need to fetch the IMUNES source/tarball from the ofcial imunes site:

http://imunes.tel.fer.hr/imunes-1.0.tar.gz
To fetch you can use the refox browser that we installed earlier or use the fetch command:

# fetch http://imunes.tel.fer.hr/imunes-1.0.tar.gz
To extract the tarball use the following command:

# tar xf imunes-1.0.tar.gz
Enter the extracted directory:

# cd imunes
Now we need to install IMUNES and populate the ZFS le system with predened and required data. To install imunes on the system execute:

# make install
52

A.1. Installation of IMUNES on FreeBSD

Appendix A. Installation

To setup the ZFS le system execute:

# make vroot
Both of these commands can be executed together by executing:

# make
Now the IMUNES GUI can be ran just by typing the imunes command in the terminal:

# imunes
The GUI allows the specication of network topologies but to execute experiments the FreeBSD kernel must be compiled with a few additional options.

A.1.5

Recompiling the FreeBSD kernel with VIMAGE support

First, the kernel sources need to be fetched, this can be done by using the sysinstall utility: 1. Start the sysinstall utility:

# sysinstall
2. Go to "Congure". 3. Go to "Distributions". 4. Go to "sys". 5. Mark "src" by pressing the Space key on it. 6. Select "X Exit". 7. Select "X Exit". 8. Select "Install from an FTP server". 9. Choose the "Main server" or a server closer to your location. 10. When the installation is done select press the Esc key until you exit the sysinstall utility. Now the kernel source is available in the folder /usr/src/sys. Enter that folder:

# cd /usr/src/sys
Depending which distribution architecture you have decided to install, i386 or amd64 the next command differs. For i386 enter the directory i386/conf:

# cd i386/conf
For amd64 enter the directory amd64/conf:

# cd amd64/conf
With an editor (vi, vim or geany) create a le named VIMAGE:

# vi VIMAGE
Insert the following conguration in the VIMAGE le:

include GENERIC nooptions SCTP nooptions FLOWTABLE options VIMAGE options VNET_DEBUG options DDB options KDB
Exit and save the le. Now execute the following commands:

53

A.2. Running IMUNES with VMware Player

Appendix A. Installation

# # # # #

config VIMAGE cd ../compile/VIMAGE make cleandepend && make depend make make install

When the last command ends use the reboot command to restart the computer:

# reboot

A.1.6

Running IMUNES on FreeBSD

After login execute the startx command to start the window manager. Open a terminal and start imunes:

# imunes
Now you can create an arbitrary network topology or something like shown in Figure 3.1 and execute the experiment.

A.2

Running IMUNES with VMware Player

We also have a VMware image containing the FreeBSD operating system including a complete and working installation of IMUNES.

A.2.1

Installing VMware
To run the image VMware Player (or any other similar VMware product) needs to be installed. VMware player can be downloaded from the following address (after registration with VMware):

http://www.vmware.com/products/player/
The installation procedure is clearly explained in the VMware "Getting Started Guide" (http: //www.vmware.com/pdf/vmware_player310.pdf)

A.2.2

Downloading the VMware image

The VWware image can be downloaded from the following address:

http://imunes.tel.fer.hr/imunes/dl/index.html
There are two archives, one in the RAR format and other in the ZIP format. They both contain the same image but the RAR le is considerably smaller. Download one of them and then unpack the contents of the archive in a folder with enough space (The unpacked image is almost 2.3GB large, but for runtime execution 4GB is needed.)

A.2.3

Running the VMware image

After the image is extracted go into the image directory. There shpuld be two les, a vmdk le containing the disk image and a vmx le containing the VMware machine settings. Doubleclicking the vmx le will open the VMware Player and start booting the image. A window will pop-up asking you wheter you moved or copied the image. Select the option "I copied it" and click on the "OK" button. After a few minutes FreeBSD with the graphical interface will start. On the desktop there is an IMUNES icon to start IMUNES.

54

A.3. Installation of the IMUNES GUI on Linux

Appendix A. Installation

A.3

Installation of the IMUNES GUI on Linux

NOTE: Although you can draw network topology on any system that supports Tcl/Tk (Linux, FreeBSD, Windows, Mac OS X, Solaris), an experiment can only be started on FreeBSD operation system with root permissions (Figure 3.15 and Figure 3.16)!. The rst thing you need to do is install Tcl/Tk. The easiest way to do this is using ActiveState ActiveTcl 8.6. To download the installation les visit:

http://www.activestate.com/activetcl/downloads
Download the version 8.6, as IMUNES cannot run on earlier versions. Download the version that is designed for your operating system: x86 if youre using 32bit Linux or x86_64 if youre using 64bit Linux. Select the option AS package. When the package is downloaded extract it using an archive manager or through the shell with the command:

# tar xzvf filename.tar.gz

Now enter the extracted directory and execute the le install.sh with root permissions. In the shell this is done with the line

# sudo ./install.sh
and provide the superuser password. If you dont have superuser permissions you can install ActiveTcl in your user directory. Make a directory in which ActiveTcl will be installed, and during the installation provide the path to that directory. After the installation you just need to put the ActiveTcl bin directory in the PATH variable. For a csh or compatible (tcsh) perform:

# setenv PATH "/opt/ActiveTcl/bin:$PATH"

For a sh or similar perform:

# PATH="/opt/ActiveTcl/bin:$PATH" # export PATH

To make the changes permanent add this lines to your shell rc conguration le (e.g. .bashrc for bash, .cshrc for csh). To run IMUNES with full functionality you need the imagemagick package. You can install it through package managers or through shell. On Debian, Ubuntu and other Debian based distributions you will use:

# sudo apt-get install imagemagick

On Fedora, Red Hat and other Red Hat based distributions you will use:

# su # yum install imagemagick

Now we can fetch the latest version of IMUNES through CVS. To do this you need to have the cvs package installed. This is done the same way as the ImageMagick installation:

# sudo apt-get install cvs

or

# su # yum install cvs

The line for fetching IMUNES from CVS is as follows:

# cvs -d :pserver:[email protected]/usr/local/src/cvsroot co imunes

Now enter the imunes directory and start IMUNES:

# cd imunes

55

A.4. Installation of the IMUNES GUI on Windows

Appendix A. Installation

# ./imunes

A.4

Installation of the IMUNES GUI on Windows

NOTE: Although you can draw network topology on any system that supports Tcl/Tk (Linux, FreeBSD, Windows, Mac OS X, Solaris), an experiment can only be started on FreeBSD operation system with root permissions (Figure 3.15 and Figure 3.16)!. The rst thing you need to do is install Tcl/Tk. The easiest way to do this is using ActiveState ActiveTcl 8.6. To download the installation les visit:

http://www.activestate.com/activetcl/downloads
Download the version 8.6, as IMUNES cannot run on earlier versions. Download the package by clicking on the Windows Installer (EXE) option. When the le is downloaded start the installation by double clicking on the le. Follow the installation instructions to the end. Now, to enable the full functionality of IMUNES you need to download the ImageMagick program from:

http://www.imagemagick.org/script/binary-releases.php
Go to the Windows Binary Release section. Select the appropriate le. Download it and install it following the installation instructions. To start IMUNES you need the latest IMUNES release. If you have access to a Unix/Linux system you can download it like it is shown at the end of the previous section (Section A.3). Then transfer it on the Windows machine. Enter the imunes directory and double click the le imunes.tcl to start IMUNES.

56

Appendix B

Troubleshooting

B.1

Terminating all active experiments

To terminate all active experiments a clean-up script is available in the IMUNES system. The script is invoked by issuing the command cleanupAll with root privileges. This script will terminate all running experiments.

# cleanupAll

B.1.1

Cleaning up hanging ZFS mounts

If a machine running an experiment is rebooted the experiment will not be available after boot but the ZFS mounts needed for network nodes will remain available after the restart. The cleanupAll tool is also used for destroying the remaining ZFS mounts.

B.2

Restoring original ZFS snapshot

The ZFS snapshot used for replicating on virtual nodes can be corrupted or deleted. To restore the ZFS snapshot to the original state we rst need to destroy the existing default snapshot named vroot/vroot@clean. Before destroying the ZFS snapshot make sure that no experiments are currently running by using the command himage -l and use the imunes -b eid option or the cleanupAll tool to terminate them. removal of the ZFS snapshot is done by issuing the following command with root user privileges:

# zfs destroy -fR vroot/vroot@clean

After the procedure is complete download the IMUNES tarball from the IMUNES website XXX and unpack it. Then enter the directory an run the command make vroot with root privileges to restore the ZFS snapshot. The procedure done as follows:

# tar xf imunes.tar.gz # cd imunes # make vroot

NOTE: To restore the snapshot an Internet connection must be available.

B.3

Obtaining kernel panic traces

In case a specic experiment conguration, workload type or hardware conguration triggers operating system crashes, obtaining traces of such events may be instrumental for sucessfull debuging and resolving the observed operating system level bugs. The following procedure is recommended for collecting kernel panic traces: Add the following line to the /etc/rc.conf le:

dumpdev="AUTO"
Create a new le /usr/local/etc/etc/rc.d/textdump and populate it with the following script:

#!/bin/sh # # PROVIDE: textdump # REQUIRE: LOGIN

57

B.3. Obtaining kernel panic traces

Appendix B. Troubleshooting

ddb script kdb.enter.panic="textdump set; capture on; bt; show reg; show pcpu; show vn
Set execution bit on /usr/local/etc/etc/rc.d/textdump le:

# chmod +x /usr/local/etc/rc.d/textdump
Once rebooted, the machine should be from now on congured to automatically store kernel panic traces in /var/crash directory. Heres an example of collection of kernel panic trace les:

# ls -l /var/crash/ total 96 -rw-r--r-- 1 root -rw------- 1 root -rw------- 1 root -rw------- 1 root -rw------- 1 root -rw------- 1 root -rw------- 1 root #

wheel wheel wheel wheel wheel wheel wheel

2 440 442 442 24576 39424 24576

Sep Sep Sep Sep Sep Sep Sep

20 19 20 20 19 20 20

00:06 23:57 00:00 00:06 23:57 00:00 00:06

bounds info.0 info.1 info.2 textdump.tar.0 textdump.tar.1 textdump.tar.2

Such "textdump" tarballs should be sumbitted along with any reports of kernel crashes.

58

Appendix C

IMUNES network conguration le

Here is the example of IMUNES network conguration le for the network topology shown in Figure C.1

Figure C.1: Network topology

node n0 { type router model quagga network-config { hostname office-router ! interface eth1 ipv6 address a:1::1/64 ip address 192.168.2.1/24 ! interface eth0 ipv6 address a:0::1/64 ip address 192.168.1.1/24 ! router rip redistribute static
59

Appendix C. IMUNES network conguration le

redistribute connected redistribute ospf network 0.0.0.0/0 ! router ripng redistribute static redistribute connected redistribute ospf6 network ::/0 ! } canvas c0 iconcoords {576.0 288.0} labelcoords {576.0 322.0} interface-peer {eth0 n1} interface-peer {eth1 n2} } node n1 { type lanswitch network-config { hostname office-switch ! interface e2 fair-queue ! interface e1 fair-queue ! interface e0 fair-queue ! } canvas c0 iconcoords {408.0 168.0} labelcoords {408.0 202.0} interface-peer {e0 n0} interface-peer {e1 n3} interface-peer {e2 n4} } node n2 { type host network-config { hostname office-host ! interface eth0 ipv6 address a:1::10/64 ip address 192.168.2.5/24 ! ipv6 route ::/0 a:1::1 ! ip route 0.0.0.0/0 192.168.2.1 ! } canvas c0
60

Appendix C. IMUNES network conguration le

iconcoords {408.0 456.0} labelcoords {408.0 498.0} interface-peer {eth0 n0} } node n3 { type pc network-config { hostname office-pc1 ! interface eth0 ipv6 address a:0::20/64 ip address 192.168.1.5/24 ! ipv6 route ::/0 a:0::1 ! ip route 192.168.2.0/24 192.168.1.1 ! } canvas c0 iconcoords {192.0 72.0} labelcoords {192.0 119.0} interface-peer {eth0 n1} } node n4 { type pc network-config { hostname office-pc2 ! interface eth0 ipv6 address a:0::21/64 ip address 192.168.1.7/24 ! ipv6 route ::/0 a:0::1 ! ip route 192.168.2.0/24 192.168.1.1 ! } canvas c0 iconcoords {192.0 240.0} labelcoords {192.0 282.0} interface-peer {eth0 n1} } link l0 { delay 30 nodes {n1 n0} bandwidth 0 } link l1 { nodes {n3 n1} bandwidth 0 }

61

Appendix C. IMUNES network conguration le

link l2 { nodes {n4 n1} bandwidth 0 } link l3 { nodes {n2 n0} bandwidth 0 } annotation a0 { iconcoords {59 20 445 338} type rectangle label {Office room} labelcolor black font {-family Arial -size 14 -weight bold -slant roman} color Gray width 1 border black rad 25 canvas c0 } canvas c0 { name {Canvas0} } option show { interface_names yes ip_addresses yes ipv6_addresses no node_labels yes link_labels yes ipsec_configs yes background_images no annotations yes grid yes iconSize normal zoom 1.0 }

62