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
100Changes from iperf 2.x
101----------------------
102
103(Note 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
110New options:
111
112 -V, --verbose more detailed output than before
113 -J, --json output in JSON format
114 -Z, --zerocopy use a 'zero copy' sendfile() method of sending data
115 -O, --omit N omit the first n seconds (to ignore slowstart)
116 -T, --title str prefix every output line with this string
117 -F, --file name xmit/recv the specified file
118 -A, --affinity n/n,m set CPU affinity (Linux and FreeBSD only)
119 -k, --blockcount #[KMG] number of blocks (packets) to transmit (instead
120 of -t or -n)
121 -L, --flowlabel set IPv6 flow label (Linux only)
122
123Changed flags:
124
125 -C, --linux-congestion set congestion control algorithm (Linux only)
126 (-Z in iperf2)
127
128
129Deprecated options:
130
131Not planning to support these iperf2 flags. If you really miss these
132options, please submit a request in the issue tracker:
133
134 -d, --dualtest Do a bidirectional test simultaneously
135 -r, --tradeoff Do a bidirectional test individually
136 -T, --ttl time-to-live, for multicast (default 1)
137 -x, --reportexclude [CDMSV] exclude C(connection) D(data) M(multicast)
138 S(settings) V(server) reports
139 -y, --reportstyle C report as a Comma-Separated Values
140
141Also deprecated is the ability to set the options via environment
142variables.
143
144Known Issues
145------------
146
147A set of known issues is maintained on the iperf3 Web pages:
148
149https://software.es.net/iperf/dev.html#known-issues
150
151Links
152-----
153
154This section lists links to user-contributed Web pages regarding
155iperf3. ESnet and Lawrence Berkeley National Laboratory bear no
156responsibility for the content of these pages.
157
158* Installation instructions for Debian Linux (by Cameron Camp
159 <cameron@ivdatacenter.com>):
160
161 http://cheatsheet.logicalwebhost.com/iperf-network-testing/
162
163Copyright
164---------
165
166iperf, Copyright (c) 2014-2018, The Regents of the University of
167California, through Lawrence Berkeley National Laboratory (subject
168to receipt of any required approvals from the U.S. Dept. of
169Energy). All rights reserved.
170
171If you have questions about your rights to use or distribute this
172software, please contact Berkeley Lab's Technology Transfer
173Department at TTD@lbl.gov.
174
175NOTICE. This software is owned by the U.S. Department of Energy.
176As such, the U.S. Government has been granted for itself and others
177acting on its behalf a paid-up, nonexclusive, irrevocable,
178worldwide license in the Software to reproduce, prepare derivative
179works, and perform publicly and display publicly. Beginning five
180(5) years after the date permission to assert copyright is obtained
181from the U.S. Department of Energy, and subject to any subsequent
182five (5) year renewals, the U.S. Government is granted for itself
183and others acting on its behalf a paid-up, nonexclusive,
184irrevocable, worldwide license in the Software to reproduce,
185prepare derivative works, distribute copies to the public, perform
186publicly and display publicly, and to permit others to do so.
187
188This code is distributed under a BSD style license, see the LICENSE
189file for complete information.
190