--- embedaddon/iperf/docs/invoking.rst 2016/10/18 13:28:18 1.1.1.1 +++ embedaddon/iperf/docs/invoking.rst 2021/03/17 00:36:45 1.1.1.2 @@ -6,7 +6,7 @@ The manual page is the most up-to-date reference to th For sample command line usage, see: -http://fasterdata.es.net/performance-testing/network-troubleshooting-tools/iperf-and-iperf3/ +https://fasterdata.es.net/performance-testing/network-troubleshooting-tools/iperf/ Using the default options, iperf3 is meant to show typical well designed application performance. "Typical well designed application" @@ -20,179 +20,424 @@ iperf3 Manual Page ------------------ This section contains a plaintext rendering of the iperf3 manual page. -It is presented here only for convenience; the authoritative iperf3 +It is presented here only for convenience; the text here might not +correspond to the current version of iperf3. The authoritative iperf3 manual page is included in the source tree and installed along with the executable. :: - IPERF(1) User Manuals IPERF(1) - - - + IPERF3(1) User Manuals IPERF3(1) + + + NAME - iperf3 − perform network throughput tests - + iperf3 - perform network throughput tests + SYNOPSIS - iperf3 ‐s [ options ] - iperf3 ‐c server [ options ] - - + iperf3 -s [ options ] + iperf3 -c server [ options ] + + DESCRIPTION - iperf3 is a tool for performing network throughput measurements. It - can test either TCP or UDP throughput. To perform an iperf3 test the - user must establish both a server and a client. - - + 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 com- + mand-line parameters, for example: + + iperf3 -s + + iperf3 --server + + 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 avail- + able. + + 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: + + iperf3 -s -p 5002 + + 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 speci- + fied by hostname, IPv4 literal, or IPv6 literal: + + iperf3 -c iperf3.example.com + + iperf3 -c 192.0.2.1 + + iperf3 -c 2001:db8::1 + + If the iperf3 server is running on a non-default TCP port, that port + number needs to be specified on the client as well: + + iperf3 -c iperf3.example.com -p 5002 + + 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 proto- + col was specified by the client. + + Normally, the test data is sent from the client to the server, and mea- + sures 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. + + iperf3 -c iperf3.example.com -p 5202 -R + + Results are displayed on both the client and server. There will be at + least one line of output per measurement interval (by default a mea- + surement 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 struc- + ture, useful for integration with other programs, by passing it the -J + flag. Because 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. + + 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. + GENERAL OPTIONS - ‐p, ‐‐port n - set server port to listen on/connect to to n (default 5201) - - ‐f, ‐‐format - [kmKM] format to report: Kbits, Mbits, KBytes, MBytes - - ‐i, ‐‐interval n - pause n seconds between periodic bandwidth reports; default is - 1, use 0 to disable - - ‐F, ‐‐file name - client‐side: read from the file and write to the network, - instead of using random data; server‐side: read from the network - and write to the file, instead of throwing the data away - - ‐A, ‐‐affinity n/n,m - Set the CPU affinity, if possible (Linux and FreeBSD 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 mul‐ - tiple CPUs). - - ‐B, ‐‐bind host - bind to a specific interface - - ‐V, ‐‐verbose - give more detailed output - - ‐J, ‐‐json - output in JSON format - - ‐‐logfile file - send output to a log file. - - ‐d, ‐‐debug - emit debugging output. Primarily (perhaps exclusively) of use - to developers. - - ‐v, ‐‐version - show version information and quit - - ‐h, ‐‐help - show a help synopsis - - + -p, --port n + set server port to listen on/connect to to n (default 5201) + + -f, --format + [kmgtKMGT] format to report: Kbits/Mbits/Gbits/Tbits + + -i, --interval n + pause n seconds between periodic throughput reports; default is + 1, use 0 to disable + + -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 + 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). + + -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. + + -V, --verbose + give more detailed output + + -J, --json + output in JSON format + + --logfile file + send output to a log file. + + --forceflush + force flushing output at every interval. Used to avoid buffer- + ing when sending output to pipe. + + -d, --debug + emit debugging output. Primarily (perhaps exclusively) of use + to developers. + + -v, --version + show version information and quit + + -h, --help + show a help synopsis + + SERVER SPECIFIC OPTIONS - ‐s, ‐‐server - run in server mode - - ‐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. - - + -s, --server + run in server mode + + -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. + + --rsa-private-key-path file + 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 + found in the EXAMPLES section. + CLIENT SPECIFIC OPTIONS - ‐c, ‐‐client host - run in client mode, connecting to the specified server + -c, --client host + 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. + + --sctp use SCTP rather than TCP (FreeBSD and Linux) + + -u, --udp + 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 + 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 + 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 + 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, + 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 + timer processing. + + --fq-rate n[KM] + 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 + no fair-queueing based pacing. + + --no-fq-socket-pacing + This option is deprecated and will be removed. It is equivalent + to specifying --fq-rate=0. + + -t, --time n + time in seconds to transmit for (default 10 secs) + + -n, --bytes n[KM] + number of bytes to transmit (instead of -t) + + -k, --blockcount n[KM] + 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 + 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. + For SCTP tests, the default size is 64KB. + + --cport port + 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 + higher throughput. + + -R, --reverse + reverse the direction of a test, so that the server sends data + to the client - ‐‐sctp use SCTP rather than TCP (FreeBSD and Linux) + --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 + and used on that side too) + + -M, --set-mss n + set TCP/SCTP maximum segment size (MTU - 40 bytes) + + -N, --no-delay + set TCP/SCTP no delay, disabling Nagle's Algorithm + + -4, --version4 + only use IPv4 + + -6, --version6 + only use IPv6 + + -S, --tos n + set the IP type of service. The usual prefixes for octal and hex + 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 + 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 + 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 + 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 + 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), + 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. + + -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- + put. + + -C, --congestion algo + 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. + + --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 + entropy. + + --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 + skipped. - ‐u, ‐‐udp - use UDP rather than TCP - - ‐b, ‐‐bandwidth n[KM] - set target bandwidth to n bits/sec (default 1 Mbit/sec for UDP, - unlimited for TCP). If there are multiple streams (‐P flag), - the bandwidth limit is applied separately to each stream. You - can also add a ’/’ and a number to the bandwidth specifier. - This is called "burst mode". It will send the given number of - packets without pausing, even if that temporarily exceeds the - specified bandwidth limit. - - ‐t, ‐‐time n - time in seconds to transmit for (default 10 secs) - - ‐n, ‐‐bytes n[KM] - number of bytes to transmit (instead of ‐t) - - ‐k, ‐‐blockcount n[KM] - number of blocks (packets) to transmit (instead of ‐t or ‐n) - - ‐l, ‐‐length n[KM] - length of buffer to read or write (default 128 KB for TCP, 8KB - for UDP) - - ‐P, ‐‐parallel n - number of parallel client streams to run - - ‐R, ‐‐reverse - run in reverse mode (server sends, client receives) - - ‐w, ‐‐window n[KM] - TCP window size / socket buffer size (this gets sent to the - server and used on that side too) - - ‐M, ‐‐set‐mss n - set TCP maximum segment size (MTU ‐ 40 bytes) - - ‐N, ‐‐no‐delay - set TCP no delay, disabling Nagle’s Algorithm - - ‐4, ‐‐version4 - only use IPv4 - - ‐6, ‐‐version6 - only use IPv6 - - ‐S, ‐‐tos n - set the IP ’type of service’ - - ‐L, ‐‐flowlabel n - set the IPv6 flow label (currently only supported on Linux) - - ‐Z, ‐‐zerocopy - 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. - - ‐T, ‐‐title str - Prefix every output line with this string. - - ‐C, ‐‐linux‐congestion algo - Set the congestion control algorithm (linux only). - - + --rsa-public-key-path file + 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: + + > 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 -out- + form PEM + + After these commands, the public key will be contained in the file pub- + lic.pem and the private key will be contained in the file pri- + vate_not_protected.pem. + + Authentication - Authorized users configuration file + 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}$pass- + word". 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 + + + AUTHORS - Iperf was originally written by Mark Gates and Alex Warshavsky. Man - page and maintence by Jon Dugan . Other con‐ - tributions from Ajay Tirumala, Jim Ferguson, Feng Qin, Kevin Gibbs, - John Estabrook , Andrew Gallatin , Stephen Hemminger - - + A list of the contributors to iperf3 can be found within the documenta- + tion located at https://software.es.net/iperf/dev.html#authors. + + SEE ALSO - libiperf(3), https://github.com/esnet/iperf - - - - ESnet February 2014 IPERF(1) + libiperf(3), https://software.es.net/iperf + + + + ESnet June 2018 IPERF3(1) The iperf3 manual page will typically be installed in manual section 1.