|
version 1.1.1.2, 2021/03/17 00:36:46
|
version 1.1.1.3, 2023/09/27 11:14:54
|
|
Line 1
|
Line 1
|
| .TH IPERF3 1 "July 2020" ESnet "User Manuals" | .TH IPERF3 1 "September 2022" ESnet "User Manuals" |
| .SH NAME |
.SH NAME |
| iperf3 \- perform network throughput tests |
iperf3 \- perform network throughput tests |
| .SH SYNOPSIS |
.SH SYNOPSIS |
|
Line 6 iperf3 \- perform network throughput tests
|
Line 6 iperf3 \- perform network throughput tests
|
| .I options |
.I options |
| .B ] |
.B ] |
| .br |
.br |
| .B iperf3 -c | .B iperf3 -c |
| .I server |
.I server |
| .B [ |
.B [ |
| .I options |
.I options |
|
Line 96 test by specifying the --get-server-output flag.
|
Line 96 test by specifying the --get-server-output flag.
|
| Either the client or the server can produce its output in a JSON |
Either the client or the server can produce its output in a JSON |
| structure, useful for integration with other programs, by passing it |
structure, useful for integration with other programs, by passing it |
| the -J flag. |
the -J flag. |
| Because the contents of the JSON structure are only competely known | Because the contents of the JSON structure are only completely known |
| after the test has finished, no JSON output will be emitted until the |
after the test has finished, no JSON output will be emitted until the |
| end of the test. |
end of the test. |
| .PP |
.PP |
|
Line 117 set server port to listen on/connect to to \fIn\fR (de
|
Line 117 set server port to listen on/connect to to \fIn\fR (de
|
| pause \fIn\fR seconds between periodic throughput reports; |
pause \fIn\fR seconds between periodic throughput reports; |
| default is 1, use 0 to disable |
default is 1, use 0 to disable |
| .TP |
.TP |
| |
.BR -I ", " --pidfile " \fIfile\fR" |
| |
write a file with the process ID, most useful when running as a daemon. |
| |
.TP |
| .BR -F ", " --file " \fIname\fR" |
.BR -F ", " --file " \fIname\fR" |
| Use a file as the source (on the sender) or sink (on the receiver) of |
Use a file as the source (on the sender) or sink (on the receiver) of |
| data, rather than just generating random data or throwing it away. |
data, rather than just generating random data or throwing it away. |
|
Line 134 In addition, on the client side you can override the s
|
Line 137 In addition, on the client side you can override the s
|
| affinity for just that one test, using the \fIn,m\fR form of |
affinity for just that one test, using the \fIn,m\fR form of |
| argument. |
argument. |
| Note that when using this feature, a process will only be bound |
Note that when using this feature, a process will only be bound |
| to a single CPU (as opposed to a set containing potentialy multiple | to a single CPU (as opposed to a set containing potentially multiple |
| CPUs). |
CPUs). |
| .TP |
.TP |
| .BR -B ", " --bind " \fIhost\fR" | .BR -B ", " --bind " \fIhost\fR[\fB%\fIdev\fR]" |
| bind to the specific interface associated with address \fIhost\fR. |
bind to the specific interface associated with address \fIhost\fR. |
| |
If an optional interface is specified, it is treated as a shortcut |
| |
for \fB--bind-dev \fIdev\fR. |
| |
Note that a percent sign and interface device name are required for IPv6 link-local address literals. |
| .TP |
.TP |
| |
.BR --bind-dev " \fIdev\fR" |
| |
bind to the specified network interface. |
| |
This option uses SO_BINDTODEVICE, and may require root permissions. |
| |
(Available on Linux and possibly other systems.) |
| |
.TP |
| .BR -V ", " --verbose " " |
.BR -V ", " --verbose " " |
| give more detailed output | give more detailed output |
| .TP |
.TP |
| .BR -J ", " --json " " |
.BR -J ", " --json " " |
| output in JSON format |
output in JSON format |
|
Line 153 send output to a log file.
|
Line 164 send output to a log file.
|
| force flushing output at every interval. |
force flushing output at every interval. |
| Used to avoid buffering when sending output to pipe. |
Used to avoid buffering when sending output to pipe. |
| .TP |
.TP |
| .BR --timestamps " [\fIformat\fR]" | .BR --timestamps "[\fB=\fIformat\fR]" |
| prepend a timestamp at the start of each output line. |
prepend a timestamp at the start of each output line. |
| By default, timestamps have the format emitted by |
By default, timestamps have the format emitted by |
| .BR ctime ( 1 ). |
.BR ctime ( 1 ). |
| Optionally, a format specification can be passed to customize the | Optionally, \fC=\fR followed by |
| | a format specification can be passed to customize the |
| timestamps, see |
timestamps, see |
| .BR strftime ( 3 ). |
.BR strftime ( 3 ). |
| |
If this optional format is given, the \fC=\fR must immediately |
| |
follow the \fB--timestamps\fR option with no whitespace intervening. |
| .TP |
.TP |
| |
.BR --rcv-timeout " \fI#\fR" |
| |
set idle timeout for receiving data during active tests. The receiver |
| |
will halt a test if no data is received from the sender for this |
| |
number of ms (default to 12000 ms, or 2 minutes). |
| |
.TP |
| |
.BR --snd-timeout " \fI#\fR" |
| |
set timeout for unacknowledged TCP data (on both test and control |
| |
connections) This option can be used to force a faster test timeout |
| |
in case of a network partition during a test. The required |
| |
parameter is specified in ms, and defaults to the system settings. |
| |
This functionality depends on the TCP_USER_TIMEOUT socket option, and |
| |
will not work on systems that do not support it. |
| |
.TP |
| .BR -d ", " --debug " " |
.BR -d ", " --debug " " |
| emit debugging output. |
emit debugging output. |
| Primarily (perhaps exclusively) of use to developers. |
Primarily (perhaps exclusively) of use to developers. |
|
Line 179 run in server mode
|
Line 206 run in server mode
|
| .BR -D ", " --daemon " " |
.BR -D ", " --daemon " " |
| run the server in background as a daemon |
run the server in background as a daemon |
| .TP |
.TP |
| .BR -I ", " --pidfile " \fIfile\fR" |
|
| write a file with the process ID, most useful when running as a daemon. |
|
| .TP |
|
| .BR -1 ", " --one-off |
.BR -1 ", " --one-off |
| handle one client connection, then exit. | handle one client connection, then exit. If an idle time is set, the |
| | server will exit after that amount of time with no connection. |
| .TP |
.TP |
| |
.BR --idle-timeout " \fIn\fR" |
| |
restart the server after \fIn\fR seconds in case it gets stuck. In |
| |
one-off mode, this is the number of seconds the server will wait |
| |
before exiting. |
| |
.TP |
| .BR --server-bitrate-limit " \fIn\fR[KMGT]" |
.BR --server-bitrate-limit " \fIn\fR[KMGT]" |
| set a limit on the server side, which will cause a test to abort if |
set a limit on the server side, which will cause a test to abort if |
| the client specifies a test of more than \fIn\fR bits per second, or |
the client specifies a test of more than \fIn\fR bits per second, or |
|
Line 195 the data rate is 5 seconds by default, but can be spec
|
Line 225 the data rate is 5 seconds by default, but can be spec
|
| a '/' and a number to the bitrate specifier. |
a '/' and a number to the bitrate specifier. |
| .TP |
.TP |
| .BR --rsa-private-key-path " \fIfile\fR" |
.BR --rsa-private-key-path " \fIfile\fR" |
| path to the RSA private key (not password-protected) used to decrypt | path to the RSA private key (not password-protected) used to decrypt |
| authentication credentials from the client (if built with OpenSSL |
authentication credentials from the client (if built with OpenSSL |
| support). |
support). |
| .TP | .TP |
| .BR --authorized-users-path " \fIfile\fR" |
.BR --authorized-users-path " \fIfile\fR" |
| path to the configuration file containing authorized users credentials to run | path to the configuration file containing authorized users credentials to run |
| iperf tests (if built with OpenSSL support). |
iperf tests (if built with OpenSSL support). |
| The file is a comma separated list of usernames and password hashes; |
The file is a comma separated list of usernames and password hashes; |
| more information on the structure of the file can be found in the |
more information on the structure of the file can be found in the |
| EXAMPLES section. |
EXAMPLES section. |
| |
.TP |
| |
.BR --time-skew-threshold second " \fIseconds\fR" |
| |
time skew threshold (in seconds) between the server and client |
| |
during the authentication process. |
| .SH "CLIENT SPECIFIC OPTIONS" |
.SH "CLIENT SPECIFIC OPTIONS" |
| .TP |
.TP |
| .BR -c ", " --client " \fIhost\fR" | .BR -c ", " --client " \fIhost\fR[\fB%\fIdev\fR]" |
| run in client mode, connecting to the specified server. |
run in client mode, connecting to the specified server. |
| By default, a test consists of sending data from the client to the |
By default, a test consists of sending data from the client to the |
| server, unless the \-R flag is specified. |
server, unless the \-R flag is specified. |
| |
If an optional interface is specified, it is treated as a shortcut |
| |
for \fB--bind-dev \fIdev\fR. |
| |
Note that a percent sign and interface device name are required for IPv6 link-local address literals. |
| .TP |
.TP |
| .BR --sctp |
.BR --sctp |
| use SCTP rather than TCP (FreeBSD and Linux) |
use SCTP rather than TCP (FreeBSD and Linux) |
|
Line 300 test in both directions (normal and reverse), with bot
|
Line 337 test in both directions (normal and reverse), with bot
|
| server sending and receiving data simultaneously |
server sending and receiving data simultaneously |
| .TP |
.TP |
| .BR -w ", " --window " \fIn\fR[KMGT]" |
.BR -w ", " --window " \fIn\fR[KMGT]" |
| window size / socket buffer size (this gets sent to the server and used on that side too) | set socket buffer size / window size. |
| | This value gets sent to the server and used on that side too; on both |
| | sides this option sets both the sending and receiving socket buffer sizes. |
| | This option can be used to set (indirectly) the maximum TCP window size. |
| | Note that on Linux systems, the effective maximum window size is approximately |
| | double what is specified by this option (this behavior is not a bug in iperf3 |
| | but a "feature" of the Linux kernel, as documented by tcp(7) and socket(7)). |
| .TP |
.TP |
| .BR -M ", " --set-mss " \fIn\fR" |
.BR -M ", " --set-mss " \fIn\fR" |
| set TCP/SCTP maximum segment size (MTU - 40 bytes) |
set TCP/SCTP maximum segment size (MTU - 40 bytes) |
|
Line 348 Use a "zero copy" method of sending data, such as send
|
Line 391 Use a "zero copy" method of sending data, such as send
|
| instead of the usual write(2). |
instead of the usual write(2). |
| .TP |
.TP |
| .BR -O ", " --omit " \fIn\fR" |
.BR -O ", " --omit " \fIn\fR" |
| Omit the first n seconds of the test, to skip past the TCP slow-start | Perform pre-test for N seconds and omit the pre-test statistics, to skip past the TCP slow-start |
| period. |
period. |
| .TP |
.TP |
| .BR -T ", " --title " \fIstr\fR" |
.BR -T ", " --title " \fIstr\fR" |
|
Line 386 It might help to test and reveal problems in networkin
|
Line 429 It might help to test and reveal problems in networkin
|
| compression (including some WiFi access points), where iperf2 and iperf3 |
compression (including some WiFi access points), where iperf2 and iperf3 |
| perform differently, just based on payload entropy. |
perform differently, just based on payload entropy. |
| .TP |
.TP |
| .BR --username " \fIusername\fR" | .BR --dont-fragment |
| | Set the IPv4 Don't Fragment (DF) bit on outgoing packets. |
| | Only applicable to tests doing UDP over IPv4. |
| | .TP |
| | .BR --username " \fIusername\fR" |
| username to use for authentication to the iperf server (if built with |
username to use for authentication to the iperf server (if built with |
| OpenSSL support). |
OpenSSL support). |
| The password will be prompted for interactively when the test is run. Note, |
The password will be prompted for interactively when the test is run. Note, |
| the password to use can also be specified via the IPERF3_PASSWORD environment |
the password to use can also be specified via the IPERF3_PASSWORD environment |
| variable. If this variable is present, the password prompt will be skipped. |
variable. If this variable is present, the password prompt will be skipped. |
| .TP |
.TP |
| .BR --rsa-public-key-path " \fIfile\fR" | .BR --rsa-public-key-path " \fIfile\fR" |
| path to the RSA public key used to encrypt authentication credentials |
path to the RSA public key used to encrypt authentication credentials |
| (if built with OpenSSL support) |
(if built with OpenSSL support) |
| |
|
| .SH EXAMPLES |
.SH EXAMPLES |
| .SS "Authentication - RSA Keypair" |
.SS "Authentication - RSA Keypair" |
| The authentication feature of iperf3 requires an RSA public keypair. |
The authentication feature of iperf3 requires an RSA public keypair. |
| The public key is used to encrypt the authentication token containing the | 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. |
user credentials, while the private key is used to decrypt the authentication token. |
| An example of a set of UNIX/Linux commands to generate correct keypair follows: | The private key must be in PEM format and additionally must not have a |
| .sp 1 | 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: |
| | .sp 1 |
| .in +.5i |
.in +.5i |
| > openssl genrsa -des3 -out private.pem 2048 |
> openssl genrsa -des3 -out private.pem 2048 |
| .sp 0 |
.sp 0 |
| > openssl rsa -in private.pem -outform PEM -pubout -out public.pem |
> openssl rsa -in private.pem -outform PEM -pubout -out public.pem |
| .sp 0 |
.sp 0 |
| > openssl rsa -in private.pem -out private_not_protected.pem -outform PEM | > openssl rsa -in private.pem -out private_not_protected.pem -outform PEM |
| .in -.5i |
.in -.5i |
| .sp 1 |
.sp 1 |
| After these commands, the public key will be contained in the file |
After these commands, the public key will be contained in the file |
| public.pem and the private key will be contained in the file |
public.pem and the private key will be contained in the file |
| private_not_protected.pem. |
private_not_protected.pem. |
| .SS "Authentication - Authorized users configuration file" |
.SS "Authentication - Authorized users configuration file" |
| A simple plaintext file must be provided to the iperf3 server in order to specify | A simple plaintext file must be provided to the iperf3 server in order to specify |
| the authorized user credentials. |
the authorized user credentials. |
| The file is a simple list of comma-separated pairs of a username and a |
The file is a simple list of comma-separated pairs of a username and a |
| corresponding password hash. |
corresponding password hash. |
|
Line 425 The file can also contain commented lines (starting wi
|
Line 476 The file can also contain commented lines (starting wi
|
| character). |
character). |
| An example of commands to generate the password hash on a UNIX/Linux system |
An example of commands to generate the password hash on a UNIX/Linux system |
| is given below: |
is given below: |
| .sp 1 | .sp 1 |
| .in +.5i |
.in +.5i |
| > S_USER=mario S_PASSWD=rossi |
> S_USER=mario S_PASSWD=rossi |
| .sp 0 |
.sp 0 |
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to iperf3.1 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / iperf / src