Annotation of embedaddon/iperf/README.md, revision 1.1
1.1 ! misho 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 bandwidth, 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 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 X. 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: Note that at this point, ESnet plans to support iperf3 in "maintenance
! 30: mode". At this point, there are no definite plans for further iperf3
! 31: releases, and ESnet will be providing a very limited amount of
! 32: resources for support and development, going forward. However, ESnet
! 33: could issue new iperf3 releases to deal with security issues or
! 34: high-impact bug fixes.
! 35:
! 36: For more information see: http://software.es.net/iperf
! 37:
! 38: Source code and issue tracker: https://github.com/esnet/iperf
! 39:
! 40: Obtaining iperf3
! 41: ----------------
! 42:
! 43: Downloads of iperf3 are available at:
! 44:
! 45: http://downloads.es.net/pub/iperf/
! 46:
! 47: To check out the most recent code, clone the git repository at:
! 48:
! 49: https://github.com/esnet/iperf.git
! 50:
! 51: Building iperf3
! 52: ---------------
! 53:
! 54: ### Prerequisites: ###
! 55:
! 56: None.
! 57:
! 58: ### Building ###
! 59:
! 60: ./configure; make; make install
! 61:
! 62: (Note: If configure fails, try running `./bootstrap.sh` first)
! 63:
! 64: Invoking iperf3
! 65: ---------------
! 66:
! 67: iperf3 includes a manual page listing all of the command-line options.
! 68: The manual page is the most up-to-date reference to the various flags and parameters.
! 69:
! 70: For sample command line usage, see:
! 71:
! 72: http://fasterdata.es.net/performance-testing/network-troubleshooting-tools/iperf-and-iperf3/
! 73:
! 74: Using the default options, iperf is meant to show typical well
! 75: designed application performance. 'Typical well designed application'
! 76: means avoiding artificial enhancements that work only for testing
! 77: (such as splice()'ing the data to /dev/null). iperf does also have
! 78: flags for 'extreme best case' optimizations but they must be
! 79: explicitly activated.
! 80:
! 81: These flags include:
! 82:
! 83: -Z, --zerocopy use a 'zero copy' sendfile() method of sending data
! 84: -A, --affinity n/n,m set CPU affinity
! 85:
! 86: Bug Reports
! 87: -----------
! 88:
! 89: Before submitting a bug report, please make sure you're running the
! 90: latest version of the code, and confirm that your issue has not
! 91: already been fixed. Then submit to the iperf3 issue tracker on
! 92: GitHub:
! 93:
! 94: https://github.com/esnet/iperf/issues
! 95:
! 96: In your issue submission, please indicate the version of iperf3 and
! 97: what platform you're trying to run on (provide the platform
! 98: information even if you're not using a supported platform, we
! 99: *might* be able to help anyway). Exact command-line arguments will
! 100: help us recreate your problem. If you're getting error messages,
! 101: please include them verbatim if possible, but remember to sanitize any
! 102: sensitive information.
! 103:
! 104: If you have a question about usage or about the code, please do *not*
! 105: submit an issue. Please use one of the mailing lists for that.
! 106:
! 107: Changes from iperf 2.x
! 108: ----------------------
! 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: * UDP performance: Some problems have been noticed with iperf3 on the
! 148: ESnet 100G testbed at high UDP rates (above 10Gbps). The symptom is
! 149: that on any particular run of iperf3 the receiver reports a loss rate
! 150: of about 20%, regardless of the -b option used on the client side.
! 151: This problem appears not to be iperf3-specific, and may be due to the
! 152: placement of the iperf3 process on a CPU and its relation to the
! 153: inbound NIC. In some cases this problem can be mitigated by an
! 154: appropriate use of the CPU affinity (-A) option. (Issue #55)
! 155:
! 156: * The -Z flag sometimes causes the iperf3 client to hang on OSX.
! 157: (Issue #129)
! 158:
! 159: * When specifying the socket buffer size using the "-w" flag on Linux, Linux
! 160: doubles the value you pass in. (You can see this using iperf3's debug flag).
! 161: But then the CWND does not actually ramp up to the doubled value, but only
! 162: to about 75% of the doubled value. This appears to be by design.
! 163:
! 164: * Although the "-w" flag is documented as setting the (TCP) window
! 165: size, it is also used to set the socket buffer size. This has been
! 166: shown to be helpful with high-bitrate UDP tests.
! 167:
! 168: * On some platforms, it might be necessary to invoke "ldconfig"
! 169: manually after doing a "make install" before the iperf3 executable can
! 170: find its shared library. (Issue #153)
! 171:
! 172: * The results printed on the server side at the end of a test do not
! 173: correctly reflect the client-side measurements. This is due to the
! 174: ordering of computing and transferring results between the client
! 175: and server. (Issue #293)
! 176:
! 177: * The server could have a very short measurement reporting interval at
! 178: the end of a test (particularly a UDP test), containing few or no
! 179: packets. This issue is due to an artifact of timing between the
! 180: client and server. (Issue #278)
! 181:
! 182: Links
! 183: -----
! 184:
! 185: This section lists links to user-contributed Web pages regarding
! 186: iperf3. ESnet and Lawrence Berkeley National Laboratory bear no
! 187: responsibility for the content of these pages.
! 188:
! 189: * Installation instructions for Debian Linux (by Cameron Camp
! 190: <cameron@ivdatacenter.com>):
! 191:
! 192: http://cheatsheet.logicalwebhost.com/iperf-network-testing/
! 193:
! 194: Copyright
! 195: ---------
! 196:
! 197: iperf, Copyright (c) 2014-2016, The Regents of the University of
! 198: California, through Lawrence Berkeley National Laboratory (subject
! 199: to receipt of any required approvals from the U.S. Dept. of
! 200: Energy). All rights reserved.
! 201:
! 202: If you have questions about your rights to use or distribute this
! 203: software, please contact Berkeley Lab's Technology Transfer
! 204: Department at TTD@lbl.gov.
! 205:
! 206: NOTICE. This software is owned by the U.S. Department of Energy.
! 207: As such, the U.S. Government has been granted for itself and others
! 208: acting on its behalf a paid-up, nonexclusive, irrevocable,
! 209: worldwide license in the Software to reproduce, prepare derivative
! 210: works, and perform publicly and display publicly. Beginning five
! 211: (5) years after the date permission to assert copyright is obtained
! 212: from the U.S. Department of Energy, and subject to any subsequent
! 213: five (5) year renewals, the U.S. Government is granted for itself
! 214: and others acting on its behalf a paid-up, nonexclusive,
! 215: irrevocable, worldwide license in the Software to reproduce,
! 216: prepare derivative works, distribute copies to the public, perform
! 217: publicly and display publicly, and to permit others to do so.
! 218:
! 219: This code is distributed under a BSD style license, see the LICENSE
! 220: file for complete information.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README.md CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / iperf