DOCSEARCHbyAlgolia
Submit Docs

iperf3 Documentation

repository·master·Indexed 27 days ago

https://github.com/esnet/iperf

A tool for active measurement of the maximum achievable bandwidth on IP networks, supporting TCP, UDP, and SCTP. Includes a library version (libiperf) for integration into other programs. Documentation covers building from source, extreme best-case optimizations using zero-copy and CPU affinity, JSON output conversion for gnuplot, and developer guidelines for release engineering and bug reporting.

Tokens
8.2K
Snippets
28
Records
100
Agent score
88%

What's inside iperf3

  1. Overview of iperf3

    master

    iperf3 is a tool for performing active measurements to determine the maximum achievable bandwidth on IP networks. It supports tuning of various parameters related to timing, protocols, and buffers, reporting measured throughput, loss, and other parameters for each test.

    Key features include:

    • Support for TCP, UDP, and SCTP protocols.
    • Zero-copy mode.
    • Optional JSON output.
    • A library version of the functionality for use in other programs.

    Note: iperf3 is not backwards compatible with the original iperf (iperf2).

  3. Build and install iperf3 from source

    master

    To build and install iperf3 from an unpacked source distribution, use the standard configure, make, and install sequence. If the configuration step fails, run ./bootstrap.sh from the top-level directory before attempting to configure again.

    ./configure && make && make install

  4. Install Sphinx and sphinx-bootstrap-theme using MacPorts

    master

    Use these commands to install the required documentation dependencies using MacPorts.

    port install python27 py27-pip py27-sphinx
port select pip py27-pip
port select sphinx py27-sphinx
pip install sphinx sphinx-bootstrap-theme

  5. Prepare a release using the Release Engineering Checklist

    master

    When preparing a new release of iperf3, follow these core steps to ensure consistency and correctness:

    1. Initialize: Start from a clean source tree (git status should be empty) with up-to-date autoconf and automake installed.
    2. Branching: Create a dedicated release engineering branch from the tip of master (e.g., releng-3.20).
    3. Metadata Updates:
      • Verify copyright dates in README.md and LICENSE.
      • Update README.md and RELNOTES.md with the new version and release date.
      • Bump the version number in configure.ac (inside the AC_INIT macro).
      • Update manpage revision dates in src/iperf3.1 and src/libiperf.3 if necessary.
    4. Regeneration: Run ./bootstrap.sh to regenerate the configure script and other build artifacts.
    5. Artifact Creation: Use the provided make_release script to create the tag and the distribution tarball with its SHA256 checksum.
    6. Verification: Verify the version string via iperf3 --version matches the artifact version and ensure the tarball is a valid gzipped tarball.
    # Create a release branch
git branch releng-3.20
git checkout releng-3.20

# Update version in configure.ac
vi configure.ac

# Regenerate build scripts
./bootstrap.sh

# Create release artifacts
./make_release tag 3.20
./make_release tar 3.20

  6. Build iperf3 from source

    master

    To build iperf3, ensure you have the necessary build environment. If the standard ./configure step fails, run ./bootstrap.sh first to prepare the build system.

    Build steps:

    ./configure; make; make install

  7. Generate an updated online manual page

    master

    If the online manual requires an update, you can generate a text version of the manpage using nroff and then import it into invoking.rst using the following command sequence:

    TERM=
export TERM
nroff -Tascii -c -man src/iperf3.1 | ul | sed 's/^/   /' > iperf3.txt

  9. Report bugs and security issues in iperf3

    master

    Before submitting a bug report, ensure you are using the latest version of the code and check the FAQ to see if the issue is already known.

    • General Bugs: Submit issues via the GitHub issue tracker: https://github.com/esnet/iperf/issues
    • Security Issues: Report potential security vulnerabilities by contacting the developers directly at iperf@es.net.

    Note: Do not use the old Google Code issue tracker; submissions there will be ignored.

  12. Clone the iperf3 source code repository

    master

    The iperf3 project is hosted on GitHub. You can check out the source code directly using Git. Primary development occurs on Ubuntu Linux, FreeBSD, and macOS.

    git clone https://github.com/esnet/iperf.git