History

How to use Iperf with OML2¶

1. Iperf Tutorial¶

This tutorial presents another example, which demonstrate how to use iperf in an automatic way with OMF. Furthermore, this tutorial give an overview of the measurements orchestrated within this traffic generator using OML.

Iperf is a traffic generator widely used to measure network characteristics. It has been originally developed by the NRANL. It allows the experimenter to generate either UDP and TCP traffic. Furthermore, the user can parallelize connection to even more stress the network.

In the context of OMF we have inserted Measurement Points inside the source code of iperf using OML. These measurements mimic the measurements originally done by iperf.

In this tutorial, we present the different configurations of iperf (UDP or TCP) using the same topology presented in the Hello World tutorial with one sender and one receiver. Thus we will run the experiment twice, one using TCP and the second using UDP.

2. Prerequisites¶

In order to fully understand this tutorial, the user should have mastered:

Hello World tutorial;
Prototype Tutorial.

3. Developing Iperf Experiment Description¶

As explained on the Introduction page earlier, to run an experiment with OMF, you need to describe it into an Experiment Description (ED). An Experiment Description (ED) is a script that is supplied as an input to the OMF Experiment Controller (EC). It contains detailed descriptions of resources required by an experiment and the sets of actions to perform in order to realize that experiment. An ED is written using the OMF Experiment Description Language (OEDL). In this ED we will be using the iperf prototypes even if we could use the application wrapper.

The ED describing this Iperf experiment is:

 1 defGroup('Sender', [1,2]) {|node|
 2   node.prototype("test:proto:iperfudpsender", {
 3     'port' => 5000,
 4     'client' => '192.168.0.3'
 5   })
 6 
 7   node.net.w0.mode = "adhoc" 
 8   node.net.w0.type = 'g'
 9   node.net.w0.channel = "6" 
10   node.net.w0.essid = "helloworld" 
11   node.net.w0.ip = "192.168.0.2" 
12 }
13 
14 defGroup('Receiver', [1,3]) {|node|
15   node.prototype("test:proto:iperfudpreceiver",{
16     'port' => 5000
17     }
18   )
19   node.net.w0.mode = "adhoc" 
20   node.net.w0.type = 'g'
21   node.net.w0.channel = "6" 
22   node.net.w0.essid = "helloworld" 
23   node.net.w0.ip = "192.168.0.3" 
24 }
25 
26 whenAllInstalled() {|node|
27   wait 10
28   allGroups.startApplications
29   wait 30
30   allGroups.stopApplications
31   Experiment.done
32 }

3.1 Resource Description and Configuration (Line 1 to 24)¶

Line 1: we define a new group of resources, called "Sender". This group includes a unique node, which is identified by a unique id: [1,2].

Line 2-6: we associate an existing prototype called "test:proto:iperfudpsender" to this group, i.e. the application associated to the prototype will be installed and run on each node of this group (here, only [1,2]). In the context of this tutorial, this application is already installed on the baseline disk image.
- More precisely:
  - Line 3: we set the property "port" of the application to the port that node [1,3] (i.e. the traffic receiver) will listen on for the duration of our experiment
  - Line 4: we set the property "client" of the application to the IP address that we will give to node [1,3] (i.e. the traffic receiver) for the duration of our experiment

Line 7-11: we configure some properties for this group, i.e. all the nodes in this group will share these properties (here, only node [1,2])
- More precisely:
  - Line 8: we request that the first wireless interface (named "w0") of the node is placed in "ad-hoc" mode
  - Line 9: this same interface is configured to operate in the type "g" of the 802.11 standard (i.e. 802.11g)
  - Line 10: this same interface is configured to operate on channel "6"
  - Line 11: we set the Extended Service Set ID (ESSID) of this interface to the name "helloworld"
  - Line 12: finally, we set the IP address of this interface to "192.168.0.2"

Line 15-26: we define a similar group, called "Receiver", which will only include node [1,3] running the existing prototype "test:proto:iperfudpreceiver". This prototype will initialise the iperf server.

Note:
- More details about how to define groups and topologies, or configure resources can be found on the other tutorial pages.
- More details about all the available options of the above "defGroup", "addApplication", etc... commands can be found on the OEDL reference pages.

3.2 Action Descriptions as a State Machine (Line 26 to 32)¶

OMF has adopted a state machine approach to describe the different actions required to perform the experiment scenario. Basically, actions are associated to states, and are performed when that state is reached. States can be characterise by many different conditions. For example, a state can be "when nodes in group X are all powered ON", or "when measured data Z reaches a threshold X", etc...

In this simple experiment, we only declare one state, which is "when all the nodes are ON, and all the required applications are installed on them". This translates into the call to "whenAllInstalled()", as shown on line 26.

Line 28-34: here we declare a unique state, named "whenAllInstalled()", which is followed by the sequential list of actions to perform when this state is reached:
- More precisely:
  - Line 29: instruct the Experiment Control to pause for 10 sec. This is recommended to ensure that all the nodes have been configured, e.g. there may be a lag between the moment a node receives a command to change its IP address, and the moment when this does happen. To be fully consistent with the "state-machine" approach, we should use here a state declaration such as "when all nodes are configured". However, OMF does not support state nesting yet, this will be added in a future release.
  - Line 30: tell all the Groups of this experiment to start all the applications associated to them. In this particular example, this command will tell all the nodes in the groups "Sender" and "Receiver" (i.e. [1,2] and [1,3]) to start their associated applications.
  - Line 31: wait for 30 sec. Basically, here we are giving time for UDP/TCP traffic to be exchanged from "Sender" to "Receiver". This is in fact the experiment.
  - Line 32: tell all the Groups to stop all the applications running on all the nodes associated to them.
  - Line 33: declare the end of the Experiment. This will trigger some "cleaning" actions on the nodes (e.g. turn off the network interfaces, stop receiving commands for this experiment, etc...)

Note:
- More details about how to define other states or actions to perform within them can be found on the other tutorial pages.
- More details about all the available options of the above commands can be found on the OEDL reference pages.

4. Results¶

The iperf applications provides the experimenter with the three kinds of OML Measurement Points. The first one, "Peer_Info", is shared by the receiver and the sender and gives information about the transfer. On the receiver side, the experimenter will have the particular MP "UDP_Rich_Info". This MP is defined as:

 1 a.defMeasurement("UDP_Rich_Info"){ |m|
 2   m.defMetric('ID', :long)
 3   m.defMetric('Begin_interval', :float)
 4   m.defMetric('End_interval', :float)
 5   m.defMetric('Transfer', :float)
 6   m.defMetric('Bandwidth', :float)
 7   m.defMetric('Jitter', :float)
 8   m.defMetric('Packet_Lost', :long)
 9   m.defMetric('Total_Packet', :long)
10   m.defMetric('PLR', :float)
11 
12 }

We can see that this MP provides in the same way as iperf with the number of bytes transferred (Transfer), the bandwidth observed between Begin_Interval and End_Interval, the jitter during this interval, the number of packets lost, the number of packets transmitted, and the Packet Loss Rate.

On the sender side, since we are using UDP, we have a more limited MP called "UDP_Periodic_Info". This MP provides information about the number of bytes transferred and bandwidth. Last, the sender receives the information from the receiver at the end of the experiment and send them using the "UDP_Rich_Info" measurement point.

Then, in order to display the result an experimenter can do the same as in Hello World tutorial section 5.2 but changing the name of the fields.

OMF

Wiki