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