runiou /

Filename Size Date modified Message
35.1 KB
80.2 KB
181.9 KB

What is runiou?

runiou is a bash shell script that simplifies the use of IOU images. With runiou is easy to build the network topology, start and stop devices, access to the devices consoles, manage externals connections to VirtualBox, Dynagen, qemu or real interfaces, and capture traffic for data analysis. In short, runiou is a tiny IOU manager.

runiou works in any console with bash installed. runiou does not provide any kind of graphical interface. All task are made in console mode. This is useful when you have remote access to the host machine through ssh and want to free all possible resources for the simulation.

runiou run in GNU/Linux, and tested briefly in NetBSD. Probably run in Solaris and in others Unix, but I don't have tested this.


What is IOU?

Cisco IOS on UNIX (IOU) is a fully working version of IOS that runs as a user mode Unix process. IOU is built as a native GNU/Linux image and run just like any other program. IOU supports all platform independent protocols and features of Cisco IOS.

With regard to functionality, it is very similar to Dynamips but it does not require nearly the resources that several virtual routers running does.

IOU allows you to build a network topology on a single PC without the need for physical routers or switchs. This is useful for validating network designs, proof-of-concept testing, and certification self-study.


IOU is a tool for Cisco internal use only. If you are not authorized by Cisco, the distribution of the IOU files is prohibited.

Please, don't askme for where to get the IOU files. Thanks.


License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.


Download

You can download the latest version of runiou in several ways.

In ZIP format:

wget https://bitbucket.org/mangelo/runiou/get/master.zip

In GZIP format:

wget https://bitbucket.org/mangelo/runiou/get/master.tar.gz

In BZ2 format:

wget https://bitbucket.org/mangelo/runiou/get/master.tar.bz2

With GIT:

git clone https://bitbucket.org/mangelo/runiou.git

Or you can browse the source code, make a feature request and report bugs in the Bitbucket repository:

https://bitbucket.org/mangelo/runiou

Dependencies

iou and runiou need several utilities and libraries to work successfully. This is a list of packages. In Ubuntu, Debian and derived, you can install the packages with apt-get install <package>.

Common packages:

  • bash
  • coreutils
  • debianutils
  • findutils
  • grep
  • gzip
  • hostname
  • kmod
  • libc-bin
  • ncompress
  • net-tools
  • procps
  • perl
  • python
  • screen
  • sed
  • tcpdump
  • telnet
  • vim-common
apt-get install bash coreutils debianutils findutils grep gzip hostname kmod libc-bin ncompress net-tools perl procps python screen sed tcpdump telnet tshark vim-common

GNU/Linux specific:

  • bridge-utils
  • syslinux-utils
  • uml-utilities
  • vlan
apt-get install bridge-utils syslinux-utils uml-utilities vlan

NetBSD specific:

  • suse_base
  • suse_compat
  • gethost
pkg_add gethost suse_base suse_compat

Libraries:

  • libssl1.0.0
  • libnet-pcap-perl
apt-get install libssl1.0.0 libnet-pcap-perl

In 64 bits systems, you need to install the support for i386 binary executables files and libraries:

dpkg --add-architecture i386
apt-get update
apt-get install lib32z1 lib32ncurses5 libssl1.0.0:i386 libtinfo5:i386 libpcap0.8:i386

IOU files:

  • i86bi-linux-<version>.bin: IOU binary files.
  • iou2net.pl: Perl script for external connections.
  • keygen.py: Python script for iourc file.
  • wrapper.bin: Binary file for remote access to consoles.
  • wrapper.py: Python script remote access to consoles (in NetBSD).

Other tasks:

  • Make a symbolic link to libcrypto.so: ln -s /usr/lib/i386-linux-gnu/libcrypto.so.1.0.0 /usr/lib/libcrypto.so.4

  • Patch the /etc/hosts file. At the end, append: 127.0.0.1 xml.cisco.com

IOUsniffer

To capture traffic in the connection between two IOU devices, you need to download, compile and install the IOUsniffer utility:

apt-get install git make gcc libpcap-dev

git clone https://github.com/Kveri/IOUsniffer.git

cd IOUsniffer

make

sudo cp iousniff CFGSCRIPTDIR/ (see the configuration section).

Check if all works:

Before to use runiou, you can check if all IOU files and utilities works well. Execute all with a normal user (no root).

  • iou2net.pl: execute this script without any parameter. You must view the help of this program.

  • keygen.py: execute this script without any parameter. You must view the license text for the machine.

  • wrapper.bin / wrapper.py / wrapper.pl: execute this script with the -h parameter. You must view the help of this program.

  • iousniff: execute this utility with the -h parameter. You must view the help of this program.

  • To test almost one IOU file:

    • Make a temporary directory: mkdir /tmp/ioucheck
    • Change to it: cd /tmp/ioucheck
    • Create an empty netmap file: touch NETMAP
    • Create a license file: /path/to/keygen.py > ~/.iourc
    • Run the IOU file with one router ID, por example 123: /path/to/i86bi-<version>.bin 123
    • You can press CTRL-C to stop and exit from IOU.
  • If IOU not start because a missing library, you can find the library dependencies with this command: ldd /path/to/i86bi-<version>.bin


install runiou

runiou is a pure and monolitic bash shell script. To install, simply copy it in any directory in the PATH. Or, if you prefer, copy it in a particular directory and make a simbolic link to runiou in any directory in $PATH (for example, /usr/local/bin): ln -s /path/to/runiou.sh /usr/local/bin/runiou. The /opt or /usr/local/bin directorys are a good choice.


Notes

  • In the present text, the term screen refers to the GNU Screen application, not the screen of the monitor.

  • Some older versions of screen only support up to 40 windows per session. Most of the new releases support up to 100 windows per session. If you want to run more than 40 or 100 devices and wish can have simultaneous access to all consoles, you need to download the screen source code, change the defined MAXWIN value, and compile it.


Configuration

All configuration in runiou is self contained in the scrconfigure function inside the runiou script. No external configuration file is needed. You can make changes to the configuration to adapt runiou to your system.

  • CFGTEMPDIRECTORY: temporary directory for files and subscripts. This directory is created by runiou. The parent directory (for example, /tmp), must allow executables files.

  • CFGBINARYDIR: is the path where are the IOU binary files (i86bi-linux-<version>.bin).

  • CFGSCRIPTDIR: is the path where are the IOU scripts and utility files: iou2net.pl, iousniff, keygen.py and wrapper.bin.

  • CFGCAPTURESDIR: directory for store the capture files when stop the capture.

  • CFGSCREENNAME: name of the main session of screen.

  • CFGCONFIGPREFIX: prefix of the exported configurations filenames.

  • CFGIOSxxxxx: filename of every IOU binary: Advance Enterprise Services, IP Base, L2 (switch) and Pagent.

  • CFGRAMxxxxx: RAM memory in Mb for every IOU binary.

  • CFGIOUKEYGEN: python script for the iourc file.

  • CFGIOUWRAPPER: wrapper for remote access to the consoles of the IOU devices.

  • CFGIOU2NET: perl script for external connections.

  • CFGIOUSNIFF: utility for capture traffic in internal connections.

  • CFGNETMAPFILE: name of the netmap file. Do not change it unless you know what are doing.

  • CFGROOTSUDOSU: method for root privilege access. 0: use sudo with the user password (typically used in Ubuntu). 1: use su with the root password (typically used in Debian).

  • CFGSCREENCOLORS: default colors for screen:

    • First char: color of the acronym.
    • Second char: color of the descriptive text.
    • Third char: color of the cursor text in the list of windows.
    • Fourth char: color of the background.
  • CFGSCREENMODE: default mode for the caption of screen.

    • splitonly: the caption text is hidden and appears only when you split a window.
    • always: the caption text is always visible.
  • CFGSCREENTEXT: default text of the caption of screen. See here for the complete string escape codes accepted by screen.

  • PATH: path for execute commands.

  • LANG: runiou need that the language must be in english for parse the result of some commands (screen, ifconfig and others). Normally, LANG="C" define the english language, but you can change it if "C" is other.

  • CFGPCAPENCAP<*>: short name (for command line parameter), value and description of encapsulations for the capture file. See the IOUsniffer documentation and here for the complete list.

  • CFGTEMPLATESTART: global template with the initial configuration of all IOU devices when boots the first time.


NETMAP file format

Normally in IOU, the netmap file are a text file with the connections between devices only. Any line which begin with the number sign # is treated as a comment, and all others lines which not are a connections are treated as an error or simply ignored.

