Return to README.md CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / iperf

Version 3.15

    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 Ubuntu 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: Discussion forums: https://github.com/esnet/iperf/discussions
   34: 
   35: Obtaining iperf3
   36: ----------------
   37: 
   38: Downloads of iperf3 are available at:
   39: 
   40:     https://downloads.es.net/pub/iperf/
   41: 
   42: To check out the most recent code, clone the git repository at:
   43: 
   44:     https://github.com/esnet/iperf.git
   45: 
   46: Building iperf3
   47: ---------------
   48: 
   49: ### Prerequisites: ###
   50: 
   51: None.
   52: 
   53: ### Building ###
   54: 
   55:     ./configure; make; make install
   56: 
   57: (Note: If configure fails, try running `./bootstrap.sh` first)
   58: 
   59: Invoking iperf3
   60: ---------------
   61: 
   62: iperf3 includes a manual page listing all of the command-line options.
   63: The manual page is the most up-to-date reference to the various flags and parameters.
   64: 
   65: For sample command line usage, see:
   66: 
   67: https://fasterdata.es.net/performance-testing/network-troubleshooting-tools/iperf/
   68: 
   69: Using the default options, iperf is meant to show typical well
   70: designed application performance.  "Typical well designed application"
   71: means avoiding artificial enhancements that work only for testing
   72: (such as splice()'ing the data to /dev/null).  iperf does also have
   73: flags for "extreme best case" optimizations, but they must be
   74: explicitly activated.
   75: 
   76: These flags include:
   77: 
   78:     -Z, --zerocopy            use a 'zero copy' sendfile() method of sending data
   79:     -A, --affinity n/n,m      set CPU affinity
   80: 
   81: Bug and Security Reports
   82: ------------------------
   83: 
   84: Before submitting a bug report, please make sure you're running the
   85: latest version of the code, and confirm that your issue has not
   86: already been fixed.  Then submit to the iperf3 issue tracker on
   87: GitHub:
   88: 
   89: https://github.com/esnet/iperf/issues
   90: 
   91: In your issue submission, please indicate the version of iperf3 and
   92: what platform you're trying to run on (provide the platform
   93: information even if you're not using a supported platform, we
   94: *might* be able to help anyway).  Exact command-line arguments will
   95: help us recreate your problem.  If you're getting error messages,
   96: please include them verbatim if possible, but remember to sanitize any
   97: sensitive information.
   98: 
   99: If you have a question about usage or about the code, please do *not*
  100: submit an issue.  Please use one of the mailing lists for that.
  101: 
  102: If you suspect there is a potential security issue, please contact the
  103: developers at:
  104: 
  105: iperf@es.net
  106: 
  107: Relation to iperf 2.x
  108: ---------------------
  109: 
  110: Although iperf2 and iperf3 both measure network performance,
  111: they are not compatible with each other.
  112: The projects (as of mid-2021) are in active, but separate, development.
  113: The continuing iperf2 development
  114: project can be found at https://sourceforge.net/projects/iperf2/.
  115: 
  116: iperf3 contains a number of options and functions not present in
  117: iperf2.  In addition, some flags are changed from their iperf2
  118: counterparts:
  119: 
  120:     -C, --linux-congestion    set congestion control algorithm (Linux only)
  121:                               (-Z in iperf2)
  122:     --bidir                   bidirectional testing mode
  123:                               (-d in iperf2)
  124: 
  125: Some iperf2 options are not available in iperf3:
  126: 
  127:     -r, --tradeoff           Do a bidirectional test individually
  128:     -T, --ttl                time-to-live, for multicast (default 1)
  129:     -x, --reportexclude [CDMSV]   exclude C(connection) D(data) M(multicast)
  130:                                   S(settings) V(server) reports
  131:     -y, --reportstyle C      report as a Comma-Separated Values
  132: 
  133: Also removed is the ability to set the options via environment
  134: variables.
  135: 
  136: Known Issues
  137: ------------
  138: 
  139: A set of known issues is maintained on the iperf3 Web pages:
  140: 
  141: https://software.es.net/iperf/dev.html#known-issues
  142: 
  143: Links
  144: -----
  145: 
  146: This section lists links to user-contributed Web pages regarding
  147: iperf3.  ESnet and Lawrence Berkeley National Laboratory bear no
  148: responsibility for the content of these pages.
  149: 
  150: * Installation instructions for Debian Linux (by Cameron Camp
  151:   <cameron@ivdatacenter.com>):
  152: 
  153:   http://cheatsheet.logicalwebhost.com/iperf-network-testing/
  154: 
  155: Copyright
  156: ---------
  157: 
  158: iperf, Copyright (c) 2014-2023, The Regents of the University of
  159: California, through Lawrence Berkeley National Laboratory (subject
  160: to receipt of any required approvals from the U.S. Dept. of
  161: Energy).  All rights reserved.
  162: 
  163: If you have questions about your rights to use or distribute this
  164: software, please contact Berkeley Lab's Technology Transfer
  165: Department at TTD@lbl.gov.
  166: 
  167: NOTICE.  This software is owned by the U.S. Department of Energy.
  168: As such, the U.S. Government has been granted for itself and others
  169: acting on its behalf a paid-up, nonexclusive, irrevocable,
  170: worldwide license in the Software to reproduce, prepare derivative
  171: works, and perform publicly and display publicly.  Beginning five
  172: (5) years after the date permission to assert copyright is obtained
  173: from the U.S. Department of Energy, and subject to any subsequent
  174: five (5) year renewals, the U.S. Government is granted for itself
  175: and others acting on its behalf a paid-up, nonexclusive,
  176: irrevocable, worldwide license in the Software to reproduce,
  177: prepare derivative works, distribute copies to the public, perform
  178: publicly and display publicly, and to permit others to do so.
  179: 
  180: This code is distributed under a BSD style license, see the LICENSE
  181: file for complete information.