--- embedaddon/iperf/docs/invoking.rst 2021/03/17 00:36:45 1.1.1.2 +++ embedaddon/iperf/docs/invoking.rst 2023/09/27 11:14:54 1.1.1.3 @@ -4,7 +4,7 @@ Invoking iperf3 iperf3 includes a manual page listing all of the command-line options. The manual page is the most up-to-date reference to the various flags and parameters. -For sample command line usage, see: +For sample command line usage, see: https://fasterdata.es.net/performance-testing/network-troubleshooting-tools/iperf/ @@ -115,7 +115,7 @@ the executable. Either the client or the server can produce its output in a JSON struc- ture, useful for integration with other programs, by passing it the -J - flag. Because the contents of the JSON structure are only competely + flag. Because the contents of the JSON structure are only completely known after the test has finished, no JSON output will be emitted until the end of the test. @@ -136,30 +136,40 @@ 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 - potentialy multiple CPUs). + 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 + potentially multiple CPUs). - -B, --bind host + -B, --bind host[%dev] bind to the specific interface associated with address host. If - the host has multiple interfaces, it will use the first inter- - face by default. + an optional interface is specified, it is treated as a shortcut + for --bind-dev dev. Note that a percent sign and interface + device name are required for IPv6 link-local address literals. + --bind-dev dev + bind to the specified network interface. This option uses + SO_BINDTODEVICE, and may require root permissions. (Available + on Linux and possibly other systems.) + -V, --verbose give more detailed output @@ -173,8 +183,30 @@ 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). + + --snd-timeout # + set timeout for unacknowledged TCP data (on both test and con- + trol 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 sys- + tem settings. This functionality depends on the TCP_USER_TIME- + OUT socket option, and will not work on systems that do not sup- + port it. + -d, --debug - emit debugging output. Primarily (perhaps exclusively) of use + emit debugging output. Primarily (perhaps exclusively) of use to developers. -v, --version @@ -191,30 +223,50 @@ 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. + handle one client connection, then exit. If an idle time is + set, the server will exit after that amount of time with no con- + nection. + --idle-timeout n + restart the server after n seconds in case it gets stuck. In + one-off mode, this is the number of seconds the server will wait + before exiting. + + --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-thresholdsecond seconds + time skew threshold (in seconds) between the server and client + during the authentication process. + CLIENT SPECIFIC OPTIONS - -c, --client host + -c, --client host[%dev] run in client mode, connecting to the specified server. 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 inter- + face is specified, it is treated as a shortcut for --bind-dev + dev. Note that a percent sign and interface device name are + required for IPv6 link-local address literals. --sctp use SCTP rather than TCP (FreeBSD and Linux) @@ -222,42 +274,42 @@ the executable. use UDP rather than TCP --connect-timeout n - set timeout for establishing the initial control connection to - the server, in milliseconds. The default behavior is the oper- - ating system's timeout for TCP connection establishment. Pro- - viding a shorter value may speed up detection of a down iperf3 + set timeout for establishing the initial control connection to + the server, in milliseconds. The default behavior is the oper- + ating system's timeout for TCP connection establishment. Pro- + viding a shorter value may speed up detection of a down iperf3 server. - -b, --bitrate n[KM] - 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 - stream. You can also add a '/' and a number to the bitrate + -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 + stream. You can also add a '/' and a number to the bitrate specifier. This is called "burst mode". It will send the given - number of packets without pausing, even if that temporarily - exceeds the specified throughput limit. Setting the target - bitrate to 0 will disable bitrate limits (particularly useful + number of packets without pausing, even if that temporarily + exceeds the specified throughput limit. Setting the target + bitrate to 0 will disable bitrate limits (particularly useful for UDP tests). This throughput limit is implemented internally - inside iperf3, and is available on all platforms. Compare with - the --fq-rate flag. This option replaces the --bandwidth flag, + inside iperf3, and is available on all platforms. Compare with + 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] - 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 - interval set by this parameter. Smaller values of the pacing - timer parameter smooth out the traffic emitted by iperf3, but - potentially at the cost of performance due to more frequent + --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 + interval set by this parameter. Smaller values of the pacing + timer parameter smooth out the traffic emitted by iperf3, but + 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- - ing (-b/--bitrate flag), and both can be specified for the same - test. Only available on platforms supporting the SO_MAX_PAC- - ING_RATE socket option (currently only Linux). The default is + ing, in bits per second. This pacing (if specified) will be in + addition to any pacing due to iperf3's internal throughput pac- + ing (-b/--bitrate flag), and both can be specified for the same + test. Only available on platforms supporting the SO_MAX_PAC- + ING_RATE socket option (currently only Linux). The default is no fair-queueing based pacing. --no-fq-socket-pacing @@ -267,38 +319,45 @@ 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] - length of buffer to read or write. For TCP tests, the default + -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 - that cannot be determined it uses 1460 bytes as a sending size. + determine a reasonable sending size based on the path MTU; if + that cannot be determined it uses 1460 bytes as a sending size. For SCTP tests, the default size is 64KB. --cport port - bind data streams to a specific client port (for TCP and UDP + bind data streams to a specific client port (for TCP and UDP only, default is to use an ephemeral port) -P, --parallel n - number of parallel client streams to run. Note that iperf3 is - single threaded, so if you are CPU bound, this will not yield + number of parallel client streams to run. Note that iperf3 is + single threaded, so if you are CPU bound, this will not yield higher throughput. -R, --reverse - reverse the direction of a test, so that the server sends data + 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. + test in both directions (normal and reverse), with both the + client and server sending and receiving data simultaneously - -w, --window n[KM] - window size / socket buffer size (this gets sent to the server - and used on that side too) + -w, --window n[KMGT] + 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)). -M, --set-mss n set TCP/SCTP maximum segment size (MTU - 40 bytes) @@ -319,84 +378,99 @@ the executable. --dscp dscp 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). + hex (see --tos above). To set both the DSCP bits and the ECN + bits, use --tos. -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 - Omit the first n seconds of the test, to skip past the TCP slow- - start period. + Perform pre-test for N seconds and omit the pre-test statistics, + to skip past the TCP slow-start period. -T, --title str 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 @@ -437,8 +511,8 @@ the executable. - ESnet June 2018 IPERF3(1) + ESnet September 2022 IPERF3(1) + The iperf3 manual page will typically be installed in manual section 1. -