IMUNES network simulator test drive

March 19, 2013

The Integrated Multiprotocol Network Emulator/Simulator (IMUNES) is a fast, functional network simulator that runs on the FreeBSD operating system. It was created by a team of researchers and educators at the University of Zagreb.


The IMUNES development team offers a VirtualBox image of a FreeBSD system with IMUNES installed so it is easy to evaluate. We will take a first look at IMUNES by installing this image in VirtualBox and testing a few of the features of this interesting open-source network simulator.

FreeBSD Jails Virtualization

IMUNES simulates IP networks by creating virtual nodes on a FreeBSD host system. These virtual nodes are virtual network stack instances created using the FreeBSD Jails virtualization feature, which is similar to Linux Containers (LXC) and provides a system of virtual nodes that start quickly and perform well.

Each virtual node runs its own copy of the FreeBSD filesystem, has its own IP networking configuration, and can run standard UNIX utilities to generate or manipulate traffic on links. The user can interact with each virtual node as if it were a physical node and can run commands on that node. You can find more technical information about the network stack virtualization used in IMUNES here, here, and here.


To evaluate IMUNES, we will download the IMUNES virtual appliance and run it in the VirtualBox virtual machine manager. The IMUNES virtual appliance is available on the Downloads page of the IMUNES web site.

Download the virtual appliance: (651MB)

Unzip the archive to a directory on your computer. The unzipped files will be in a directory named IMUNES.

Start VirtualBox. Use the VirtualBox menu command, Machine → Add to select the IMUNES.vbox file. Virtualbox will load the virtual machine into its list of available virtual machines. In the VirtualBox virtual machine manager window, click on the virtual machine named IMUNES and press the Start button. The IMUNES virtual machine will start up.

Start the IMUNES virtual machine

After starting up the IMUNES virtual machine, VirtualBox indicated an “Invalid settings detected” warning. To clear the warning, I increased the video memory assigned to the virtual machine to 16 MB. Then I started the virtual machine, again.


The IMUNES virtual machine will start up, running FreeBSD.

Keyboard mapping

The IMUNES virtual machine is set up to work with a European keyboard. If you are using a “US English” keyboard like I am, you will find that the keymapping for important keys like slash do not match your keyboard. I’d like to thank anntoin, who provided the key mapping procedure shown below:

To define a new keyboard map, use the keyboard mapping utility, setxkbmap. Run the following command to set the keyboard to a US layout:

# setxkbmap us

To change this setting permanently, edit the /root/.bashrc file. But first, run the setxkbmap command in the Terminal so the keyboard mapping is set to match your keyboard or editing the file will not work because the keys do not match the key mappings.

If you are using another type of keyboard, you can find the list of supported keyboard layouts in the file: /usr/local/share/X11/xkb/rules/base.lst.


Click on the IMUNES icon on the desktop to start the IMUNES network simulator. This will open the IMUNES graphical user interface, which is a window with a graph paper-like canvas, a toolbox on the left side, and a menu bar on the top.

The IMUNES network simulator has two modes of operation: the Edit and Execute modes.

By default, the IMUNES GUI starts in Edit mode, which presents a blank canvas and a toolbar on the left side of the canvas. The user will draw a network scenario using the Edit mode tools and then run the simulation in Execute mode by executing the menu command: Experiment → Execute.

Edit mode: Add network nodes

In Edit mode, all of the tools in the IMUNES toolbox are available to use. While in Edit mode, we will add and configure PC nodes, switches, routers, and servers to the canvas. The tools we will us are:

0G-imunes-pc-button-shadowPC tool: This tool creates a virtual machine that performs the role of a client PC in the test network. The PC virtual machine is configured with a default static route, it does not forward packets, and it does not run any routing protocols or network services.

0D-imunes-switch-button-shadowLAN Switch tool: This tool creates a netgraph node that is configured to perform the role of a LAN switch. the LAN switch is not configurable; the user can configure only the node name and the queuing method. This node will build a forwarding table of link-layer addresses and ports and will forward received frames based on the link-layer information in the frames’ header.

0E-imunes-router-button-shadowRouter tool: This tool creates a virtual machine that is configured to perform the role of a router in the network. The router virtual machine is configured to run dynamic routing protocols and will forward received packets based on the IP header information in each packet. The user can log in to the router virtual machine and create more complex routing configurations and run advanced network servoces.

