Iperf

1. Basic description

This test module provides you with an easy way to use the iperf utility with LNST. It is required that machines where this module will be run have this utility installed. The iperf utility is used to measure the network performance between two separate machines. This test therefore requires the use of at least two machines, and to use it properly you will need to run two commands.

The purpose of this test module is quite obvious - measuring the network performance.

2. Options

This test module accepts these options:

role	accepted values are: client or server. This option is mandatory and determines the role of the slave machine this test is being run on.
duration	in seconds, specifies how long will the test be running. By default it is set to 60 seconds for the client, and unlimited for the server.
threshold	in [kMGT]bits/sec ( e.g. 1.2 Mbits/sec ) determines the lowest network performance throughput needed for the test to succeed. The default value is 0 bits/sec.
iperf_opts	gives you the ability to provide any additional arguments that should be passed to the iperf command.
iperf_server	expects an IP address or the hostname of the machine where an iperf command is running with role=server. This option is mandatory when role=client.
bind	represents the argument -B, of the iperf utility, that determines on which address will the server be listening for incoming connections. This option can only be used when role=server.

3. Usage Example

As was mentioned earlier, you will need two machines and run two Iperf tests at the same time in order to use this module correctly. To clarify see the following command sequence:

    <task>
        <run module="Iperf" host="testmachine2" bg_id="server">
            <options>
                <option name="role" value="server"/>
                <option name="bind" value="{ip(testmachine2, testifc2)}"/>
            </options>
        </run>
        <run module="Iperf" host="testmachine1">
            <options>
                <option name="role" value="client"/>
                <option name="iperf_server" value="{ip(testmachine2, testifc2)}"/>
            </options>
        </run>
        <kill host="testmachine2" bg_id="server"/>
    </task>

The first command will run the iperf utility in the role of the server, we also need to specify that it should bind to our testing interface. Since we want to run two commands at a time this command must be run as a background command (attribute bg_id).

Next we run the second command this time on a different machine, in the role of the client, and we direct him to where our server is listening.

To simplify the example we are not using any optional arguments but adding them should be fairly easy.

And finally, since we created a background command we add a corresponding kill command to clean-up.

4. Results

The command sequence, from the previous section, can be used in a full recipe considering you modify the ids to match your environment specification.

A successful run of these commands will give you results similar to these:

23/01 13:51:28|       (127.0.0.1) INFO: Executing command: [type (test), machine_id (testmachine2), value (Iperf), bg_id (server)]
23/01 13:51:26|  (192.168.122.30) DEBUG: Running in background with id "server", pid "2510"
23/01 13:51:28|       (127.0.0.1) DEBUG: Result: {'passed': True}
23/01 13:51:28|       (127.0.0.1) INFO: Executing command: [type (test), machine_id (testmachine1), value (Iperf)]
23/01 13:51:26| (192.168.122.109) DEBUG: compiled command: iperf --client 192.168.100.2 -t 60 
23/01 13:51:26| (192.168.122.109) DEBUG: running as client ...
23/01 13:52:27| (192.168.122.109) DEBUG: 
    data:
    ------------------------------------------------------------
    Client connecting to 192.168.100.2, TCP port 5001
    TCP window size: 23.2 KByte (default)
    ------------------------------------------------------------
    [  5] local 192.168.100.3 port 47099 connected with 192.168.100.2 port 5001
    [ ID] Interval       Transfer     Bandwidth
    [  5]  0.0-60.0 sec  1.39 GBytes    200 Mbits/sec
23/01 13:52:27| (192.168.122.109) DEBUG: PASSED
23/01 13:52:28|       (127.0.0.1) DEBUG: Result: {'res_data': 'Measured rate: 200 Mbits/sec', 'passed': True}
23/01 13:52:28|       (127.0.0.1) INFO: Result data: 'Measured rate: 200 Mbits/sec'
23/01 13:52:28|       (127.0.0.1) INFO: Executing command: [type (kill), machine_id (testmachine2), value (server)]
23/01 13:52:27|  (192.168.122.30) DEBUG: Killing background command with id "server", pid "2510"
23/01 13:52:28|       (127.0.0.1) DEBUG: Result: {'passed': True}