From d4f8999e6b55cff486e80002be21f21e341c92b8 Mon Sep 17 00:00:00 2001 From: "Bruce A. Mah" Date: Tue, 1 Jun 2021 08:43:54 -0700 Subject: [PATCH] docs: Update for iperf-3.10 manpage. --- docs/invoking.rst | 192 ++++++++++++++++++++++++++++------------------ 1 file changed, 116 insertions(+), 76 deletions(-) diff --git a/docs/invoking.rst b/docs/invoking.rst index b1fc5c2..9726d69 100644 --- a/docs/invoking.rst +++ b/docs/invoking.rst @@ -136,29 +136,34 @@ the executable. pause n seconds between periodic throughput reports; default is 1, use 0 to disable + -I, --pidfile file + write a file with the process ID, most useful when running as a + daemon. + -F, --file name - 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. This feature is used for finding whether or - not the storage subsystem is the bottleneck for file transfers. - It does not turn iperf3 into a file transfer tool. The length, - attributes, and in some cases contents of the received file may + 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. This feature is used for finding whether or + not the storage subsystem is the bottleneck for file transfers. + It does not turn iperf3 into a file transfer tool. The length, + attributes, and in some cases contents of the received file may not match those of the original file. -A, --affinity n/n,m - Set the CPU affinity, if possible (Linux, FreeBSD, and Windows - only). On both the client and server you can set the local - affinity by using the n form of this argument (where n is a CPU - number). In addition, on the client side you can override the - server's affinity for just that one test, using the n,m form of - argument. Note that when using this feature, a process will - only be bound to a single CPU (as opposed to a set containing + Set the CPU affinity, if possible (Linux, FreeBSD, and Windows + only). On both the client and server you can set the local + affinity by using the n form of this argument (where n is a CPU + number). In addition, on the client side you can override the + server's affinity for just that one test, using the n,m form of + argument. Note that when using this feature, a process will + only be bound to a single CPU (as opposed to a set containing potentialy multiple CPUs). -B, --bind host - bind to the specific interface associated with address host. If - the host has multiple interfaces, it will use the first inter- - face by default. + bind to the specific interface associated with address host. + --bind-dev dev.ft R bind to the specified network interface. + This option uses SO_BINDTODEVICE, and may require root permis- + sions. (Available on Linux and possibly other systems.) -V, --verbose give more detailed output @@ -173,8 +178,21 @@ the executable. force flushing output at every interval. Used to avoid buffer- ing when sending output to pipe. + --timestamps[=format] + prepend a timestamp at the start of each output line. By + default, timestamps have the format emitted by ctime(1). + Optionally, = followed by a format specification can be passed + to customize the timestamps, see strftime(3). If this optional + format is given, the = must immediately follow the --timestamps + option with no whitespace intervening. + + --rcv-timeout # + 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). + -d, --debug - emit debugging output. Primarily (perhaps exclusively) of use + emit debugging output. Primarily (perhaps exclusively) of use to developers. -v, --version @@ -191,27 +209,33 @@ the executable. -D, --daemon run the server in background as a daemon - -I, --pidfile file - write a file with the process ID, most useful when running as a - daemon. - -1, --one-off handle one client connection, then exit. + --server-bitrate-limit n[KMGT] + set a limit on the server side, which will cause a test to abort + if the client specifies a test of more than n bits per second, + or if the average data sent or received by the client (including + all data streams) is greater than n bits per second. The + default limit is zero, which implies no limit. The interval + over which to average the data rate is 5 seconds by default, but + can be specified by adding a '/' and a number to the bitrate + specifier. + --rsa-private-key-path file - path to the RSA private key (not password-protected) used to - decrypt authentication credentials from the client (if built + path to the RSA private key (not password-protected) used to + decrypt authentication credentials from the client (if built with OpenSSL support). --authorized-users-path file - path to the configuration file containing authorized users cre- - dentials to run iperf tests (if built with OpenSSL support). - The file is a comma separated list of usernames and password - hashes; more information on the structure of the file can be + path to the configuration file containing authorized users cre- + dentials to run iperf tests (if built with OpenSSL support). + 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 EXAMPLES section. - - --time-skew-threshold seconds - time skew threshold (in seconds) between the server and client + + --time-skew-thresholdsecond seconds + time skew threshold (in seconds) between the server and client during the authentication process. CLIENT SPECIFIC OPTIONS @@ -232,7 +256,7 @@ the executable. viding a shorter value may speed up detection of a down iperf3 server. - -b, --bitrate n[KM] + -b, --bitrate n[KMGT] set target bitrate to n bits/sec (default 1 Mbit/sec for UDP, unlimited for TCP/SCTP). If there are multiple streams (-P flag), the throughput limit is applied separately to each @@ -246,7 +270,7 @@ the executable. the --fq-rate flag. This option replaces the --bandwidth flag, which is now deprecated but (at least for now) still accepted. - --pacing-timer n[KMG] + --pacing-timer n[KMGT] set pacing timer interval in microseconds (default 1000 microseconds, or 1 ms). This controls iperf3's internal pacing timer for the -b/--bitrate option. The timer fires at the @@ -255,7 +279,7 @@ the executable. potentially at the cost of performance due to more frequent timer processing. - --fq-rate n[KM] + --fq-rate n[KMGT] Set a rate to be used with fair-queueing based socket-level pac- ing, in bits per second. This pacing (if specified) will be in addition to any pacing due to iperf3's internal throughput pac- @@ -271,13 +295,13 @@ the executable. -t, --time n time in seconds to transmit for (default 10 secs) - -n, --bytes n[KM] + -n, --bytes n[KMGT] number of bytes to transmit (instead of -t) - -k, --blockcount n[KM] + -k, --blockcount n[KMGT] number of blocks (packets) to transmit (instead of -t or -n) - -l, --length n[KM] + -l, --length n[KMGT] length of buffer to read or write. For TCP tests, the default value is 128KB. In the case of UDP, iperf3 tries to dynamically determine a reasonable sending size based on the path MTU; if @@ -296,12 +320,13 @@ the executable. -R, --reverse reverse the direction of a test, so that the server sends data to the client - - --bidir - bidirectional mode, server and client send and receive data. - -w, --window n[KM] - window size / socket buffer size (this gets sent to the server + --bidir + test in both directions (normal and reverse), with both the + client and server sending and receiving data simultaneously + + -w, --window n[KMGT] + window size / socket buffer size (this gets sent to the server and used on that side too) -M, --set-mss n @@ -321,32 +346,32 @@ the executable. can be used, i.e. 52, 064 and 0x34 all specify the same value. --dscp dscp - set the IP DSCP bits. Both numeric and symbolic values are - accepted. Numeric values can be specified in decimal, octal and + set the IP DSCP bits. Both numeric and symbolic values are + accepted. Numeric values can be specified in decimal, octal and hex (see --tos above). -L, --flowlabel n set the IPv6 flow label (currently only supported on Linux) -X, --xbind name - Bind SCTP associations to a specific subset of links using - sctp_bindx(3). The --B flag will be ignored if this flag is + Bind SCTP associations to a specific subset of links using + sctp_bindx(3). The --B flag will be ignored if this flag is specified. Normally SCTP will include the protocol addresses of - all active links on the local host when setting up an associa- - tion. Specifying at least one --X name will disable this behav- - iour. This flag must be specified for each link to be included - in the association, and is supported for both iperf servers and + all active links on the local host when setting up an associa- + tion. Specifying at least one --X name will disable this behav- + iour. This flag must be specified for each link to be included + in the association, and is supported for both iperf servers and clients (the latter are supported by passing the first --X argu- - ment to bind(2)). Hostnames are accepted as arguments and are - resolved using getaddrinfo(3). If the --4 or --6 flags are - specified, names which do not resolve to addresses within the + ment to bind(2)). Hostnames are accepted as arguments and are + resolved using getaddrinfo(3). If the --4 or --6 flags are + specified, names which do not resolve to addresses within the specified protocol family will be ignored. --nstreams n Set number of SCTP streams. -Z, --zerocopy - Use a "zero copy" method of sending data, such as sendfile(2), + Use a "zero copy" method of sending data, such as sendfile(2), instead of the usual write(2). -O, --omit n @@ -357,50 +382,64 @@ the executable. Prefix every output line with this string. --extra-data str - Specify an extra data string field to be included in JSON out- + Specify an extra data string field to be included in JSON out- put. -C, --congestion algo - Set the congestion control algorithm (Linux and FreeBSD only). - An older --linux-congestion synonym for this flag is accepted + Set the congestion control algorithm (Linux and FreeBSD only). + An older --linux-congestion synonym for this flag is accepted but is deprecated. --get-server-output Get the output from the server. The output format is determined by the server (in particular, if the server was invoked with the - --json flag, the output will be in JSON format, otherwise it - will be in human-readable format). If the client is run with - --json, the server output is included in a JSON object; other- - wise it is appended at the bottom of the human-readable output. + --json flag, the output will be in JSON format, otherwise it + will be in human-readable format). If the client is run with + --json, the server output is included in a JSON object; other- + wise it is appended at the bottom of the human-readable output. + + --udp-counters-64bit + Use 64-bit counters in UDP test packets. The use of this option + can help prevent counter overflows during long or high-bitrate + UDP tests. Both client and server need to be running at least + version 3.1 for this option to work. It may become the default + behavior at some point in the future. --repeating-payload - Use repeating pattern in payload, instead of random bytes. The - same payload is used in iperf2 (ASCII '0..9' repeating). It - might help to test and reveal problems in networking gear with - hardware compression (including some WiFi access points), where - iperf2 and iperf3 perform differently, just based on payload + Use repeating pattern in payload, instead of random bytes. The + same payload is used in iperf2 (ASCII '0..9' repeating). It + might help to test and reveal problems in networking gear with + hardware compression (including some WiFi access points), where + iperf2 and iperf3 perform differently, just based on payload entropy. + --dont-fragment + Set the IPv4 Don't Fragment (DF) bit on outgoing packets. Only + applicable to tests doing UDP over IPv4. + --username username username to use for authentication to the iperf server (if built with OpenSSL support). The password will be prompted for inter- - actively when the test is run. Note, the password to use can - also be specified via the IPERF3_PASSWORD environment variable. - If this variable is present, the password prompt will be + actively when the test is run. Note, 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. - + --rsa-public-key-path file - path to the RSA public key used to encrypt authentication cre- + path to the RSA public key used to encrypt authentication cre- dentials (if built with OpenSSL support) EXAMPLES Authentication - RSA Keypair - 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. An example of a set of UNIX/Linux commands to - generate correct keypair follows: + 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 addi- + tionally 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 key- + pair follows: > openssl genrsa -des3 -out private.pem 2048 > openssl rsa -in private.pem -outform PEM -pubout -out public.pem @@ -441,7 +480,8 @@ the executable. - ESnet June 2018 IPERF3(1) + ESnet February 2021 + IPERF3(1) The iperf3 manual page will typically be installed in manual section 1.