0F-imunes-server-button-shadowHost tool: This tool creates a virtual machine that performs the role of a host server in the test network. The PC virtual machine is configured with a default static route, it does not forward packets, and it does not run any routing protocols. The host server runs network services such as SSH.

To use each tool, click on the tool in the toolbar and then move the mouse pointer to a point on the canvas where you want to place that node type and click the mouse again. the node will appear on the canvas. In this example, we added PCs, switches, routers, and hosts (servers) to the canvas.


Edit mode: Connect network nodes

Next, we will connect the nodes together in a network. We will build links between the nodes in the network using the Link tool:

0B-imunes-link-button-shadowimunes-link-configLink tool: This tool creates links between network nodes. Click on the Link tool, then click on one node and drag towards the other node to which you want the link to connect. This will draw a link between the two nodes.

In this example, we created a “core network” of three routers that are all connected to each other to create multiple paths trough the network. We created networks consisting of PC nodes, host nodes, and switches to the routers at the edges of the core network.

Links can be configured using the Link Configuration dialog box. Right-click on a link and select Configure from the menu that appears. You can configure link quality attributes such as bit error rates. In this example, we will use the default configurations.

Edit mode: Configure network nodes

Next, we will configure the routers to run the OSPF dynamic routing protocol and then connect the nodes together in a network. To do this, we will use the following tool in the toolbar:

0A-imunes-select-button-shadowimunes-configure-routerSelect tool: This tool selects nodes and links, and allows the user to move nodes around the canvas. Click on the select tool, then click on the node you want to configure or move. You can click and drag the node anywhere on the canvas. You can right-click on a node or link to see the configuration menu for the node.

First, we will configure the routers to run OSPF. Click on the select tool. Then, right-click on one of the routers. Click on Configure in the drop-down menu that appears. This will open the Router Configuration dialog box.

In the Configuration tab, select quagga as the router model. IMUNES supports either the quagga or XORP open-source router software. However, XORP is not installed in the IMUNES.vbox virtual machines. If you select XORP, the router will not be able to function so choose quagga. Then, de-select the RIP routing protocols and select OSPFv2


In the Interfaces tab, you can configure IP addresses and the link state. In this example, we will use all the default values. One issue I saw was that the router configuration dialog box is available in both Edit mode and Execute mode, but changes made in the dialog box do not make any changes to the router’s configuration during Execute mode, even though the change appears in the configuration dialog. So, do not use the router configuration dialog during Execute mode; open a node shell and execute commands to change a running router’s configuration.


Execute mode: Running the simulation

Now that we have created the network shown below, we start the simulation. To switch to Execute mode, use the menu command, Experiment → Execute.


During Execute mode, most of the tools in the toolbar are greyed-out and cannot be used. The network topology cannot be changed in the canvas while IMUNES is in Execute mode. But, one can change the topology in other ways that do not show up on the canvas. For example, one could terminate a link between tow nodes by opening a shell on each node and changing the status of the interfaces on each end of the link to “down”.

Execute mode: Widgets

IMUNES provides a Widget function that will show information about nodes when the mouse is moved over a node during Execute mode emulation. The widget function execute a shell command and returns the results to a pop-up windown on canvas. There are widgets available by default: ifconfig and Routing Table. You can also create custom widgets.

For example, we could quickly inspect the routing tables of each node by running the Menu command, Widgets → Routing Table and moving the mouse over a node, as seen below.


To stop widgets from popping up, execute the Menu command, Widgets → None.

Accessing a node terminal

The user can log in to a node and execute shell commands to perform more configurations or start network tools such as a traffic generator or a traceroute command. The LAN Switch and Hub nodes do not provide shell access because they are implemented as kernel processes, not virtual machines emulating network-layer equipment. PC nodes, hosts, and routers provide shell access.

To access the node’s shell, right-click on the node and select the Shell option from the pop-up menu that appears, Then select the shell you want to run on the node, such as the bash shell on a PC or the vtysh shell on a quagga router.


A terminal window will appear that is running the shell on the selected node. The node name is shown in the terminal window’s title bar. In this example, we will run a bash shell on one of the PC nodes and execute ping and traceroute commands to test if the emulated network will forward packets to and from a host server on the far side of the core network.


