IPERF3(1) | User Manuals | IPERF3(1) |
iperf3 - perform network throughput tests
iperf3 -s [ options ]
iperf3 -c server [ options ]
iperf3 is a tool for performing network throughput measurements. It can test TCP, UDP, or SCTP throughput. To perform an iperf3 test the user must establish both a server and a client.
The iperf3 executable contains both client and server functionality. An iperf3 server can be started using either of the -s or --server command-line parameters, for example:
Note that many iperf3 parameters have both short (-s) and long (--server) forms. In this section we will generally use the short form of command-line flags, unless only the long form of a flag is available.
By default, the iperf3 server listens on TCP port 5201 for connections from an iperf3 client. A custom port can be specified by using the -p flag, for example:
After the server is started, it will listen for connections from iperf3 clients (in other words, the iperf3 program run in client mode). The client mode can be started using the -c command-line option, which also requires a host to which iperf3 should connect. The host can by specified by hostname, IPv4 literal, or IPv6 literal:
If the iperf3 server is running on a non-default TCP port, that port number needs to be specified on the client as well:
The initial TCP connection is used to exchange test parameters, control the start and end of the test, and to exchange test results. This is sometimes referred to as the "control connection". The actual test data is sent over a separate TCP connection, as a separate flow of UDP packets, or as an independent SCTP connection, depending on what protocol was specified by the client.
Normally, the test data is sent from the client to the server, and measures the upload speed of the client. Measuring the download speed from the server can be done by specifying the -R flag on the client. This causes data to be sent from the server to the client.
Results are displayed on both the client and server. There will be at least one line of output per measurement interval (by default a measurement interval lasts for one second, but this can be changed by the -i option). Each line of output includes (at least) the time since the start of the test, amount of data transferred during the interval, and the average bitrate over that interval. Note that the values for each measurement interval are taken from the point of view of the endpoint process emitting that output (in other words, the output on the client shows the measurement interval data for the client.
At the end of the test is a set of statistics that shows (at least as much as possible) a summary of the test as seen by both the sender and the receiver, with lines tagged accordingly. Recall that by default the client is the sender and the server is the receiver, although as indicated above, use of the -R flag will reverse these roles.
The client can be made to retrieve the server-side output for a given test by specifying the --get-server-output flag.
Either the client or the server can produce its output in a JSON structure, useful for integration with other programs, by passing it the -J flag. Normally the contents of the JSON structure are only competely known after the test has finished, no JSON output will be emitted until the end of the test. By enabling line-delimited JSON multiple objects will be emitted to provide a real-time parsable JSON output.
iperf3 has a (overly) large set of command-line options that can be used to set the parameters of a test. They are given in the "GENERAL OPTIONS" section of the manual page below, as well as summarized in iperf3's help output, which can be viewed by running iperf3 with the -h flag.
The authentication feature of iperf3 requires an RSA public keypair. The public key is used to encrypt the authentication token containing the user credentials, while the private key is used to decrypt the authentication token. The private key must be in PEM format and additionally must not have a password set. The public key must be in PEM format and use SubjectPrefixKeyInfo encoding. An example of a set of UNIX/Linux commands using OpenSSL to generate a correctly-formed keypair follows:
> openssl genrsa -des3 -out private.pem 2048
> openssl rsa -in private.pem -outform PEM -pubout -out public.pem
> openssl rsa -in private.pem -out private_not_protected.pem
-outform PEM
After these commands, the public key will be contained in the file public.pem and the private key will be contained in the file private_not_protected.pem.
A simple plaintext file must be provided to the iperf3 server in order to specify the authorized user credentials. The file is a simple list of comma-separated pairs of a username and a corresponding password hash. The password hash is a SHA256 hash of the string "{$user}$password". The file can also contain commented lines (starting with the # character). An example of commands to generate the password hash on a UNIX/Linux system is given below:
> S_USER=mario S_PASSWD=rossi
> echo -n "{$S_USER}$S_PASSWD" | sha256sum | awk '{
print $1 }'
An example of a password file (with an entry corresponding to the above username and password) is given below:
> cat credentials.csv
# file format: username,sha256
mario,bf7a49a846d44b454a5d11e7acfaf13d138bbe0b7483aa3e050879700572709b
A list of the contributors to iperf3 can be found within the documentation located at https://software.es.net/iperf/dev.html#authors.
libiperf(3), https://software.es.net/iperf
May 2024 | ESnet |