README.md
1iperf3: A TCP, UDP, and SCTP network bandwidth measurement tool
2================================================================
3
4Summary
5-------
6
7iperf is a tool for active measurements of the maximum achievable
8bandwidth on IP networks. It supports tuning of various parameters
9related to timing, protocols, and buffers. For each test it reports
10the measured throughput / bitrate, loss, and other parameters.
11
12This version, sometimes referred to as iperf3, is a redesign of an
13original version developed at NLANR/DAST. iperf3 is a new
14implementation from scratch, with the goal of a smaller, simpler code
15base, and a library version of the functionality that can be used in
16other programs. iperf3 also has a number of features found in other tools
17such as nuttcp and netperf, but were missing from the original iperf.
18These include, for example, a zero-copy mode and optional JSON output.
19Note that iperf3 is *not* backwards compatible with the original iperf.
20
21Primary development for iperf3 takes place on CentOS Linux, FreeBSD,
22and macOS. At this time, these are the only officially supported
23platforms, however there have been some reports of success with
24OpenBSD, NetBSD, Android, Solaris, and other Linux distributions.
25
26iperf3 is principally developed by ESnet / Lawrence Berkeley National
27Laboratory. It is released under a three-clause BSD license.
28
29For more information see: https://software.es.net/iperf
30
31Source code and issue tracker: https://github.com/esnet/iperf
32
33Obtaining iperf3
34----------------
35
36Downloads of iperf3 are available at:
37
38 https://downloads.es.net/pub/iperf/
39
40To check out the most recent code, clone the git repository at:
41
42 https://github.com/esnet/iperf.git
43
44Building iperf3
45---------------
46
47### Prerequisites: ###
48
49None.
50
51### Building ###
52
53 ./configure; make; make install
54
55(Note: If configure fails, try running `./bootstrap.sh` first)
56
57Invoking iperf3
58---------------
59
60iperf3 includes a manual page listing all of the command-line options.
61The manual page is the most up-to-date reference to the various flags and parameters.
62
63For sample command line usage, see:
64
65https://fasterdata.es.net/performance-testing/network-troubleshooting-tools/iperf/
66
67Using the default options, iperf is meant to show typical well
68designed application performance. "Typical well designed application"
69means avoiding artificial enhancements that work only for testing
70(such as splice()'ing the data to /dev/null). iperf does also have
71flags for "extreme best case" optimizations, but they must be
72explicitly activated.
73
74These flags include:
75
76 -Z, --zerocopy use a 'zero copy' sendfile() method of sending data
77 -A, --affinity n/n,m set CPU affinity
78
79Bug Reports
80-----------
81
82Before submitting a bug report, please make sure you're running the
83latest version of the code, and confirm that your issue has not
84already been fixed. Then submit to the iperf3 issue tracker on
85GitHub:
86
87https://github.com/esnet/iperf/issues
88
89In your issue submission, please indicate the version of iperf3 and
90what platform you're trying to run on (provide the platform
91information even if you're not using a supported platform, we
92*might* be able to help anyway). Exact command-line arguments will
93help us recreate your problem. If you're getting error messages,
94please include them verbatim if possible, but remember to sanitize any
95sensitive information.
96
97If you have a question about usage or about the code, please do *not*
98submit an issue. Please use one of the mailing lists for that.
99
100Relation to iperf 2.x
101---------------------
102
103Note that iperf2 is no longer being developed by its original
104maintainers. However, beginning in 2014, another developer began
105fixing bugs and enhancing functionality, and generating releases of
106iperf2. Both projects (as of late 2017) are currently being developed
107actively, but independently. The continuing iperf2 development
108project can be found at https://sourceforge.net/projects/iperf2/.
109
110iperf3 contains a number of options and functions not present in
111iperf2. In addition, some flags are changed from their iperf2
112counterparts:
113
114 -C, --linux-congestion set congestion control algorithm (Linux only)
115 (-Z in iperf2)
116 --bidir bidirectional testing mode
117 (-d in iperf2)
118
119Some iperf2 options are not available in iperf3:
120
121 -r, --tradeoff Do a bidirectional test individually
122 -T, --ttl time-to-live, for multicast (default 1)
123 -x, --reportexclude [CDMSV] exclude C(connection) D(data) M(multicast)
124 S(settings) V(server) reports
125 -y, --reportstyle C report as a Comma-Separated Values
126
127Also removed is the ability to set the options via environment
128variables.
129
130Known Issues
131------------
132
133A set of known issues is maintained on the iperf3 Web pages:
134
135https://software.es.net/iperf/dev.html#known-issues
136
137Links
138-----
139
140This section lists links to user-contributed Web pages regarding
141iperf3. ESnet and Lawrence Berkeley National Laboratory bear no
142responsibility for the content of these pages.
143
144* Installation instructions for Debian Linux (by Cameron Camp
145 <cameron@ivdatacenter.com>):
146
147 http://cheatsheet.logicalwebhost.com/iperf-network-testing/
148
149Copyright
150---------
151
152iperf, Copyright (c) 2014-2020, The Regents of the University of
153California, through Lawrence Berkeley National Laboratory (subject
154to receipt of any required approvals from the U.S. Dept. of
155Energy). All rights reserved.
156
157If you have questions about your rights to use or distribute this
158software, please contact Berkeley Lab's Technology Transfer
159Department at TTD@lbl.gov.
160
161NOTICE. This software is owned by the U.S. Department of Energy.
162As such, the U.S. Government has been granted for itself and others
163acting on its behalf a paid-up, nonexclusive, irrevocable,
164worldwide license in the Software to reproduce, prepare derivative
165works, and perform publicly and display publicly. Beginning five
166(5) years after the date permission to assert copyright is obtained
167from the U.S. Department of Energy, and subject to any subsequent
168five (5) year renewals, the U.S. Government is granted for itself
169and others acting on its behalf a paid-up, nonexclusive,
170irrevocable, worldwide license in the Software to reproduce,
171prepare derivative works, distribute copies to the public, perform
172publicly and display publicly, and to permit others to do so.
173
174This code is distributed under a BSD style license, see the LICENSE
175file for complete information.
176