We see, in this example, that ping and traceroute commands executed on the PC named n2 perform as expected. We also see that the routing protocols running on the core network routers created forwarding tables that cause the routers to forward data packets generated by the traceroute command through the shortest path between the PC named n2 and the server named n8: through routers n3 and n5.

Inspecting network traffic using Wireshark

While the emulation is running, we can start some network traffic between two nodes in a network and then use the Wiresharktool to inspect the data packets running through the emulated network.

We can start Wireshark from the IMUNES user interface. Right click on a node in the network and select Wireshark from the menu that appears. Then select the port that you wish to monitor on that node. Wireshark will start up and will start displaying all data packets that are receive on, or transmitted by, that interface.


From our previous experiments with traceroute, we know that the data passing between n2 and n8 is passing through routers n3 and n5, so next we will start Wireshark on the eth1 port of router n5.

Then, on n2 we will run the same ping and traceroute commands as we did previously and watch the data packets appear on the Wireshark window that is monitoring traffic on the eth1 port of router n5. We see the ICMP packets from the ping command and the UDP packets from the traceroute command.


Stop the emulation

To stop the emulation, run the Menu command: Experiment → Terminate. This returns IMUNES to Edit mode.

Save the network configuration

We can save the network topology for future use by using the Menu command: File → Save As. This will save a configuration file that describes the network topology and configurations.


Note that only configurations created using the IMUNES user interface are saved. Additional configurations made in the command line in a node shell are not saved. But, complex configuration can be custom startup configuration field in the configuration dialog of a PC node, host, or router. See the Advanced Usage section in the IMUNES user manual for more details.

Run a saved network configuration

Another way to take a first look at IMUNES is to load an existing sample network configuration. Use the menu command File → Open and then select an existing sample lab file: for example, the OSPF lab. IMUNES will load the configuration and display the sample network on the canvas.


We evaluated the IMUNES open-source network simulator running in VirtualBox on a downloaded FreeBSD virtual machine. We used the features of IMUNES to emulate the operation of a small test network and to run some basic tests on that network.

IMUNES is a functional open-source network emulator. It provides a graphical user interface that makes it easy to create networks of interconnected virtual machines that can emulate network elements. This tool provides a lot of functionality beyond what is shown in this first look.

IMUNES is very similar to the CORE Network Emulator. CORE is a fork of IMUNES. Please see my posts about the CORE network emulator for more information about CORE.

The main differences that I have observed between IMUNES and CORE are:

  1. IMUNES runs only on FreeBSD. CORE runs on both Linux and FreeBSD.
  2. IMUNES and CORE share the same basic functions but CORE has more functionality added to it. However, not all of the added functions in CORE work well (or even work at all).
  3. IMUNES appears to perform better than CORE when running a simulation. However, I evaluated CORE on Linux so it is possible that CORE also runs as well as IMUNES if it is run on FreeBSD instead of on Linux.

7 responses to IMUNES network simulator test drive

  1. First, thanks for these great articles – you’ve made a lot of these tools far more accessible.

    Regarding the keyboard issue, the X Server keymap is set here in /root/.bashrc and is set to Croatian hr as default. Run setxkbmap us for a US layout, or setxkbmap gb for a UK layout for the current session, and change it in the .bashrc to make it permanent.

    • Anntoin,

      Thank you for your encouragement. I appreciate it.

      Also, thank you for documenting the procedure to change the keyboard mapping. I will update this post as soon as I can.


  2. I’m trying to run IMUNES using Oracle VM VirtualBox and the GUI is not showing up whatsoever. My VirtualBox is version 4.3.4 and I tried to run the IMUNES 8.3 release. Any ideas as to why it isn’t functioning?

    • Hi, I did not encounter that problem. What is the setup you used for the virtual machine? Maybe you didn’t allocate enough memory? When you say the GUI does not show up, do you still get a command-line prompt, which would suggest the issue is a configuration on the IMUNES VM image itself?

      • I got it to work with a more current version. Thanks for your help ☺

        • Your answer was just what I neeedd. It’s made my day!

          • I went ahead and got a more current version of VM VirtualBox (4.3.12) and use version 9.2 of IMUNES, and it’s still functions like a charm. I have some problems with the mouse pointer, but I think that’s due to it being in fullscreen with the mini toolbar present.