In runiou, the netmap file contains the same connections lines and also contains information about the devices and external connections. This info always begin with the number sign # at the beginning of the line, followed by an another character which identifies the type of configuration. runiou ignores any line which not begin with the number sign followed by the configuration character. There should be no space or tab at the beginning of the line.

With this, IOU ignores the runiou configuration lines because they are treated as a comments. The configuration lines accepted by runiou must begin with any of this:

#%    define an IOU router/switch device.
#/    define an external device: command for console.
#$    define an external connection in UDP mode.
#@    define an external connection with a physical interface.
#^    define an external connection in TAP mode.
#&    define an external telnet IP for the IOU consoles.
#=    define a text visible on the caption of screen.
#+    define a separator in the list of windows in screen.
#<    define the IOU initial startup configuration commands.

See below for a detailed info.

The name of the netmap file is fixed in the IOU binary files to NETMAP (in upper case). If you wish to change it, you need:

  • Change the CFGNETMAPFILE var in runiou.

  • Patch runiou or create manually the environment variable NETIO_NETMAP with the full path and name of the netmap file.

Is more easier to use the name NETMAP without changing it.


IOU interface numbering

The IOU devices support only ethernet and serial interfaces. The ethernet interfaces are always up with link (unless you put it in the shutdown state). The serial interfaces are always up too and always are DTE. You don't need to configure the clock speed in the serial interfaces.

Every IOU device support up to 64 interfaces in total (ethernet + serial), and every module have four interfaces of the same type. This make a total of 16 modules maximum. With this, a configuration of (for example) 62 ethernet interfaces and 2 serial interfaces is invalid because it would require 17 modules. runiou detect this and inform the error.

The interfaces numbers always start with the slot 0, and the ports are from 0 to 3 (four interfaces per slot). For example, if you configure a device with 5 ethernet interfaces only, the device run with this:

Ethernet 0/0 to 0/3
Ethernet 1/0 to 1/3
Total: 8 interfaces

Another example: if you configure a device with 7 serial interfaces only, the device run with this:

Serial 0/0 to 0/3
Serial 1/0 to 1/3
Total: 8 interfaces

Note that the number of slot always start at 0.

If you configure a device with mixed interfaces (ethernet + serial), the first slots always are for the ethernet interfaces, and the last slots are for the serial interfaces.

For example, if you configure a device with 5 ethernet interfaces and 7 serial interfaces, the device run with this:

Ethernet 0/0 to 0/3
Ethernet 1/0 to 1/3
Serial 2/0 to 2/3
Serial 3/0 to 3/3

If later you want to add 5 more ethernet interfaces (total: 5 + 5 = 10 ethernets and 7 + 0 = 7 serials), the device run with this:

Ethernet 0/0 to 0/3
Ethernet 1/0 to 1/3
Ethernet 2/0 to 2/3
Serial 3/0 to 3/3
Serial 4/0 to 4/3

The slot of the serial interfaces has been changed. Be careful with this. When the device boots, the startup config have the old interfaces numbers and not apply the configuration to the new interfaces numbers.


Device id

The device id is a decimal number between 1 and 1023 which univocally identifies each device. You must assign an unique device id to every device in the lab. This number is used by IOU for make the connections between interfaces (defined in the netmap file) and to create the nvram file of the device.


NVRAM files

The nvram file stores the startup configuration of the IOU devices in a binary form. The name of the file are always nvram_<device id>, with the device id padded with zeros and five digits. For example, the nvram file of the device id 72 is nvram_00072.

L2 switchs also generates the vlan database info in a file called vlan.dat-<device id>, with device id padded with zeros and five digits too.

You can make a full backup and/or distribute the actual state of the lab by copying the netmap, nvram and vlan.dat files: the netmap file for the device definitions and connections (lab topology) and the nvram and vlan.dat files for the configuration of every IOU device in the lab.


Connections between devices

The connections between devices defines how the devices are interconnected to each other. Every connection must have your own line and you can't define two separated connections in the same line.

The syntax is simple:

<device id A>:<slot A>/<port A>   <device id B>:<slot B>/<port B>

For example, to connect the interface 0/1 of the device id 123 with the interface 2/3 of the device id 543, the line is:

123:0/1  543:2/3

The order does not matter, this is the same connection:

543:2/3  123:0/1

The separator between devices can be spaces, tabs or a combination of both.

In the case to you want to connect three or more interfaces with each other like an ethernet hub, you must configure the connection with the three or more <device id>:<slot>/<port> in the same line. For example:

123:0/1  543:2/3  234:3/1  45:8/3  874:13/2

This multiconnection only makes sense with ethernet interfaces, for example, in a LAN connection without an IOU switch. The serial interfaces are point to point by nature (one to one). If you make a multiconnection of three or more serial interfaces, IOU don't show any error, but the functioning is unpredictable.

Please note that in a multipoint connection you can not capture traffic. If you need a multipoint connection and need to capture traffic, you must add an IOU switch.

Also, IOU does not show error when you connect an ethernet interface to a serial interface. In IOU this connection is valid but it does not work in the lab because the encapsulations are different.

Note that you do not need to specify the interface type in the connection. The slots/ports number of the interfaces never are overlapped, which makes each interface has your own and unique slot/port number.


Define an IOU router/switch device

An IOU device is a virtual router or switch provided by one of the IOU binary files.

The syntax for an IOU device is:

#%  <device ID>  <acronym>  <ios>  <ethernet>  <serial>
  • The device id of the device (1 <= ID <= 1023).

  • The acronym is a short name which appears in the list of windows in screen when you access to the console device, the name to start and stop the device, and so on. The device id is the real name for IOU, and the acronym is an alias for humans. The acronym is only one word, no spaces allowed, and is case sensitive.

  • The ios identifies which one of the four configured files with CFGIOSxxxxx run this device. The accepted values are:

    • advipsrv: Advance IP Services.
    • ipbase: IP Base
    • l2: Switch
    • pagent: Pagent
  • The quantity of ethernet interfaces in a decimal number between 0 and 64.

  • The quantity of serial interfaces in a decimal number between 0 and 64.

The quantity of ethernet and serial interfaces is the quantity of ports, not the quantity of slots.

For example, if you want a lab with one router with advipsrv, one router with ipbase and one switch, you can write this in the netmap file:

#%  100     ROUTER1     advipsrv    1   0
#%  101     ROUTER2     ipbase      1   0
#%  102     LANSWITCH   l2          2   0

With this, you have defined the three IOU devices.


Define an external device

An external device is a real hardware device connected to the lab through a connection in interface mode or a virtual device (not IOU) connected to the lab through a connection in udp or tap mode (see below). Because the real or external virtual devices interacts with the IOU virtual lab, you can manage these devices using a specific command integrated with all IOU devices in the lab.

For example, if you have connected a real firewall to the lab, and you can access to the firewall console through a rs232 multiplexer with an IP address and port, you can define this firewall in the netmap file as external device with the command to access to the console. With this, the firewall appears in the list of windows in screen and you can select and manage it. Or, for example, if the real firewall only can be accessed through ssh, you can configure it in the netmap file.

The syntax is:

#/  <device ID>  <acronym>  <command>  <optional args>
  • The device id of the device. In real devices, this id must be equal or greater than 1, but is not limited to 1023 (may can be greater).

  • The acronym is a short name which appears in the list of windows in screen when you access to the console device. The acronym is only one word, no spaces allowed and is case sensitive.

  • The command and arguments to execute when you need to access to the the console of the external device.

For example, if your external firewall console is accessed through a rs232 multiplexer with IP address 192.168.25.8 and port 2035, you can define this:

#/  2134   FIREWALL1  telnet 192.168.25.8 2035

If the firewall can be accessed through ssh to the IP address 192.168.75.89, you can define this:

#/  2134   FIREWALL1  ssh -l user -2 -c 3des -p 22 192.168.75.89

With this, you can integrate a real device to the consoles management in screen.


Define a connection in UDP mode

A connection in UDP mode is a connection between an IOU device and another virtual not IOU device, such a virtualbox / qemu virtual machine or a Dynagen / GNS3 virtual router. This connection is made by runiou through the iou2net.pl script. This connection type is also called UDP Tunnel.

The syntax is:

#$  <device ID>  <local port>  <remote ip address>  <remote port>
  • The device id of the connection (1 <= ID <= 1023).

  • The local UDP port (1024 <= port <= 65535).

  • The remote IP address.

  • The remote UDP port (1024 <= port <= 65535).

You must define an UDP port in the local and the remote machine. The remote IP address can be an plain IP address, a hostname (resolved via /etc/hosts) or a domain name (resolved via dns).

