Centre for Advanced Internet Architectures,
Swinburne University of Technology,
Melbourne, Australia
CRICOS number 00111D

8th April, 2009


----------------------------------------------
OVERVIEW
----------------------------------------------

The functionally equivalent "caia_iperf202_1.1.patch" and
"caia_iperf204_1.1.patch" patch files are for Iperf v2.0.2 and v2.0.4
respectively. The patch addresses the need for fine grained control of socket
buffer sizes. It also clarifies the behaviour of the existing Iperf "-w" switch
and adds some useful information to the Iperf test output relating to the
socket buffer sizes used during the test.

This patch adds 2 new switches to Iperf and changes the meaning (not behaviour)
of the -w switch. The new "-j" switch modifies the socket send buffer size and
the new "-k" switch modifies the socket receive buffer size. The existing "-w"
switch now stands for "wizard buffer tuning mode" instead of "TCP window size"
which should eliminate confusion as to its actual behaviour. The new switches
cannot be used concurrently with the "-w" switch. The "-w" switch will negate
the effects of the "-j" and "-k" switches if specified, and a message will be
printed to console informing the user of this negation.

Note: this patch has not been tested on systems which utilise autotuning of
socket buffer sizes, such as recent versions of Linux and FreeBSD. The
underlying system may ignore attempts to force a certain buffer size using the
switches introduced in this patch.


----------------------------------------------
LICENCE
----------------------------------------------

The Iperf patch is released under a BSD licence. Refer to licence headers in
the patch files for further details.


----------------------------------------------
USAGE
----------------------------------------------

1. untar the Iperf source code

2. Copy the appropriate "caia_iperf20?_1.1.patch" patch file into the Iperf
   source code directory

3. cd into the Iperf source code directory and run
   "patch -p0 < caia_iperf20?_1.1.patch"

4. Run "./configure" followed by "make"

5. Copy the "src/iperf" binary wherever you like


----------------------------------------------
ACKNOWLEDGEMENTS
----------------------------------------------

Development of this patch has been made possible in part by a grant from the
Cisco University Research Program Fund at Community Foundation Silicon Valley.


----------------------------------------------
RELATED READING
----------------------------------------------

This software was developed as part of the NewTCP research project at
Swinburne University's Centre for Advanced Internet Architectures.
More information on the project is available at:

http://caia.swin.edu.au/urp/newtcp/

A number of software tools and technical reports related to SIFTR and/or
experimental TCP research in general are available respectively at:

http://caia.swin.edu.au/urp/newtcp/tools.html
http://caia.swin.edu.au/urp/newtcp/papers.html

At the time of writing, the following software tools may be of interest:

Statistical Information For TCP Research (SIFTR)
Deterministic Packet Discard (DPD)

At the time of writing, the following reports/papers may be of interest:

[1] contains a technical evaluation and analysis of the SIFTR software which
has been extensively used during our experimental FreeBSD work.

[2] provides a detailed technical overview of the modular congestion control
patch to FreeBSD which we developed using Iperf and SIFTR for
verification purposes.

[3,4] illustrate the type of detailed analytical research being carried
out using Iperf and SIFTR.

[5] provides a discussion of useful tuning parameters for the FreeBSD 6
TCP/IP stack.


----------------------------------------------
REFERENCES
----------------------------------------------

[1] L. Stewart, G. Armitage, J. Healy, "Characterising the Behaviour and
    Performance of SIFTR v1.1.0", CAIA Technical Report 070824A, August 2007.

[2] L. Stewart, J. Healy, "Light-Weight Modular TCP Congestion Control for
    FreeBSD 7", CAIA Technical Report 071218A, December 2007.

[3] G. Armitage, L. Stewart, M. Welzl, J. Healy, "An independent H-TCP
    implementation under FreeBSD 7.0 - description and observed behaviour",
    ACM SIGCOMM Computer Communication Review, Volume 38 Issue 3, July 2008.

[4] L. Stewart, G. Armitage, and A. Huebner, "Collateral Damage: The Impact
    of Optimised TCP Variants On Real-time Traffic Latency in Consumer
    Broadband Environments", IFIP/TC6 NETWORKING 2009. To be presented,
    Aachen, Germany, 11-15 May 2009.

[5] L. Stewart, J. Healy,  "Tuning and Testing the FreeBSD 6 TCP Stack", CAIA
    Technical Report 070717B, July 2007.


----------------------------------------------
AUTHORS
----------------------------------------------

The Iperf patch was first released in 2007 by James Healy and Lawrence Stewart
whilst working on the NewTCP research project at Swinburne University's
Centre for Advanced Internet Architectures, Melbourne, Australia.

Lawrence Stewart is currently the sole maintainer, and all contact regarding
this patch should be directed to him via email: lastewart@swin.edu.au