Skip to content

Making scripts for IMUNES

Denis Salopek edited this page Aug 9, 2019 · 5 revisions

Batch mode

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

### Start experiment with Experiment ID i1234
# imunes -b -e i1234 topology.imn
Using experiment ID 'i1234'.
Creating nodes...
100.0%
Creating links...
100.0%
Configuring nodes...
100.0%
Starting services...
Network topology instantiated in 2.261 seconds (5 nodes and 4 links).
Experiment ID = i1234

If you don't provide the -e flag, IMUNES will assign the experiment a random ID:

### Start experiment with a random Experiment ID
# imunes -b topology.imn
Creating nodes...
100.0%
Creating links...
100.0%
Configuring nodes...
100.0%
Starting services...
Network topology instantiated in 2.378 seconds (5 nodes and 4 links).
Experiment ID = i29bf

It is also possible to stop the experiment without GUI (if you know its ID), by using the batch option:

### Stop experiment with Experiment ID i29bf
# imunes -b -e i29bf
Using experiment ID 'i29bf'.
Stopping ngraphs and vimages...
100.0%                                          
Destroying links...
100.0%                                          
Shutting down vimages...
100.0%                                          
Cleanup completed in 0.979 seconds.

Automation tools

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, BER, delay, duplicate)
  • cleanupAll - shuts down all running experiments:

himage

The himage command is a wrapper:

  • for jls and jexec tools on FreeBSD:
  • for docker ps and docker exec commands on Linux

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
bin   boot.conf  etc   lib    media  opt      proc  run   srv  tmp  var
boot  dev	 home  lib64  mnt    out.log  root  sbin  sys  usr

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

### FreeBSD output
# himage pc1 ls
Error: pc1 is not a unique name.
It is used (at least) for nodes:
JID	Name    	Hostname
5234	ie418.n3	pc1
5239	id622.n3	pc1

### Linux output
# himage pc1 ls
Error: pc1 is not a unique name.
It is used (at least) for nodes:
            pc1   93d4bf80a282b...     /ie418.n3
            pc1   789d08c576555...     /id622.n3

Now you need to specify the experiment ID (i.e. @id622) you want to run the command in:

# himage pc1@id622 ls
bin        dev	 lib	mnt	 proc  sbin  tmp
boot	   etc	 lib64	opt	 root  srv   usr
boot.conf  home  media	out.log  run   sys   var

To see the list of running experiments, run the following:

# himage -l
id622 (topology.imn - Fri Aug 09 18:28:29 CEST 2019)
ie418 (topology.imn - Fri Aug 09 16:11:19 CEST 2019)

To see the list with experiment node names, run the following:

# himage -ln
id622 (pc2 pc1 router3 router2 router1)
ie418 (pc2 pc1 router3 router2 router1)

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

# himage -v pc1 # full jail or docker name
i7636.n3
# himage -n pc1 # jail or docker node name
n3
# himage -e pc1 # node experiment id
i7636
# himage -i pc1 # jail id on FreeBSD
5234
# himage -j pc1 # jail id on FreeBSD (same as -i - FreeBSD only)
5234
# himage -i pc1 # docker id on Linux
93d4bf80a282bd029495f4f78f11423d777ac4676e4d419825a3638797cd70e9
# himage -m pc1 # execute command in experiment parent (master) jail (FreeBSD only)
root@:/ #
# himage -d pc1 # path of the virtual image on the filesystem (FreeBSD only)
/var/imunes/i7636/n3
# himage -b pc1 <command> # run in detached (background) mode (Linux only)
# himage -nt pc1 <command> # run command without pseudo-tty (no-tty) - some commands need this to run in Docker (Linux only)

hcp

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

# hcp router1:boot.conf .
# hcp start_script.sh 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@i84ec:root/start_script.sh router1@i56ad:root/

vlink

The vlink command on FreeBSD is a wrapper around ngctl on FreeBSD, netgraph tool used to create links between virtual nodes in IMUNES. On Linux, it is a wrapper around tc, a tool for traffic control settings manipulation in the Linux kernel.

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.

Usage:
vlink [options] link_name[@eid]
options:
 -l                   print the list of all links
 -s                   print link status
 -r                   set link settings to default values
 -bw value            set link bandwidth (bps) <>
 -b value             set link bandwidth (bps) <>
 -BER value           set link BER (1/value) <>
 -B value             set link BER (1/value) <>
 -dly value           set link delay (us) <>
 -d value             set link delay (us) <>
 -dup value           set link duplicate (%) <>
 -D value             set link duplicate (%) <>
 -e value             specify experiment ID <>
 -eid value           specify experiment ID <>
 --                   Forcibly stop option processing
 -help                Print this message
 -?                   Print this message

To print the list of all links, run:

# himage -l
i56ad (pc1:router1 router1:router2 router2:router3 router3:pc2)

To print out the status of every parameter of the link, run:

# himage -s router1:pc1
pc1:router1@i56ad:
        No currently applied settings.

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 = i56ad):

# vlink -dup 20 router1:pc1@i56ad

If you check the status of the modified link now, it would look like this:

# himage -s router1:pc1
pc1:router1@i56ad:
        bandwidth 10Mbps
        BER 1000000
        delay 30ms
        duplicate 20%

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

# vlink -r router1:pc1@i56ad

cleanupAll

cleanupAll shuts down all running experiments:

# cleanupAll
Cleaning experiment with eid i29bf.
Using experiment ID 'i29bf'.
Stopping ngraphs and vimages...
100.0%                                          
Destroying links...
100.0%                                          
Shutting down vimages...
100.0%                                          
Cleanup completed in 0.979 seconds.
Clone this wiki locally
You can’t perform that action at this time.