Examples are available for download on github:

List of currently available documented examples:

Installing additional packages in virtual nodes

To install additional packages in the IMUNES virtual nodes the script pkg_add_imunes is included in the IMUNES release.

# pkg_add_imunes -r strogswan tshark

Making scripts for IMUNES

IMUNES experiments can be started without GUI, by using the batch option:

# imunes -b topology.imn
Creating nodes...
pc1 router1 router2 pc2 router3 
Creating links...
l0 l2 l1 l3 
Configuring nodes...
n0 n1 n2 n3 n4 
Network topology instantiated in 0 seconds (5 nodes and 4 links).
Experiment ID = i95350

IMUNES includes the following tools that enable easy scripting for virtual topologies:

  • himage - runs a shell or command directly in a virtual node
  • hcp - copies files to/from (between) virtual nodes (i.e. copying config, log files)
  • vlink - alters all link properties (bandwidth, delay, BER, duplicate)
  • cleanupAll - shuts down all running experiments
    # cleanupAll
    Terminating processes...
    Shutting down netgraph node 
    Shutting down vimages...
    Cleanup completed in 1 seconds.


The himage command is a wrapper around the standard jls and jexec tools that are used to manage FreeBSD jails.

The default output shows usage possibilities:

$ himage

Command himage can be used as an interface to the command jexec/jls
for virtual images. Hostname is used instead of jail name.
Hostname can be in the form: hostname or hostname@eid.

  himage vi_hostname command
  himage -v vi_hostname  ---> vimage name      (eid.nodename)
  himage -n vi_hostname  ---> vimage node name (nodename)
  himage -e vi_hostname  ---> vimage eid name  (eid)
  himage -j vi_hostname  ---> vimage jail id   (jid)
  himage -d vi_hostname  ---> vimage path
  himage -l              ---> running experiments eids 

The main usage scenario of himage is to run applications in IMUNES nodes without GUI by using node names (i.e. pc1, router1, dnsServer, ...) instead of node identificators (i.e. n0, n1, ...). Running a command inside the node named pc1 in the current topology (must be ran as root):

# himage pc1 ls
.cshrc		boot.conf	libexec		rescue		usr
.profile	dev		media		root		var
COPYRIGHT	etc		mnt		sbin
bin		home		out.log		sys
boot		lib		proc		tmp

If there are multiple experiments running with the same node names then a warning will be issued:

# himage pc1
Error: pc1 is not a unique name.
It is used (at least) for nodes:
   245  -               pc1                           /var/imunes/i95350/n0
   256  -               pc1                           /var/imunes/ib5b10/n0

Now you need to specify the experiment ID (@i95350) you want to run the command in:

# himage pc1@i95350 ls
.cshrc		boot.conf	libexec		rescue		usr
.profile	dev		media		root		var
COPYRIGHT	etc		mnt		sbin
bin		home		out.log		sys
boot		lib		proc		tmp

To see the list of running experiments run the following:

$ himage -l

Additional information about experiment nodes can be found using the other himage options:

$ himage -v pc1
$ himage -n pc1
$ himage -e pc1
$ himage -j pc1
$ himage -d pc1


The hcp command is a wrapper around the standard cp command. It uses node names to refer to virtual node root partitions.

Here are two examples that demonstrate copying from the virtual node and to the virtual node:

# hcp router1:boot.conf .
# hcp router1:/root/

The command can also be used to copy files between virtual nodes and between experiments (using the same notation as himage):

# hcp router1:boot.conf router2:root/
# hcp router1@i84ec0:root/ router1@i56ad1:root/

The vlink command is a wrapper around ngctl, netgraph tool used to create links between virtual nodes in IMUNES.

vlink is used to change link parameters. The following link parameters are available:

  • bandwidth (bps, bits-per-second)
  • bit-error rate, BER (number of bits in which one error will occur)
  • delay (microseconds)
  • packet duplication (%, percentage of packets that will be duplicated)

A link is identified by the endpoint node names. The link between pc1 and pc2 is identified by pc1-pc2 or pc2-pc1.

vlink [options] link_name[@eid]
 -bw value            set link bandwidth (bps) <>
 -BER value           set link BER (1/value) <>
 -dly value           set link delay (us) <>
 -dup value           set link duplicate (%) <>
 -r                   set link settings to default values
 -e value             specify experiment ID <>
 -eid value           specify experiment ID <>
 -?                   Print this message

Setting the bandwidth to 10 Mb/s with a delay of 30 ms to the link connecting router1 and pc1:

# vlink -bw 10000000 -dly 30000 router1-pc1

Generate an error on one bit in a million:

# vlink -BER 1000000 router1-pc1

Set packet duplication to 20%:

# vlink -dup 20 router1-pc1

Modifying a link in a specific experiment (i.e. Experiment ID = i56ad1):

# vlink -dup 20 router1-pc1@i56ad1

To reset the link settings to the default values the -r flag is used:

# vlink -r router1-pc1@i56ad1
Last modified 2 years ago Last modified on Mar 17, 2015 2:25:22 PM

Attachments (2)

Download all attachments as: .zip