For example, consider this topology: you need to connect an ethernet interface of an IOU router with a virtual machine running in virtualbox. The info is:

  • IOU router:
    • ID: 637
    • Interface: ethernet 2/1
    • Running in the machine 192.168.0.32
  • Virtual machine (virtualbox):
    • Interface: eth3
    • Running in the machine 192.168.0.45

You need to define some parameters:

  • Connection id: use a free id, for example, id = 147

  • Free UDP port in the machine 192.168.0.32 (local port): for example: 8888

  • Free UDP port in the machine 192.168.0.45 (remote port): for example: 9999

With all these data, you can define the connection. In the netmap file, you can write these two lines:

#$   147   8888   192.168.0.45   9999
637:2/1  147:0/0

With the first line, you have defined a fake IOU device with id 147 (really is iou2net), and configured iou2net for listen in the port 8888 and transmit to 192.168.0.45 port 9999 (the remote machine with virtualbox).

In the second line, you have defined the connection between the IOU router (637) to the fake device (iou2net, 147). In the iou2net side of the connection, the port can be any valid slot/port (0 <= slot <= 15 and 0 <= port <= 3). runiou ignores the slot/port and internally rewrite it to 0/0 needed by iou2net.

On the other hand, you must configure virtualbox for use UDP tunnels in the machine 192.168.0.45:

Network:
  Adapter N:
    Connected to:   Generic Driver
    Name:           UDPTunnel
    Properties:     dest=192.168.0.32
                    dport=8888
                    sport=9999

With this, the workflow of the data is:

  • The IOU router 637 transmit an ethernet frame in the ethernet interface 2/1.

  • This interface is connected to the device 147 (iou2net) interface 0/0.

  • iou2net.pl get the ethernet frame.

  • iou2net.pl is configured in UDP mode. Take the ethernet frame, encapsulate it in an UDP packet, and transmit it to 192.168.0.45 port 9999.

  • virtualbox receives this UDP packet, decapsulate it, and send it to the virtual machine in eth3 interface.

As user, you only must write the two lines in the netmap file, configure the network adapter in virtualbox and runiou does the rest.

In qemu, the syntax of the start command is:

-net nic,vlan=N,macaddr=xx:xx:xx:xx:xx:x \
-net socket,vlan=N,udp=<remote ip>:<remote port>,localaddr=:<local port>

From the above example, the start command for qemu is:

-net nic,vlan=N,macaddr=xx:xx:xx:xx:xx:x \
-net socket,vlan=N,udp=192.168.0.32:8888,localaddr=:9999

In Dynagen, the syntax of the net file is:

<interface> = NIO_udp:<local port>:<remote ip>:<remote port>

From the above example, the Dynagen configuration must be:

[router R]
    <interface> = NIO_udp:9999:192.168.0.32:8888

In GNS3, this can be made with the cloud connection. In the NIO UDP tab of the Cloud Configuration you can configure the connection. From the above example:

* Local port: 9999
* Remote host: 192.168.0.32
* Remote port: 8888

In another software which support UDP tunnels, please consult the manual about how to configure it.


Define a connection in interface mode

A connection in interface mode is a connection between an IOU device and a real device. This connection is made by runiou through the iou2net.pl script. To connect to a real device, one (or more) real ethernet interface in the host machine is used.

The syntax is:

#@  <device id>  <interface>
  • The device id of the connection (1 <= ID <= 1023).

  • The interface in the host machine.

The interface can be a physical interface (like eth1) or a subinterface (like eth3.123). In the last case, the ethernet frames are tagged with a 802.1q vlan.

For example, if you need to connect an ethernet interface of an IOU router with a real firewall connected in an ethernet interface in the host machine:

  • IOU router:
    • ID: 258
    • Interface: ethernet 3/1
  • Real firewall:
    • Connected to the interface eth2 in the host machine.

You need to define one parameter:

  • Connection id for the eth2 interface in the host machine: use a free id, for example, id = 321

With all these data, you can define the connection. In the netmap file, you can write these two lines:

#@  321  eth2
258:3/1  321:0/0

With the first line, you have defined a fake IOU device with id 321 (really is iou2net.pl), and configured iou2net.pl for bridge with the interface eth2 in the host machine.

In the second line, you have defined the connection between the IOU router (258) to the fake device (iou2net.pl, 321). In the iou2net.pl side of the connection, the port can be any valid slot/port (0 <= slot <= 15 and 0 <= port <= 3). runiou ignores the slot/port and internally rewrite it to 0/0 needed by iou2net.

With this, the workflow of the data is:

  • The IOU router 258 transmit an ethernet frame in the ethernet interface 3/1.

  • This interface is connected to the device 321 (iou2net.pl) interface 0/0

  • iou2net.pl get the ethernet frame.

  • iou2net.pl is configured in interface mode. Take the ethernet frame, and transmit it through the interface eth2 of the host machine.

As user, you only must write the two lines in the netmap file and runiou does the rest.

You can use any ethernet interface in the host machine. The main interface (eth0, eth1, eth2, etc) is automatically bring up before use. If you configure a connection with a subinterface, runiou automatically load the 8021q module (only in GNU/Linux), add the vlan to the ethernet interface, and brings up the subinterface created before the start of the connection. When you stop the connection, runiou deconfigure and delete the subinterfaces only if they not have an IP address configured.

For example, you can define multiple subinterfaces with 802.1q vlans:

#@  122  eth2.544
#@  123  eth2.456
#@  124  eth2.987

Internally, runiou is a little more complex with the interface connections. In GNU/Linux, with iou2net.pl configured directly to the physical interface, you can not pass 802.1q vlans from the IOU device to the real device. For this reason, runiou creates two virtual interfaces in the host machine: a tap interface and a bridge interface (only in GNU/Linux).

So, the complete data workflow for connections in interface mode is (from the above example):

  • The IOU router 258 transmit an ethernet frame in the ethernet interface 3/1.

  • This interface is connected to the device 321 (iou2net.pl) interface 0/0

  • iou2net.pl get the ethernet frame.

  • iou2net.pl is configured in TAP mode. The TAP interface is rioutapext0258.

  • The TAP interface rioutapext0258 is part of a bridge interface called rioubrgext0258.

  • Finally, the output interface eth2 is the other part of the bridge interface rioubrgext0258.

In summary, the data flow is: IOU router --> iou2net.pl --> TAP interface --> bridge interface --> host ethernet interface.

With this, you can pass 802.1q vlans from the IOU device to the real device. runiou configure and deconfigure automatically the TAP and Bridge interfaces when you start or stop the connections. Because to the creation and deletion of this interfaces, runiou need root privileges to complete this job. You must configure the CFGROOTSUDOSU correctly to have root access. Please, see here for a complete example of this method applied manually.

In non GNU/Linux, the iou2net is configured to connect directly to the physical interface (without tap and bridge interfaces).

In practice, is convenient (and almost always necessary) to use a dedicated interface in the host machine to connect the IOU device to an external real device. For example, in Ubuntu, the Network Manager interferes with the external connection: the connection is established without error, but the traffic not pass from the IOU device to the real device. In this scenario, you must disable the Network Manager for the dedicated interface and bring up manually the interface with ifconfig.


Define a connection in tap mode

A connection in tap mode is a connection between an IOU device and a tap interface in the host machine. This connection is made by runiou through the iou2net.pl script. With this, you can connect an IOU device with the host machine having bidirectional connectivity.

The syntax is:

#^  <device id>  pre-up     command [args...]
#^  <device id>  post-up    command [args...]
#^  <device id>  pre-down   command [args...]
#^  <device id>  post-down  command [args...]
  • The device id of the connection (1 <= ID <= 1023).

  • When execute the command:

    • pre-up: execute the command before the tap interface creation.
    • post-up: execute the command after the tap interface creation.
    • pre-down: execute the command before the tap interface deletion.
    • post-down: execute the command after the tap interface deletion.
  • The command (and optional arguments) to execute.

At least one command is mandatory. If you not want to execute any command, specify the /bin/false command in any pre or post keyword.

The commands are executed with root privileges in order in which are defined. There may be multiple commands for every pre and post keyword in every connection.

The <TAP> keyword is replaced by the name of the tap interface generated by runiou. The name of the tap interface is composed with the "rioutapint" string and the zero padded ID with four digits (for example: rioutapint0003, rioutapint0529).

In the iou2net.pl side of the connection, the port can be any valid slot/port (0 <= slot <= 15 and 0 <= port <= 3). runiou ignores the slot/port and internally rewrite it to 0/0 needed by iou2net.pl.

runiou will ask for the root or user password when start or stop these connections (need root privileges).

