Orbit > Other Applications > Integrating Iperf with ORBIT

Iperf Integration

This document covers the general details of integrating sample applications with the ORBIT tesbed setup. A specific example (Iperf) is chosen as a candidate application and the steps are described in the document. The readers are referred to the ORBIT architecture document for the individual software component details.

To summarize, nodeHandler is the experiment controller software that is used to choreograph the experiment. It is used to power on, initialize interfaces, launch the applications simultaneously on the nodes involved in the experiment, as well as create databases consistent with the measurements for that particular experiment.

OML (ORBIT Measurement Library) is used to collect measurements at run-time from the nodes. It consists of an OML-client on the nodes and the collection server on the experiment controller machine that is used to collect the measurements sent by the clients and insert into appropriate columns of the database.

Integrating a new application with this setup mainly consists of the following steps

Contents

• 1   Integrating with measurement collection
  • 1.1   Identifying the measurements reported by Iperf
  • 1.2   Create the application definition XML file
  • 1.3   Creating OML shared library and headers for Iperf
  • 1.4   Include header files and function calls in source code
  • 1.5   Modify Makefile and build application
  • 1.6   Miscellaneous
• 2   Integrating with Nodehandler – Launching the application
  • 2.1   Create application definitions for Iperf client and server
  • 2.2   Iperf Sender
  • 2.3   Iperf Receiver
  • 2.4   Create prototypes using previously defined applications
  • 2.5   Iperf UDP Sender
  • 2.6   Iperf UDP Receiver
  • 2.7   Iperf TCP Sender
  • 2.8   Iperf TCP Receiver
  • 2.9   Write experiment script using the previously defined application and prototype definitions
  • 2.10   Experiment Script
• 3   Parameters and statistics supported
  • 3.1   Sender Side
  • 3.2   Receiver Side
  • 3.3   Statistics Reported

---

1   Integrating with measurement collection

In order to initiate measurement collection using OML, the following steps need to be taken

1.1   Identifying the measurements reported by Iperf

The first step is to identify what are the measurements reported by the application and finding the right files in the source code corresponding to these measurement reports. For Iperf, the statistics for UDP are throughput, packet loss and jitter and for TCP: throughput

For Iperf, this was traced to the file ReportDefault.c

1.2   Create the application definition XML file

The application definition file for Iperf is defined to capture the outputs that the program reports. This file is later used to auto-generate OML library and headers for this application. The following application definition file has been written for Iperf (using a subset of command line inputs)

[wiki:Documentation/OtherApps/Iperf/IperfAppDefXML Iperf Application Definition Schema]

Verify that the XML file is syntactically correct by correct by checking if it opens correctly in an XML enabled browser (IE or Mozilla)

1.3   Creating OML shared library and headers for Iperf

After defining the application definition file as above, use the following command to submit the application definition file to a wrapper utility

'''wget -q http://www.orbit-lab.org/oml/client_wrapper --post-file <app-def.xml>'''

In response to the <app-def>.xml file, the OML application service returns a tar file containing: oml_<app-def>.h and liboml_<app-def>.a.

Iperf is then compiled against this library.

1.4   Include header files and function calls in source code

In the main method of Iperf (found in main.cpp),

''#include "oml_orbit_winlab_iperf.h"''

''initialize_oml(&argc, argv, null)''

In the file ReportDefault.c

''oml_receiverport(msmt1, msmt2, msmt3)''

1.5   Modify Makefile and build application

Linker options: -loml_client -lomltx

LDFLAGS = -L/usr/lib/ -Lpath_to/liboml_orbit_winlab_iperf.a

The oml client package with the required libraries can be obtained from the orbit repository (apt-get oml-client). It will install oml-client and oml_transport libraries in /usr/lib/

Note that the OML client is already present on the nodes (so the second step can be ignored)

Now, Iperf can be rebuilt using the Makefile.

1.6   Miscellaneous

Note that the application will need the following environment variables to be set

'''LD_LIBRARY_PATH = /usr/lib/''' '''OML_NAME=<node-id>''' '''OML_CONFIG=<OML configuration file>'''

All these variables are set automatically when the experiment is run using the nodeHandler.

2   Integrating with Nodehandler – Launching the application

This section includes the details of how to integrate Iperf with the experiment controller (nodeHandler) so that it can be launched on all the nodes involved in the experiment.

2.1   Create application definitions for Iperf client and server

The following two sample files for Iperf sender and receiver show the details of how to create definitions for any application. The definition mainly contains the command line options that can be set during launching the application as well as the output statistics reported by the application

2.2   Iperf Sender

[wiki:Documentation/OtherApps/Iperf/IperfSender Iperf Sender Application Script]

2.3   Iperf Receiver

[http://www.orbit-lab.org/wiki/Documentation/OtherApps/Iperf/IperfReceiver Iperf Receiver Application Script]

2.4   Create prototypes using previously defined applications

Using the previously defined Iperf client and server application definitions, the next step is to create prototypes that use these applications. For e.g using the basic Iperf application, we define four prototypes, udpsender, udpreceiver, tcpsender and tcpreceiver. Each of these will use Iperf as the underlying application; however their properties can be customized as shown below

2.5   Iperf UDP Sender

[wiki:Documentation/OtherApps/Iperf/IperfUDPSender Iperf UDP Sender Prototype Script]

2.6   Iperf UDP Receiver

[wiki:Documentation/OtherApps/Iperf/IperfUDPReceiver Iperf UDP Receiver Prototype Script]

2.7   Iperf TCP Sender

[wiki:Documentation/OtherApps/Iperf/IperfTCPSender Iperf TCP Sender Prototype Script]

2.8   Iperf TCP Receiver

[wiki:Documentation/OtherApps/Iperf/IperfTCPReceiver Iperf TCP Receiver Prototype Script]

2.9   Write experiment script using the previously defined application and prototype definitions

The final step is to write the actual experiment script as shown below

2.10   Experiment Script

[wiki:Documentation/OtherApps/Iperf/ExperimentScript Experiment Script]

3   Parameters and statistics supported

3.1   Sender Side

• UDP or TCP flow
• Sender port number
• TCP Send Window size (for TCP flows)
• Payload length (for UDP flows)
• Bandwidth (offered load for UDP flows)
• Duration of traffic generation
• Number of parallel flows

3.2   Receiver Side

• UDP or TCP flow
• Receiver port number
• TCP Receive window size (for TCP flows)
• Duration of run
• Payload length (to expect from sender for UDP flows)
• Interval (periodic duration between report generation)

3.3   Statistics Reported

• Throughput (TCP and UDP)
• Jitter (UDP)
• Packet Loss (UDP)