Annotation of embedaddon/iperf/README.md, revision 1.1.1.3

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
1.1.1.2   misho      10: the measured throughput / bitrate, loss, and other parameters.
1.1       misho      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
1.1.1.2   misho      16: other programs. iperf3 also has a number of features found in other tools
1.1       misho      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: 
1.1.1.3 ! misho      21: Primary development for iperf3 takes place on Ubuntu Linux, FreeBSD,
1.1.1.2   misho      22: and macOS.  At this time, these are the only officially supported
1.1       misho      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: 
1.1.1.2   misho      29: For more information see: https://software.es.net/iperf
1.1       misho      30: 
                     31: Source code and issue tracker: https://github.com/esnet/iperf
                     32: 
1.1.1.3 ! misho      33: Discussion forums: https://github.com/esnet/iperf/discussions
        !            34: 
1.1       misho      35: Obtaining iperf3
                     36: ----------------
                     37: 
                     38: Downloads of iperf3 are available at:
                     39: 
1.1.1.2   misho      40:     https://downloads.es.net/pub/iperf/
1.1       misho      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: 
1.1.1.3 ! misho      65: For sample command line usage, see:
1.1       misho      66: 
1.1.1.2   misho      67: https://fasterdata.es.net/performance-testing/network-troubleshooting-tools/iperf/
1.1       misho      68: 
                     69: Using the default options, iperf is meant to show typical well
1.1.1.2   misho      70: designed application performance.  "Typical well designed application"
1.1       misho      71: means avoiding artificial enhancements that work only for testing
                     72: (such as splice()'ing the data to /dev/null).  iperf does also have
1.1.1.2   misho      73: flags for "extreme best case" optimizations, but they must be
1.1       misho      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: 
1.1.1.3 ! misho      81: Bug and Security Reports
        !            82: ------------------------
1.1       misho      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: 
1.1.1.3 ! misho     102: If you suspect there is a potential security issue, please contact the
        !           103: developers at:
        !           104: 
        !           105: iperf@es.net
        !           106: 
1.1.1.2   misho     107: Relation to iperf 2.x
                    108: ---------------------
1.1       misho     109: 
1.1.1.3 ! misho     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
1.1.1.2   misho     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:
1.1       misho     119: 
                    120:     -C, --linux-congestion    set congestion control algorithm (Linux only)
                    121:                               (-Z in iperf2)
1.1.1.2   misho     122:     --bidir                   bidirectional testing mode
                    123:                               (-d in iperf2)
1.1       misho     124: 
1.1.1.2   misho     125: Some iperf2 options are not available in iperf3:
1.1       misho     126: 
                    127:     -r, --tradeoff           Do a bidirectional test individually
                    128:     -T, --ttl                time-to-live, for multicast (default 1)
1.1.1.3 ! misho     129:     -x, --reportexclude [CDMSV]   exclude C(connection) D(data) M(multicast)
1.1       misho     130:                                   S(settings) V(server) reports
                    131:     -y, --reportstyle C      report as a Comma-Separated Values
                    132: 
1.1.1.2   misho     133: Also removed is the ability to set the options via environment
1.1       misho     134: variables.
                    135: 
                    136: Known Issues
                    137: ------------
                    138: 
1.1.1.2   misho     139: A set of known issues is maintained on the iperf3 Web pages:
                    140: 
                    141: https://software.es.net/iperf/dev.html#known-issues
1.1       misho     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: 
1.1.1.3 ! misho     158: iperf, Copyright (c) 2014-2023, The Regents of the University of
1.1       misho     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.

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>