For example, you can create two tap interface connections:

#^  766     post-up     ifconfig <TAP> 192.168.45.1 netmask 255.255.255.0
#^  766     post-up     route add -net 172.16.45.0 netmask 255.255.255.0 gw 192.168.45.2
#^  766     post-up     iptables -I INPUT 1 -s 172.16.45.0/24 -i <TAP> -j ACCEPT
#^  766     post-down   iptables -D INPUT -s 172.16.45.0/24 -i <TAP> -j ACCEPT

#^  48      post-up     ifconfig <TAP> 192.168.99.1 netmask 255.255.255.0
#^  48      post-up     route add -net 10.20.30.0 netmask 255.255.255.0 gw 192.168.99.2
#^  48      post-up     iptables -I INPUT 1 -s 10.20.30.0/24 -i <TAP> -j ACCEPT
#^  48      post-down   iptables -D INPUT -s 10.20.30.0/24 -i <TAP> -j ACCEPT

21:0/0      766:0/0
32:0/0       48:0/0

With this, the tap interfaces named rioutapint0766 and rioutapint0048 are created, the commands are executed, and the tap interfaces are connected to the IOU devices with id 21 and 32.

Another example is if you don't want to execute any command before or after the tap interface is created. In this case, you can specify the /bin/false command:

#^  381     post-up     /bin/false

The /bin/false command is executed, but does nothing.


Define a machine which run IOU

Sometimes you need to build a lab with many devices. In this scenario, with more free RAM memory, the IOU devices runs better. If the host machine is dedicated for the lab, you can make some tricks to free more RAM memory and CPU usage: disable the graphical interface, unload unused modules, kill unnecesary daemons, activate aditional swap file, and so on.

Another method to free some RAM memory is make the telnet to the consoles of the IOU and external devices in another machine. With this, the RAM memory and CPU used by screen for the history buffers of all consoles are freed for IOU usage.

For example, if you have two host machines dedicated to the lab, one with all IOU devices and the other with a few of lightweight virtual machines, you can make the telnet / ssh from the second machine to free RAM memory and CPU usage from the first machine.

With this option you can do that. The syntax is:

#&  <ip address>

The IP address can be a plain IP address, a hostname (resolved by /etc/hosts) or a domain name (resolved by dns).

For example, suppose that you have two host machines: one high-end server and one low-end desktop. You want to run the IOU lab in the server, and free the RAM memory and the CPU usage as much as possible. For this, you choose to run screen with the telnet to the IOU and external devices consoles in the desktop machine.

For this, in the netmap file you can define the IP address of the server which run the IOU lab. For example:

#&  192.168.56.74

Now, you can copy the netmap file from the server to the desktop. The lab is started and stopped from the server, but the telnet commands for console access works from the desktop machine. The lab can not be started nor stopped from the desktop machine. In the desktop machine, the list command show the IOU devices as 'remote'. Of course, you need to have installed runiou in the desktop machine.


Define the caption of screen

With this option, you can define a small text which appears in the caption of all screen windows. This is useful when you need to show some info such the lab name, the customer name, the status of the machine, or other relevant information.

The syntax is one of the following lines:

<none>
#=
#= Text
#= {WXYZ}
#= {WXYZ} Text
#= splitonly "TU" "V"
#= always "TU" "V"

The first method is not write an #= entry in the netmap file. When runiou not detect a caption text, by default the caption is hidden, and appears when you split a window in screen. In this case, the caption shows the acronym of the actual device with the default colors.

With the second method (#= with empty text), the caption is always visible and show the acronym of the actual device at the left bottom with the defaults colors.

With the third method, the caption is always visible and show the acronym of the actual device at the left bottom and the descriptive text at the right bottom with the defaults colors.

With the fourth method, the caption is always visible and show the acronym of the actual device at the left bottom with the custom colors.

With the fifth method, the caption is always visible and show the acronym of the actual device at the left bottom and the descriptive text at the right bottom with the custom colors.

With the sixth method, the caption is hidden and appears when you split a window. The cursor in the list of window in screen appears with the "TU" colors and the caption text is the "V" text. "V" can be any string escapes supported by screen.

With the seventh method, the caption is always visible. The cursor in the list of windows in screen appears with the "TU" colors and the caption text is the "V" text. "V" can be any string escapes supported by screen.

For the fourth and fifth method, the "WXYZ" colors are one character by color:

  • W: color of the acronym text.
  • X: color of the descriptive text.
  • Y: color of the text in the cursor of the windows list.
  • Z: color of the background.

For the sixth and seventh method, the "TU" colors are one character by color:

  • T: color of the text in the cursor of the windows list.
  • U: color of the background in the cursor of the windows list.

For the sixth and seventh method, the "V" text can be any text recognized by screen, including the string escapes.

Please, see here for a complete list of strings recognized by screen.

The one chars colors recognized by screen are:

  • k: black
  • r: red
  • g: green
  • y: yellow
  • b: blue
  • m: magenta
  • c: cyan
  • w: white
  • d: default color
  • .: leave color unchanged

The capitalized versions of the letter specify bright colors.

The string escapes recognized by screen are:

  • %: the escape character itself
  • a: either am or pm
  • A: either AM or PM
  • c: current time HH:MM in 24h format
  • C: current time HH:MM in 12h format
  • d: day number
  • D: weekday name
  • f: flags of the window
  • F: sets %? to true if the window has the focus
  • h: hardstatus of the window
  • H: hostname of the system
  • l: current load of the system
  • m: month number
  • M: month name
  • n: window number
  • s: seconds
  • S: session name
  • t: window title
  • u: all other users on this window
  • w: all window numbers and names. With - qualifier: up to the current window; with + qualifier: starting with the window after the current one.
  • W: all window numbers and names except the current one
  • y: last two digits of the year number
  • Y: full year number
  • ?: the part to the next %? is displayed only if a % escape inside the part expands to a non-empty string
  • :: else part of %?
  • =: pad the string to the display's width (like TeX's hfill).
  • {: attribute/color modifier string terminated by the next }

Examples:

#=
#= Foo Bar Lab 1
#= {BbBk}
#= {kKkg} Training for the company Foo Bar
#= {RRRk} Foo Bar presentation
#= always    "bK" "%3n %t%? @%u%?%? [%h]%?%=%c"
#= splitonly "bK" "%{= kc}%H–%n (%t)%-5=%{= .m}%0c"
#= always    "bK" "Host: %H Date: %D-%M-%Y: Load: %l"
#= splitonly "Ry" "%{= kc}%H (system load: %l)%-21=%{= .m}%D %d.%m.%Y %0c"
#= always    "bK" "%{= gk}| %H | %{+b .y}%l%{-} | %D %M %d %C | %{+b g}%t (%n)%{-}"
#= splitonly "bK" "%{bw}[%H] [%?%-Lw%?%{wb}%n*%f %t%{bw}%?%+Lw%?]%=%{bw} [%1`] [%c:%s] [%l]"
#= always    "bK" "%{= kG}[ %{G}%H %{g}][%= %{= kw}%?%-Lw%?%{r}(%{W}%n*%f%t%?(%u)%?%{r})%{w}%?%+Lw%?%?%= %{g}][%{B} %d/%m %{W}%c %{g}]"
#= splitonly "kw" "%{b kw}%H %{r} %{w}| %{g}%c %{w}| %{y}%d.%m.%Y %{w}| %{g}%l %{w}| %{-b kw}%u %-Lw%{= rW}%50> %n%f %t %{-}%+Lw%<"
#= always    "bK" "%m/%d %02c:%s %?%E%{= .Y}%:%{= .g}%?%H%{-} %L=%-w%45L>%{= g.}%n %t%{-}%+w %-17<%=%{= .y}(%l)"

Another examples: here, here and here


Define a separator in screen windows list

Sometimes (again) you need to build a lab with many devices. In the list of windows in screen appears all IOU and external devices in the same order in which you have defined it in the netmap file. screen not handle the concept of grouping windows (windows grouped in a hierarchical order). This can be solved partially with nested screens, but is complicated to handle, specially when you split two or more windows. To make matters worse, screen not have the feature to search windows by the name (as have tmux). In this scenario, if you have too many devices in the list, sometimes is confusing to find any device, specially if the acronyms are similar.

In these cases, you can define in the netmap file some separators in the list of windows in screen. The syntax is:

#+  <device id>  <separator text>
  • The device id of the device which have the separator (ID >= 1).

  • The separator text, can contains spaces and symbols.

The separator text appears at the right of the device name in the list of windows in screen right justified to the width of the longest separator text. The space between the acronym and the separator text is filled with the first character of the separator text.

