NAME

SYNOPSIS

iitis-generator [OPTIONS...] TRAFFIC FILE [CONFIG FILE]

INTRODUCTION

This tool provides partial, limited solution to the problem formulated by the question: given a
computer network, how will it perform under traffic work load? The network may consist of many nodes
and we want detailed statistical data for each node.

Motivations behind this fundamental question are - for instance - the need to assess service quality
and the need to predict the performance of the network. There exist an approach to solve this
problem by means of digital modelling and simulation. The iitis-generator program, however,
is a supportive tool for an alternative approach, complementary to network simulation.

In this approach, real traffic is generated in a physical network and statistical data is collected.
Results of such experiment can be used for further search for the answer to the question on network
performance.

DESCRIPTION

iitis-generator is basically a traffic generator. It is run on many network hosts at the same
time. Each host is called a node. Each node may be connected to many test networks - on which
traffic is to be generated - and also must be connected to one IP service network.

Basically iitis-generator does the following:

parse traffic characteristics in TRAFFIC FILE

negotiate a common experiment start moment using the service network

generate and receive traffic on test networks

periodically write statistics to disk

As the output, a directory with a tree-like structure is created. It contains the resultant network
statistics, amongst the others (see OUTPUT).

iitis-generator is written in C and designed to be run on embedded systems, especially MikroTik
RouterBoards running OpenWrt.

NETWORK ENVIRONMENT

The test traffic is generated using the low level packet injection facility of the Linux mac80211
subsystem. Hence, a precise control over wireless frames is possible. Traffic capture is realized
in similar way.

In order to make a wireless interface available to be used by iitis-generator, it must be put into
the monitor mode and named like "mon*", where * is a number 0-7, e.g. "mon0". This interface number
is also used in the traffic file.

Frames generated in test networks have 3 headers:

IEEE 802.11 header (24B + 4B FCS)

LLC header, encapsulated Ethernet (8B)

iitis-generator header (20B)

The service network is realized by:

sending UDP broadcast (255.255.255.255) frames on port 31337

replying with UDP unicast frames

By default, the "eth0" interface is used. This can be changed using the "svc-ifname" option (see
iitis-generator-conf(5)). Currently, the service network is used only for node synchronization.

NODE SYNCHRONIZATION

Definitions in the traffic file use relative time moments. In order to synchronize actions being
taken by nodes, a certain moment of time needs to be chosen as the time origin ("origin" for
short), common for all nodes. This moment is chosen on the wall clock. Such approach has an
advantage of opening a possibility for an external program working on wall clock synchronization
parallely to iitis-generator.

Node synchronization is realized during startup, in a master-slave manner. The node with the lowest
ID is chosen as the master, and all other nodes become slaves. Master will periodically propose
some origin a few seconds ahead the wall clock, until all slaves reply with a positive
acknowledgement.

A reliable wall clock source is required on all nodes. Running NTP on each node is enough to have a
1 ms accuracy in a typical LAN environment.

OPTIONS

iitis-generator accepts following options.

--id=num

ID number of this node; by default it will be extracted from the hostname, e.g. "router5" gives number 5

--root=directory

the root directory for the program output; by default "./out"

--sess=name

optional session name

--world

make all generated files and directories readable and writable by anyone

--verbose,-V

be verbose; alias for --debug=5

--debug=num

set debugging level

--help,-h

display short help screen and exit

--version,-v

display version and copying information

Most options can be overriden in the CONFIG FILE, which is applied after command line options.

CONFIG FILE

The CONFIG FILE is recommended to be common for the whole network. Exemplary config file below.

Notice the message prefix with information on the program internals. Level of detail of this
information increases with the debug level. In example above it's name of the C function which
generated the message.

Possible program return values and their meanings:

0

everything completed successfully

1

invalid command line arguments

2

no available interfaces found

3

invalid TRAFFIC FILE provided

4

invalid CONFIG FILE provided

134

aborted, see below

139

segmentation fault

iitis-generator may abnormally abort execution with return value 134 due to unexpected
circumstances. However, the user will be notified about detailed source code file name and line
number that caused such behaviour. Such information will be in the last line printed to the standard
error output of the program. This may be used for further tracing of the root error cause.