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