For example, if you have four devices, two for a MPLS backbone and the others two for the CPE customers and you wish to separate them, you can define this in the netmap file:

#%  101    MPLS1    advipsrv    3   0
#%  102    MPLS2    advipsrv    3   0
#%  103    CUST1    advipsrv    2   0
#%  104    CUST2    advipsrv    2   0

#+  101    - Backbone
#+  103    =[ Customers ]==

In this example, the list of windows in screen looks like this:

  0 MPLS1 ------------ Backbone       $
  1 MPLS2                             $
  2 CUST1 ======[ Customers ]==       $
  3 CUST2                             $

The separator text is right justified, and filled with the first character of the text.

Internally, runiou change the window title of screen (name) to the acronym of the device plus the separator text. This brings the undesired effect in the caption of windows in screen: the device acronym is now the acronym plus the separator text. For example, when you select the CUST1 device, the caption of the window looks like this:

CUST1 ======[ Customers ]==       [Lab training for Foo Bar Inc. (C) 2013]

Define the initial startup configuration for IOU devices

When you have many IOU devices, the initial base configuration is tedious. You need to configure the same commands to all IOU devices: hostname, banners, console permissions, logging, and so on. runiou offers a template configuration for all IOU devices. This configuration is applied when de IOU device boot the first time and still does not have a nvram file. This template contains the base configuration for all IOU devices.

There are a global template defined in the CFGTEMPLATESTART constant in the scrconfigure function of runiou script. You can modify this template anytime. You can also define a particular template for the lab in the NETMAP file, and you can combine both templates, the global and the particular, which are applied to all IOU devices. When you start a device which not have a nvram file, runiou get the template, create a nvram file, and store the template in this nvram file. When the IOU device start, it have a valid startup configuration.

The syntax is:

#<  global
#<  command

You must define only one command by line, and comments (with #) are not allowed, they are taken as part of the command. You not need to enter the 'configure terminal' or the 'end' command. The 'command' can be any valid command configuration in IOS, and is stored in the nvram file without syntax checking. The 'global' keyword is replaced by the global template in place.

The commands are parsed from top to down, inserting the global template when the 'global' keyword appears. The 'global' keyword can appears multiple times. If the length of the final configuration is greather than 62Kb, the configuration is compressed and the command 'service compress-config' is inserted.

The %H keyword is replaced by the acronym of the device. The %D keyword is replaced by the device id.

For example:

#<  global

apply only the global template. Other example:

#<  hostname %H-%D
#<  banner motd $
#<  Welcome to %H [%D]
#<  $

apply only the particular template for the lab. And for example:

#<  global
#<  hostname %H-%D
#<  banner motd $
#<  Welcome to %H [%D]
#<  $

apply both templates in the top - down order.


Command line options

When you run runiou without any parameter, this brief help is displayed:

  start:               start all iou devices and external connections.
  stop:                stop all iou devices and external connections.
  rtstart ACR [ACR]:   start some iou devices.
  rtstop ACR [ACR]:    stop some iou devices.
  cnstart ID1 [ID2]:   start some external connections.
  cnstop ID1 [ID2]:    stop some external connections.
  cndeconfigure:       force deconfigure unused tap, bridge and eth interfaces.
  cnhelp:              help for all external connections.
  show:                show information about the netmap file.
  list:                equivalent to show.
  telnet:              console to all iou and external devices.
  console:             equivalent to telnet.
  rttelnet ACR [ACR]:  console to some iou devices and/or external devices.
  rtconsole ACR [ACR]: equivalent to rttelnet.
  netmap:              create a template netmap file in the current dir.
  captureon DEV SL/PRT TYPE [DESC]: start capture traffic (tcpdump/tshark).
  captureoff DEV:      stop capture traffic.
  capturelist:         show the list of captures.
  capturehelp:         show a brief help for capture.
  export:              export all iou devices startup-config.
  rtexport ACR [ACR]:  export some iou devices startup-config.
  rtimport ACR FILE:   import startup-config to an iou device.
  version:             show version.
  help:                show this help.

start

With this command, you can start the complete lab: all IOU devices and all connections. If you have configured any interface or tap connection, runiou ask for user password (with sudo) or root password (with su) to start these connections. The devices and connections are started in alphabetical order.

Example:

runiou start

stop

With this command, you can stop the complete lab: all IOU devices and all connections. If you have configured any interface or tap connection, runiou ask for user password (with sudo) or root password (with su) to stop these connections. The devices and connections are stopped in alphabetical order.

Before stop any device or connection, runiou ask if you are sure. You must respond YES in upper case before a timeout of 15 seconds. If you do not respond anything or other text than YES, the stop is canceled.

Example:

runiou stop

rtstart ACR [ACR]

With this command, you can start some IOU devices specified in the command line by acronym. The devices are started in alphabetical order.

If you specifies two or more times the same device, runiou ignores the duplicated devices and not try to start the same device two or more times in the same command.

If you specifies an unknown acronym, runiou inform the error but not cancel the start process.

Keep in mind that the acronyms are case sensitives.

Example:

runiou rtstart MPLS1 MPLS2 CPE1 CPE2

rtstop ACR [ACR]

With this command, you can stop some IOU devices specified in the command line by acronym. The devices are stopped in alphabetical order.

If you specifies two or more times the same device, runiou ignores the duplicated devices and not try to stop the same device two or more times in the same command.

If you specifies an unknown acronym, runiou inform the error but not cancel the stop process.

Keep in mind that the acronyms are case sensitives.

You can not stop any IOU device while is capturing traffic.

Example:

runiou rtstop MPLS1 MPLS2 CPE1 CPE2

cnstart ID1 [ID2]

With this command, you can start some external udp / interface / tap connections specified in the command line by connection id. The connections are started in alphabetical order.

If you specifies two or more times the same connection id, runiou ignores the duplicated connections and not try to start the same connection two or more times in the same command.

If you specifies an unknown connection id, runiou inform the error but not cancel the start process.

If you want to start any interface or tap connection, runiou ask for user password (with sudo) or root password (with su) to start these connections.

Example:

runiou cnstart 121 122 123

cnstop ID1 [ID2]

With this command, you can stop some external udp / interface / tap connections specified in the command line by connection id. The connections are stopped in alphabetical order.

If you specifies two or more times the same connection, runiou ignores the duplicated connections and not try to stop the same connection two or more times in the same command.

If you specifies an unknown connection id, runiou inform the error but not cancel the stop process.

If you want to stop any interface or tap connection, runiou ask for user password (with sudo) or root password (with su) to stop these connections.

You can not stop any connection while is capturing traffic.

Example:

runiou cnstop 121 122 123

cndeconfigure

Sometimes, any software can fail. In the case of the interface or tap connections, if the iou2net.pl process crash (or you manually kill them), the tap and bridge interfaces are already configured and up (only in GNU/Linux). When you try to start again the interface connection, runiou try to recreate the tap and bridge interfaces. In this case, the connection start correctly, but the lab not work, the traffic not exit the physical interface.

To solve this problem, you can run runiou with the cndeconfigure command. runiou ask for the user password (with sudo) or the root password (with su) and deconfigure, bring down and delete the tap, bridge and the physical subinterface (if they not have an IP address configured). Then, you can start the interface connection again and the lab work correctly.

Other method is manually deconfigure, bring down and delete the tap and bridge interfaces. Or, if you can, reboot the system to lose these interfaces.

Example:

runiou cndeconfigure

cnhelp

With this command, you can get a brief help about how to configure the external udp connections in virtualbox or qemu to make the connections in the lab. If you have configured any udp connection, this command show a brief help for every udp connection.

The info is in the point of view from virtualbox or qemu. The remote IP are the IP of the host machine which run IOU, the destination port is the local port defined in the netmap file, and the source port is the remote port defined in the netmap file.

Example:

runiou cnhelp

virtual device #41:
  for virtualbox:
    in network adapter:
        connected to:   Generic Driver
        name:           UDPTunnel
        properties:     dest=172.28.245.6
                        dport=9001
                        sport=9002
  for qemu:
    -net nic,vlan=N,macaddr=xx:xx:xx:xx:xx:x \
    -net socket,vlan=N,udp=172.28.245.6:9001,localaddr=:9002

show / list

With this command, you can view all the configuration in the netmap file, except the connections between IOU devices. Also, this command show the status of the devices and external connections: running, stopped or remote, the console command for every device (in case you want to enter manually), the configuration of the external connections, the current traffic captures and the info of the lab.

Example:

runiou show

telnet / console

With this command, you can access to the console of all IOU devices plus the console or management of the external devices through screen.

To reattach to a detached screen session, you simply type at the shell prompt:

screen -r

If you have two or more screen sessions actives, to reattach to the lab session, type at the shell prompt:

screen -r runiou

The name runiou is configured in the CFGSCREENNAME var, you can change it by the text of your choice.

Example:

runiou telnet

If there are an active session of screen and you execute the runiou telnet command, runiou detect this and not try to create a new screen session. In this case, runiou check for the active consoles, try to recreate the dead connections to the consoles, and reattach to the original session.

rttelnet / rtconsole ACR [ACR]

With this command, you can access to the console of some IOU devices and/or the console or management of the external devices through screen. The devices must be specified with the acronym. Keep in mind that the acronyms are case sensitive.

If you specifies two or more times the same device, runiou ignores the duplicated devices and not try to enter to the console of the same device two or more times in the same command.

If you specifies an unknown acronym, runiou not inform the error and not cancel the process.

If the device already have an active console connection, runiou not try to make other connection, not inform this error and not cancel the process.

If you want to create a new and freshly connection, you must kill the old console connection first.

Example:

runiou rttelnet CPE1 CPE2 MPLS1 MPLS2

netmap

With this command, runiou write a netmap file in the working directory with a brief help of every command and a little example. If the netmap file already exist, runiou show an error and cancel the operation.

Example:

runiou netmap

captureon

With this command, you can start a traffic capture in one interface of an IOU device to examine with tshark, wireshark, tcpdump or any software compatible with the pcap files. The syntax is:

runiou captureon DEV SLOT/PORT TYPE [DESC]
  • DEV: acronym of the IOU device in which capture the traffic.

  • SLOT/PORT: slot/port of the IOU device in which capture the traffic.

  • TYPE: any valid encapsulation type (see below).

  • DESC: an optional description of the capture. Must be a word or a phrase without spaces nor symbols, limited to 24 chars.

The encapsulation type must be any word configured in runiou. To see the accepted encapsulations types, you must run the runiou capturehelp command. If you specify a wrong encapsulation type, runiou and iousniff do not show any error, but tshark or wireshark can not properly decode the capture file and show wrong data. The most commonly used types are eth, ppp and fr.

When you capture traffic in a interface of an IOU device connected to an external interface or tap connection, runiou ask for the root password (with su) or the user password (with sudo) for restart the connection.

Due to the nature of the of how iousniff works, you can not capture traffic in two or more interfaces of the same device at the same time. Neither you can not capture traffic in any interface on the IOU device connected to the first IOU device which capturing traffic.

For example, if your topology is like this (all IOU devices):

111:0/0     222:0/1
222:0/0     333:0/1

If you start a capture in 111:0/0, both IOU devices (111 and 222) are busy in the capture process, and you can not start another capture in 222:0/0 at the same time.

runiou can not start a capture in a interface with a multipoint connection. If you need a capture in that interface, you must use an IOU switch.

Example:

runiou captureon MPLS1 0/2 eth

captureoff

With this command, you can stop any running traffic capture. After stop the capture, runiou rename and move the capture file to the configured directory.

The syntax is:

runiou captureoff DEV
  • DEV: acronym of the IOU device in which stop capture the traffic.

For example:

runiou captureoff MPLS1

The name of the final capture file is:

<CAPTURE_DIR>/cap-<ACRONYM>-<SLOT>-<PORT>-<DATE>-<TIME>-<DESCRIPTION>.pcap

Where:

* CAPTURE_DIR: Directory of stored captures (CFGCAPTURESDIR).
* ACRONYM: Acronym of the IOU device.
* SLOT: Slot of the capture.
* PORT: Port of the capture.
* DATE: Date when the capture start in YYYYMMDD format.
* TIME: Time when the capture start in HHMMSS format.
* DESCRIPTION: Optional description text.

For example, if you start a traffic capture in the device R4 interface 0/2 without a description, at 02 Jan 2014 18:05:34 and your user ID in the GNU/Linux system is 1004, the final capture file is renamed and moved to:

/tmp/runiou1004/captures/cap-R4-0-2-20140102-180534.pcap

If in the start of the capture you specify a description (for example, TestMPLS), the final capture file is moved and renamed to:

/tmp/runiou1004/captures/cap-R4-0-2-20140102-180534-TestMPLS.pcap

This name is displayed when the capture stop. And then, you can open the capure file with tshark, wireshark, tcpdump, or any other software which support pcap files.

capturelist

With this command, you can see all captured files in the capture directory.

Example:

runiou capturelist

capturehelp

This command show a brief help about the captureon command. This help shows:

  • The options for the captureon command.

  • A brief example of the syntax.

  • The encapsulation types configured and accepted by runiou.

If you need to specify your own encapsulation type, you must edit runiou and append the new type in the CFGPCAPENCAPxxx variables.

Example:

runiou capturehelp

export

With this command, you can export the startup configuration of all IOU devices to a plain text files. See the rtexport command for a detailed information.

Example:

runiou export

rtexport ACR [ACR]

With this command, you can export the startup configuration of some IOU devices to a plain text files. The syntax is:

runiou rtexport DEV1 [DEV2] [DEV3] [...]
  • DEV: acronym of the device(s).

If you specifies two or more times the same device, runiou ignores the duplicated devices and not try to export the startup config of the same device two or more times in the same command.

If you specifies an unknown acronym, runiou inform the error and not cancel the process.

runiou reads the nvram file of every IOU device to export the startup configuration. If any IOU device not have your nvram file, runiou inform the error and not cancel the process.

Because runiou reads the nvram file of the IOU device, it is not necessary that the IOU device is running.

The text configurations files have this name convention:

config-<ACRONYM>-<DATE>-<TIME>.txt

Where: ACRONYM: acronym of the device. DATE: date of the start of this command in YYYYMMDD format. * TIME: time of the start of this command in HHMMSS format.

Some restrictions apply:

  • If you have two machines, one for run the IOU devices and the other for the telnet to the consoles with screen, you must execute this command in the machine in which run the IOU devices.

  • The text configurations files are stored in the machine which run the IOU devices and in the same directory of the IOU nvram and netmap files.

  • runiou obtain the text files from the nvram files of the IOU devices. You must write the running config to the startup config of all IOU devices before export the configurations with this command.

Example:

runiou rtexport CPE1 CPE2 MPLS1 MPLS2

rtimport

With this command, you can import a startup configuration in a plain text file to the nvram file of a IOU device. The syntax is:

runiou rtimport DEV FILE
  • DEV: acronym of the device.

  • FILE: filename with the configuration in plain text file format.

The content of the configuration file is transfered to the nvram file without any syntax checking. If the size of the configuration is greather than 32 Kb, the configuration is compressed and the 'service compress-config' command is added. In any case, if the size of the configuration (compressed or not) is greather than 62 Kb, runiou display the error and cancel the operation.

Example:

runiou rtimport CPE1 /path/to/filename.txt

version

With this command, you can see the version of runiou. The syntax is:

runiou version

help

With this command, you can see a brief help of all commands accepted by runiou. The syntax is:

runiou help

Putting all together

In this example, you have this topology:

  • An IOU switch:

    • Name: SW1
    • ID: 11
    • With 6 ethernet ports.
  • An IOU router:

    • Name: R1
    • ID: 21
    • eth 0/0 connected to eth 0/0 of SW1.
  • An IOU router:

    • Name: R2
    • ID: 22
    • eth 0/0 connected to eth 0/1 of SW1.
  • A software firewall:

    • Name: FW1
    • Management command: ssh -l admin 192.168.56.2
    • Management ID: 31
    • Running in a virtualbox machine.
    • eth0 connected to eth 0/2 of SW1 via udp connection.
    • Connection ID: 41
    • UDP port of IOU interface: 9001
    • UDP port of virtualbox interface: 9002
  • A software firewall:

    • Name: FW2
    • Management command: ssh -l admin 10.10.10.2
    • Management ID: 32
    • Running in a qemu machine.
    • eth0 connected to eth 0/3 of SW1 via udp connection.
    • Connection ID: 42
    • UDP port of IOU interface: 9003
    • UDP port of qemu interface: 9004
  • A real firewall:

    • Name: FW3
    • Management command: ssh -l pix 192.168.0.9
    • Management ID: 33
    • eth1 of the host machine connected to eth 1/0 of SW1 via interface connection.
    • Connection ID: 51
    • The real firewall FW3 is connected to eth1 host machine.
  • The host machine:

    • Name: PC1
    • Management command: bash
    • Management ID: 34
    • tap interface connected to eth 1/1 of SW1 via tap connection.
    • Connection ID: 61

This lab is for training of employees from the company Foo Bar Inc.

The screen windows list have a separator in the FW1 firewall.

Use the global template for the initial configuration plus a pair of particular commands.

With all this information, you can build the netmap file and configure the network cards in virtualbox and qemu. The netmap file can be look like this:

#--- IOU devices.
#%  11    SW1   l2        6   0
#%  21    R1    advipsrv  2   0
#%  22    R2    ipbase    2   0

#--- Real and virtual devices.
#/  31    FW1   ssh -l admin 192.168.56.2
#/  32    FW2   ssh -l admin 10.10.10.2
#/  33    FW3   ssh -l pix 192.168.0.9
#/  34    PC1   bash

#--- UDP connections.
#$  41    9001  127.0.0.1 9002
#$  42    9003  127.0.0.1 9004

#--- Interface connections.
#@  51    eth1

#--- TAP connections.
#^  61    post-up   ifconfig <TAP> 192.168.2.4 netmask 255.255.255.0
#^  61    post-up   route add -net 10.91.91.0 netmask 255.255.255.0 gw 192.168.2.5

#--- Startup config.
#<  global
#<  hostname %H-%D
#<  ip route 0.0.0.0 0.0.0.0 null0

#--- Others.
#=  Foo Bar Inc - Lab #1
#+  31    --- Real equipment ---

#--- IOU connections.
11:0/0  21:0/0
11:0/1  22:0/0
11:0/2  41:0/0
11:0/3  42:0/0
11:1/0  51:0/0
11:1/1  61:0/0

#--- End.

With the list command, you can see a brief info of the lab:

$ runiou list
iou devices:
  SW1 - stopped - telnet 127.0.0.1 2011
  R1  - stopped - telnet 127.0.0.1 2021
  R2  - stopped - telnet 127.0.0.1 2022
external devices:
  FW1 - external - ssh -l admin 192.168.56.2
  FW2 - external - ssh -l admin 10.10.10.2
  FW3 - external - ssh -l pix 192.168.0.9
  PC1 - external - bash
external udp connections:
    41 - stopped - SW1:0/2 <--> 9001:127.0.0.1:9002
    42 - stopped - SW1:0/3 <--> 9003:127.0.0.1:9004
external interface connections:
    51 - stopped - SW1:1/0 <--> eth1
external tap connections:
    61 - stopped - SW1:1/1 <--> rioutapint0061
capturing traffic:
  none.
other info:
  this lab is running in 127.0.0.1 (local).
  caption of screen window: Foo Bar Inc - Lab #1
  with iou initial startup config.

With the cnhelp command, you can see the configuration of the network adapter in virtualbox and qemu for udp connections.

$ runiou cnhelp
external udp connections:

virtual device #41:
  for virtualbox:
    in network adapter:
        connected to:   Generic Driver
        name:           UDPTunnel
        properties:     dest=127.0.0.1
                        dport=9001
                        sport=9002
  for qemu:
    -net nic,vlan=N,macaddr=xx:xx:xx:xx:xx:x \
    -net socket,vlan=N,udp=127.0.0.1:9001,localaddr=:9002

virtual device #42:
  for virtualbox:
    in network adapter:
        connected to:   Generic Driver
        name:           UDPTunnel
        properties:     dest=127.0.0.1
                        dport=9003
                        sport=9004
  for qemu:
    -net nic,vlan=N,macaddr=xx:xx:xx:xx:xx:x \
    -net socket,vlan=N,udp=127.0.0.1:9003,localaddr=:9004

With the netmap file in the current directory, you can start the lab with the start command. runiou start the IOU devices and connections. When runiou start the interface and tap connections, ask for the user password (with sudo) or root password (with su).

$ runiou start
starting R1
starting R2
starting SW1
wait ......
devices started ok.
starting udp conn #41
starting udp conn #42
wait ......
udp connections started ok.
=> To start the interface connections, we need root privileges.
=> Enter the root password.
Password:
starting intf conn #51
wait ......
intf connections started ok.
=> To start the tap connections, we need root privileges.
=> Enter the root password.
Password:
starting tap conn #61
wait ......
tap connections started ok.

You can list the status of devices and connections with the list command:

$ runiou list
iou devices:
  SW1 - running - telnet 127.0.0.1 2011
  R1  - running - telnet 127.0.0.1 2021
  R2  - running - telnet 127.0.0.1 2022
external devices:
  FW1 - external - ssh -l admin 192.168.56.2
  FW2 - external - ssh -l admin 10.10.10.2
  FW3 - external - ssh -l pix 192.168.0.9
  PC1 - external - bash
external udp connections:
    41 - running - SW1:0/2 <--> 9001:127.0.0.1:9002
    42 - running - SW1:0/3 <--> 9003:127.0.0.1:9004
external interface connections:
    51 - running - SW1:1/0 <--> eth1
external tap connections:
    61 - running - SW1:1/1 <--> rioutapint0061
capturing traffic:
  none.
other info:
  this lab is running in 127.0.0.1 (local).
  caption of screen window: Foo Bar Inc - Lab #1
  with iou initial startup config.

If there are no errors, the state must be running on all IOU devices and all connections.

The list command also show the telnet command for the console of all IOU and external devices if you want to enter manually.

You can access to the consoles of all devices with the telnet command. With this, runiou call the screen command to open all IOU devices consoles and execute the commands to enter to all extenal devices.

$ runiou telnet

 Num Name                                Flags
   0 SW1                                     $
   1 R1                                      $
   2 R2                                      $
   3 FW1 ------ Real equipment ---           $
   4 FW2                                     $
   5 FW3                                     $
   6 PC1                                     $

If you have specified an initial startup config, the IOU devices start with these initial configuration.

Now, you can configure the devices for get a working lab.

Here are a quick reference of screen usage, command line and keywords.

At any time you can capture traffic in any interface of any IOU device. The traffic capture is started with the captureon command and is stopped with the captureoff command.

For example, if you need to capture the traffic in R1 0/0 (connected to SW1 0/0), you can start the capture with this command:

$ runiou captureon R1 0/0 eth
capture in R1 0/0 started.

runiou start iousniff to capture the traffic data. You can start others traffic captures simultaneously, but you can not start a capture in any device which are busy in any capture process.

With the list command, you can view all actives traffic captures:

$ runiou list
....
capturing traffic:
  R1 0/0 <--> SW1 0/0 [eth]
....

When you need to stop the capture, you can execute the captureoff command:

$ runiou captureoff R1
capture in R1 stopped.
file: /tmp/runiou1001/captures/cap-R1-0-0-20160426-175137.pcap

When you stop the capture, runiou rename the capture file and move it to the final directory configured in the variable CFGCAPTURESDIR in runiou, and inform the final filename.

With the capturelist command, you can view all capture files:

$ runiou capturelist
capture files in tatiana [172.28.245.6]:
  /tmp/runiou1001/captures/cap-R1-0-0-20160426-175137.pcap
  /tmp/runiou1001/captures/cap-R2-0-0-20160426-174525.pcap

You can download (with cp, scp, rsync, ftp, etc), view (with wireshark, tshark, tcpdump), delete, move or whatever the captures. For example, a brief view with tshark:

tshark -n -r /tmp/runiou1001/captures/cap-R1-0-0-20160426-175137.pcap
  1   0.000000 aa:bb:cc:00:0b:00 -> 01:80:c2:00:00:00 STP 60 Conf. Root = 32768/1/aa:bb:cc:00:0b:00  Cost = 0  Port = 0x8001
  2   1.446953   10.77.77.1 -> 10.98.28.6   ICMP 78 Echo (ping) request  id=0x0161, seq=1/256, ttl=255
  3   1.447402   10.98.28.6 -> 10.77.77.1   ICMP 78 Echo (ping) reply    id=0x0161, seq=1/256, ttl=255 (request in 2)
  4   1.662353  192.168.2.6 -> 224.0.0.5    OSPF 94 Hello Packet
  5   2.004154 aa:bb:cc:00:0b:00 -> 01:80:c2:00:00:00 STP 60 Conf. Root = 32768/1/aa:bb:cc:00:0b:00  Cost = 0  Port = 0x8001
  6   4.004055 aa:bb:cc:00:0b:00 -> 01:80:c2:00:00:00 STP 60 Conf. Root = 32768/1/aa:bb:cc:00:0b:00  Cost = 0  Port = 0x8001
  7   4.448752   10.36.74.7 -> 10.65.45.9   UDP 94 Source port: 5422  Destination port: 1967
  8   4.449053  192.168.2.5 -> 10.36.74.7   UDP 66 Source port: 1967  Destination port: 5422
  9   4.449403   10.36.74.7 -> 10.65.45.9   UDP 60 Source port: 5422  Destination port: 2344
 10   4.449581   10.65.45.9 -> 10.36.74.7   UDP 60 Source port: 2344  Destination port: 5422
 11   6.008371 aa:bb:cc:00:0b:00 -> 01:80:c2:00:00:00 STP 60 Conf. Root = 32768/1/aa:bb:cc:00:0b:00  Cost = 0  Port = 0x8001
 12   6.277302  192.168.2.5 -> 224.0.0.5    OSPF 94 Hello Packet
 13   8.016390 aa:bb:cc:00:0b:00 -> 01:80:c2:00:00:00 STP 60 Conf. Root = 32768/1/aa:bb:cc:00:0b:00  Cost = 0  Port = 0x8001
 14   9.706105 aa:bb:cc:00:15:00 -> aa:bb:cc:00:15:00 LOOP 60 Reply
 15   9.706218 aa:bb:cc:00:15:00 -> aa:bb:cc:00:15:00 LOOP 60 Reply
 16  10.020703 aa:bb:cc:00:0b:00 -> 01:80:c2:00:00:00 STP 60 Conf. Root = 32768/1/aa:bb:cc:00:0b:00  Cost = 0  Port = 0x8001

Also, you can capture traffic in any external udp, tap or interface connection. With tap or interface connection, runiou ask for the user password (with sudo) or root password (with su). For example, you can capture traffic in the SW1 1/1 connected to the tap interface to PC1:

$ runiou captureon SW1 1/1 eth
=> To start the capture, we need root privileges.
=> Enter the root password.
Password:
capture in SW1 1/1 started.

With the list command, you can view the actives captures:

$ runiou list
...
capturing traffic:
  SW1 1/1 <--> rioutapint0061 [eth]
....

Again, when you stop the capture, runiou ask for the user or root password:

$ runiou captureoff SW1
=> To stop the capture, we need root privileges.
=> Enter the root password.
Password:
capture in SW1 stopped.
file: /tmp/runiou1001/captures/cap-SW1-1-1-20160426-182349.pcap

With the capturelist command, you can view all the capture files:

$ runiou capturelist
capture files in tatiana [172.28.245.6]:
  /tmp/runiou1001/captures/cap-R2-0-0-20160426-174525.pcap
  /tmp/runiou1001/captures/cap-R1-0-0-20160426-175137.pcap
  /tmp/runiou1001/captures/cap-SW1-1-1-20160426-182349.pcap

And you can analize the capture with tshark:

tshark -n -r /tmp/runiou1001/captures/cap-SW1-1-1-20160426-182349.pcap
  1   0.000000 aa:bb:cc:00:0b:11 -> 01:80:c2:00:00:00 STP 60 Conf. Root = 32768/1/aa:bb:cc:00:0b:00  Cost = 0  Port = 0x8006
  2   0.352679  192.168.2.5 -> 192.168.2.4  ICMP 78 Echo (ping) request  id=0x026f, seq=1/256, ttl=255
  3   0.352758  192.168.2.4 -> 192.168.2.5  ICMP 78 Echo (ping) reply    id=0x026f, seq=1/256, ttl=64 (request in 2)
  4   1.460759  192.168.2.5 -> 224.0.0.5    OSPF 94 Hello Packet
  5   2.003787 aa:bb:cc:00:0b:11 -> 01:80:c2:00:00:00 STP 60 Conf. Root = 32768/1/aa:bb:cc:00:0b:00  Cost = 0  Port = 0x8006
  6   3.348665  192.168.2.5 -> 192.168.2.4  ICMP 78 Echo (ping) request  id=0x0270, seq=1/256, ttl=255
  7   3.348771  192.168.2.4 -> 192.168.2.5  ICMP 78 Echo (ping) reply    id=0x0270, seq=1/256, ttl=64 (request in 6)
  8   4.004336 aa:bb:cc:00:0b:11 -> 01:80:c2:00:00:00 STP 60 Conf. Root = 32768/1/aa:bb:cc:00:0b:00  Cost = 0  Port = 0x8006
  9   4.408765  192.168.2.6 -> 224.0.0.5    OSPF 94 Hello Packet
 10   4.672944   10.65.45.9 -> 192.168.2.4  UDP 94 Source port: 55400  Destination port: 1967
 11   6.005557 aa:bb:cc:00:0b:11 -> 01:80:c2:00:00:00 STP 60 Conf. Root = 32768/1/aa:bb:cc:00:0b:00  Cost = 0  Port = 0x8006
 12   6.348483  192.168.2.5 -> 192.168.2.4  ICMP 78 Echo (ping) request  id=0x0272, seq=1/256, ttl=255
 13   6.348555  192.168.2.4 -> 192.168.2.5  ICMP 78 Echo (ping) reply    id=0x0272, seq=1/256, ttl=64 (request in 12)
 14   7.921839 aa:bb:cc:00:0b:11 -> 01:00:0c:cc:cc:cc DTP 60 Dynamic Trunk Protocol
 15   7.921923 aa:bb:cc:00:0b:11 -> 01:00:0c:00:00:00 LLC 94 U, func=UI; SNAP, OUI 0x00000C (Cisco), PID 0x0003
 16   8.005658 aa:bb:cc:00:0b:11 -> 01:80:c2:00:00:00 STP 60 Conf. Root = 32768/1/aa:bb:cc:00:0b:00  Cost = 0  Port = 0x8006

At any time, you can export the startup configuration of all IOU devices to a plain text with the export command, or of some IOU devices with the rtexport command. For example:

$ runiou export
exporting R1 to config-R1-20160430-190338.txt: OK.
exporting R2 to config-R2-20160430-190338.txt: OK.
exporting SW1 to config-SW1-20160430-190338.txt: OK.

and obtains:

$ ls -l
-rw-rw-r-- 1 user user    744 abr 30 19:03 config-R1-20160430-190338.txt
-rw-rw-r-- 1 user user 751222 abr 30 19:03 config-R2-20160430-190338.txt
-rw-rw-r-- 1 user user   1307 abr 30 19:03 config-SW1-20160430-190338.txt
-rw-rw-r-- 1 user user    884 abr 30 18:48 NETMAP
-rw-rw-r-- 1 user user 131072 abr 30 17:30 nvram_00011
-rw-rw-r-- 1 user user 131072 abr 30 17:28 nvram_00021
-rw-rw-r-- 1 user user 131072 abr 30 18:00 nvram_00022

To stop the lab, you can execute the stop command. runiou ask if you are sure, you must respond YES in upper case with a timeout of 15 seconds. If there any tap or interface connection, runiou ask for the user password (with sudo) or root password (with su) to stop these connections:

$ runiou stop
==> WARNING: This command stop the lab.
==> WARNING: You must respond YES to stop the lab.
==> WARNING: Are you sure? [YES/no]: YES
=> To stop the interface connections, we need root privileges.
=> Enter the root password.
Password:
stopping intf conn #51
wait ......
intf connections stopped ok.
=> To stop the tap connections, we need root privileges.
=> Enter the root password.
Password:
stopping intf conn #61
wait ......
tap connections stopped ok.
stopping udp conn #41
stopping udp conn #42
wait ......
udp connections stopped ok.
stopping R1
stopping R2
stopping SW1
wait ......
devices stopped ok.

Known issues

  • The external interface connections partially works or not work at all when the ethernet interface in the host machine have an IP address configured. Also does not work when the Gnome Network Manager is activated in the interface. If the IOU device can not pass traffic to the real device, use a dedicated and unmanaged ethernet interface in the host machine.

  • The capture traffic of internal connections between two IOU devices not work in NetBSD 5.1 due to a bug in IOUSniff (iousniff break the sockets files and the IOU devices can not comunicate between them).

  • The external interface connections not work under NetBSD 5.1 which run as guest virtual machine in virtualbox. I am not sure if is a bug of iou2net.pl, NetBSD, virtualbox or Ubuntu in the host machine.

  • In NetBSD 5.1, sometimes the runiou telnet command fails due to bug of screen. When the screen session is created the first time, screen closes without error and the creation of the telnet windows fail. Workaround: execute the runiou telnet command again.


  • The most complete Cisco IOU FAQ link

  • Installing and running IOU link

  • GNU Screen Manual link

  • GNU Screen usage link

  • GNU Screen quick reference link

  • tshark manual page link

  • tshark display filters link

  • Examples of tshark / wireshark filters link

  • Wireshark cheatsheet link