Return to iperf3.1 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / iperf / src

Version 3.15

    1: .TH IPERF3 1 "September 2022" ESnet "User Manuals"
    2: .SH NAME
    3: iperf3 \- perform network throughput tests
    4: .SH SYNOPSIS
    5: .B iperf3 -s [
    6: .I options
    7: .B ]
    8: .br
    9: .B iperf3 -c
   10: .I server
   11: .B [
   12: .I options
   13: .B ]
   14: 
   15: .SH DESCRIPTION
   16: iperf3 is a tool for performing network throughput measurements.
   17: It can test TCP, UDP, or SCTP throughput.
   18: To perform an iperf3 test the user must establish both a server and a
   19: client.
   20: .PP
   21: The iperf3 executable contains both client and server functionality.
   22: An iperf3 server can be started using either of the -s or
   23: --server command-line parameters, for example:
   24: .IP
   25: \fCiperf3 -s\fR
   26: .IP
   27: \fCiperf3 --server \fR
   28: .PP
   29: Note that many iperf3 parameters have both short (-s) and long
   30: (--server) forms.
   31: In this section we will generally use the short form of command-line
   32: flags, unless only the long form of a flag is available.
   33: .PP
   34: By default, the iperf3 server listens on TCP port 5201 for connections
   35: from an iperf3 client.
   36: A custom port can be specified by using the -p flag, for
   37: example:
   38: .IP
   39: \fCiperf3 -s -p 5002\fR
   40: .PP
   41: After the server is started, it will listen for connections from
   42: iperf3 clients (in other words, the iperf3 program run in client
   43: mode).
   44: The client mode can be started using the -c command-line option,
   45: which also requires a host to which iperf3 should connect.
   46: The host can by specified by hostname, IPv4 literal, or IPv6 literal:
   47: .IP
   48: \fCiperf3 -c iperf3.example.com\fR
   49: .IP
   50: \fCiperf3 -c 192.0.2.1\fR
   51: .IP
   52: \fCiperf3 -c 2001:db8::1\fR
   53: .PP
   54: If the iperf3 server is running on a non-default TCP port, that port
   55: number needs to be specified on the client as well:
   56: .IP
   57: \fCiperf3 -c iperf3.example.com -p 5002\fR
   58: .PP
   59: The initial TCP connection is used to exchange test parameters,
   60: control the start and end of the test, and to exchange test results.
   61: This is sometimes referred to as the "control connection".
   62: The actual test data is sent over a separate TCP connection, as a
   63: separate flow of UDP packets, or as an independent SCTP connection,
   64: depending on what protocol was specified by the client.
   65: .PP
   66: Normally, the test data is sent from the client to the server, and
   67: measures the upload speed of the client.
   68: Measuring the download speed from the server can be done by specifying
   69: the -R flag on the client.
   70: This causes data to be sent from the server to the client.
   71: .IP
   72: \fCiperf3 -c iperf3.example.com -p 5202 -R
   73: .PP
   74: Results are displayed on both the client and server.
   75: There will be at least one line of output per measurement interval (by
   76: default a measurement interval lasts for one second, but this can be
   77: changed by the -i option).
   78: Each line of output includes (at least) the time since the start of
   79: the test, amount of data transferred during the interval, and the
   80: average bitrate over that interval.
   81: Note that the values for each measurement interval are taken from the
   82: point of view of the endpoint process emitting that output (in other
   83: words, the output on the client shows the measurement interval data for
   84: the client.
   85: .PP
   86: At the end of the test is a set of statistics that shows (at
   87: least as much as possible) a summary of the test as seen by both the
   88: sender and the receiver, with lines tagged accordingly.
   89: Recall that by default the client is the sender and the server is the
   90: receiver, although as indicated above, use of the \fC-R\fR flag will
   91: reverse these roles.
   92: .PP
   93: The client can be made to retrieve the server-side output for a given
   94: test by specifying the --get-server-output flag.
   95: .PP
   96: Either the client or the server can produce its output in a JSON
   97: structure, useful for integration with other programs, by passing it
   98: the -J flag.
   99: Because the contents of the JSON structure are only completely known
  100: after the test has finished, no JSON output will be emitted until the
  101: end of the test.
  102: .PP
  103: iperf3 has a (overly) large set of command-line options that can be
  104: used to set the parameters of a test.
  105: They are given in the "GENERAL OPTIONS" section of the manual page
  106: below, as well as summarized in iperf3's help output, which can be
  107: viewed by running iperf3 with the -h flag.
  108: .SH "GENERAL OPTIONS"
  109: .TP
  110: .BR -p ", " --port " \fIn\fR"
  111: set server port to listen on/connect to to \fIn\fR (default 5201)
  112: .TP
  113: .BR -f ", " --format " "
  114: [kmgtKMGT]   format to report: Kbits/Mbits/Gbits/Tbits
  115: .TP
  116: .BR -i ", " --interval " \fIn\fR"
  117: pause \fIn\fR seconds between periodic throughput reports;
  118: default is 1, use 0 to disable
  119: .TP
  120: .BR -I ", " --pidfile " \fIfile\fR"
  121: write a file with the process ID, most useful when running as a daemon.
  122: .TP
  123: .BR -F ", " --file " \fIname\fR"
  124: Use a file as the source (on the sender) or sink (on the receiver) of
  125: data, rather than just generating random data or throwing it away.
  126: This feature is used for finding whether or not the storage subsystem
  127: is the bottleneck for file transfers.
  128: It does not turn iperf3 into a file transfer tool.
  129: The length, attributes, and in some cases contents of the received
  130: file may not match those of the original file.
  131: .TP
  132: .BR -A ", " --affinity " \fIn/n,m\fR"
  133: Set the CPU affinity, if possible (Linux, FreeBSD, and Windows only).
  134: On both the client and server you can set the local affinity by using
  135: the \fIn\fR form of this argument (where \fIn\fR is a CPU number).
  136: In addition, on the client side you can override the server's
  137: affinity for just that one test, using the \fIn,m\fR form of
  138: argument.
  139: Note that when using this feature, a process will only be bound
  140: to a single CPU (as opposed to a set containing potentially multiple
  141: CPUs).
  142: .TP
  143: .BR -B ", " --bind " \fIhost\fR[\fB%\fIdev\fR]"
  144: bind to the specific interface associated with address \fIhost\fR.
  145: If an optional interface is specified, it is treated as a shortcut
  146: for \fB--bind-dev \fIdev\fR.
  147: Note that a percent sign and interface device name are required for IPv6 link-local address literals.
  148: .TP
  149: .BR --bind-dev " \fIdev\fR"
  150: bind to the specified network interface.
  151: This option uses SO_BINDTODEVICE, and may require root permissions.
  152: (Available on Linux and possibly other systems.)
  153: .TP
  154: .BR -V ", " --verbose " "
  155: give more detailed output
  156: .TP
  157: .BR -J ", " --json " "
  158: output in JSON format
  159: .TP
  160: .BR --logfile " \fIfile\fR"
  161: send output to a log file.
  162: .TP
  163: .BR --forceflush " "
  164: force flushing output at every interval.
  165: Used to avoid buffering when sending output to pipe.
  166: .TP
  167: .BR --timestamps "[\fB=\fIformat\fR]"
  168: prepend a timestamp at the start of each output line.
  169: By default, timestamps have the format emitted by
  170: .BR ctime ( 1 ).
  171: Optionally, \fC=\fR followed by
  172: a format specification can be passed to customize the
  173: timestamps, see
  174: .BR strftime ( 3 ).
  175: If this optional format is given, the \fC=\fR must immediately
  176: follow the \fB--timestamps\fR option with no whitespace intervening.
  177: .TP
  178: .BR --rcv-timeout " \fI#\fR"
  179: set idle timeout for receiving data during active tests. The receiver
  180: will halt a test if no data is received from the sender for this
  181: number of ms (default to 12000 ms, or 2 minutes).
  182: .TP
  183: .BR --snd-timeout " \fI#\fR"
  184: set timeout for unacknowledged TCP data (on both test and control
  185: connections) This option can be used to force a faster test timeout
  186: in case of a network partition during a test. The required
  187: parameter is specified in ms, and defaults to the system settings.
  188: This functionality depends on the TCP_USER_TIMEOUT socket option, and
  189: will not work on systems that do not support it.
  190: .TP
  191: .BR -d ", " --debug " "
  192: emit debugging output.
  193: Primarily (perhaps exclusively) of use to developers.
  194: .TP
  195: .BR -v ", " --version " "
  196: show version information and quit
  197: .TP
  198: .BR -h ", " --help " "
  199: show a help synopsis
  200: 
  201: .SH "SERVER SPECIFIC OPTIONS"
  202: .TP
  203: .BR -s ", " --server " "
  204: run in server mode
  205: .TP
  206: .BR -D ", " --daemon " "
  207: run the server in background as a daemon
  208: .TP
  209: .BR -1 ", " --one-off
  210: handle one client connection, then exit.  If an idle time is set, the
  211: server will exit after that amount of time with no connection.
  212: .TP
  213: .BR --idle-timeout " \fIn\fR"
  214: restart the server after \fIn\fR seconds in case it gets stuck.  In
  215: one-off mode, this is the number of seconds the server will wait
  216: before exiting.
  217: .TP
  218: .BR --server-bitrate-limit " \fIn\fR[KMGT]"
  219: set a limit on the server side, which will cause a test to abort if
  220: the client specifies a test of more than \fIn\fR bits per second, or
  221: if the average data sent or received by the client (including all data
  222: streams) is greater than \fIn\fR bits per second.  The default limit
  223: is zero, which implies no limit.  The interval over which to average
  224: the data rate is 5 seconds by default, but can be specified by adding
  225: a '/' and a number to the bitrate specifier.
  226: .TP
  227: .BR --rsa-private-key-path " \fIfile\fR"
  228: path to the RSA private key (not password-protected) used to decrypt
  229: authentication credentials from the client (if built with OpenSSL
  230: support).
  231: .TP
  232: .BR --authorized-users-path " \fIfile\fR"
  233: path to the configuration file containing authorized users credentials to run
  234: iperf tests (if built with OpenSSL support).
  235: The file is a comma separated list of usernames and password hashes;
  236: more information on the structure of the file can be found in the
  237: EXAMPLES section.
  238: .TP
  239: .BR --time-skew-threshold second " \fIseconds\fR"
  240: time skew threshold (in seconds) between the server and client
  241: during the authentication process.
  242: .SH "CLIENT SPECIFIC OPTIONS"
  243: .TP
  244: .BR -c ", " --client " \fIhost\fR[\fB%\fIdev\fR]"
  245: run in client mode, connecting to the specified server.
  246: By default, a test consists of sending data from the client to the
  247: server, unless the \-R flag is specified.
  248: If an optional interface is specified, it is treated as a shortcut
  249: for \fB--bind-dev \fIdev\fR.
  250: Note that a percent sign and interface device name are required for IPv6 link-local address literals.
  251: .TP
  252: .BR --sctp
  253: use SCTP rather than TCP (FreeBSD and Linux)
  254: .TP
  255: .BR -u ", " --udp
  256: use UDP rather than TCP
  257: .TP
  258: .BR --connect-timeout " \fIn\fR"
  259: set timeout for establishing the initial control connection to the
  260: server, in milliseconds.
  261: The default behavior is the operating system's timeout for TCP
  262: connection establishment.
  263: Providing a shorter value may speed up detection of a down iperf3
  264: server.
  265: .TP
  266: .BR -b ", " --bitrate " \fIn\fR[KMGT]"
  267: set target bitrate to \fIn\fR bits/sec (default 1 Mbit/sec for UDP,
  268: unlimited for TCP/SCTP).
  269: If there are multiple streams (\-P flag), the throughput limit is applied
  270: separately to each stream.
  271: You can also add a '/' and a number to the bitrate specifier.
  272: This is called "burst mode".
  273: It will send the given number of packets without pausing, even if that
  274: temporarily exceeds the specified throughput limit.
  275: Setting the target bitrate to 0 will disable bitrate limits
  276: (particularly useful for UDP tests).
  277: This throughput limit is implemented internally inside iperf3, and is
  278: available on all platforms.
  279: Compare with the \--fq-rate flag.
  280: This option replaces the \--bandwidth flag, which is now deprecated
  281: but (at least for now) still accepted.
  282: .TP
  283: .BR --pacing-timer " \fIn\fR[KMGT]"
  284: set pacing timer interval in microseconds (default 1000 microseconds,
  285: or 1 ms).
  286: This controls iperf3's internal pacing timer for the \-b/\--bitrate
  287: option.
  288: The timer fires at the interval set by this parameter.
  289: Smaller values of the pacing timer parameter smooth out the traffic
  290: emitted by iperf3, but potentially at the cost of performance due to
  291: more frequent timer processing.
  292: .TP
  293: .BR --fq-rate " \fIn\fR[KMGT]"
  294: Set a rate to be used with fair-queueing based socket-level pacing,
  295: in bits per second.
  296: This pacing (if specified) will be in addition to any pacing due to
  297: iperf3's internal throughput pacing (\-b/\--bitrate flag), and both can be
  298: specified for the same test.
  299: Only available on platforms supporting the
  300: \fCSO_MAX_PACING_RATE\fR socket option (currently only Linux).
  301: The default is no fair-queueing based pacing.
  302: .TP
  303: .BR --no-fq-socket-pacing
  304: This option is deprecated and will be removed.
  305: It is equivalent to specifying --fq-rate=0.
  306: .TP
  307: .BR -t ", " --time " \fIn\fR"
  308: time in seconds to transmit for (default 10 secs)
  309: .TP
  310: .BR -n ", " --bytes " \fIn\fR[KMGT]"
  311: number of bytes to transmit (instead of \-t)
  312: .TP
  313: .BR -k ", " --blockcount " \fIn\fR[KMGT]"
  314: number of blocks (packets) to transmit (instead of \-t or \-n)
  315: .TP
  316: .BR -l ", " --length " \fIn\fR[KMGT]"
  317: length of buffer to read or write.  For TCP tests, the default value
  318: is 128KB.
  319: In the case of UDP, iperf3 tries to dynamically determine a reasonable
  320: sending size based on the path MTU; if that cannot be determined it
  321: uses 1460 bytes as a sending size.
  322: For SCTP tests, the default size is 64KB.
  323: .TP
  324: .BR --cport " \fIport\fR"
  325: bind data streams to a specific client port (for TCP and UDP only,
  326: default is to use an ephemeral port)
  327: .TP
  328: .BR -P ", " --parallel " \fIn\fR"
  329: 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.
  330: .TP
  331: .BR -R ", " --reverse
  332: reverse the direction of a test, so that the server sends data to the
  333: client
  334: .TP
  335: .BR --bidir
  336: test in both directions (normal and reverse), with both the client and
  337: server sending and receiving data simultaneously
  338: .TP
  339: .BR -w ", " --window " \fIn\fR[KMGT]"
  340: set socket buffer size / window size.
  341: This value gets sent to the server and used on that side too; on both
  342: sides this option sets both the sending and receiving socket buffer sizes.
  343: This option can be used to set (indirectly) the maximum TCP window size.
  344: Note that on Linux systems, the effective maximum window size is approximately
  345: double what is specified by this option (this behavior is not a bug in iperf3
  346: but a "feature" of the Linux kernel, as documented by tcp(7) and socket(7)).
  347: .TP
  348: .BR -M ", " --set-mss " \fIn\fR"
  349: set TCP/SCTP maximum segment size (MTU - 40 bytes)
  350: .TP
  351: .BR -N ", " --no-delay " "
  352: set TCP/SCTP no delay, disabling Nagle's Algorithm
  353: .TP
  354: .BR -4 ", " --version4 " "
  355: only use IPv4
  356: .TP
  357: .BR -6 ", " --version6 " "
  358: only use IPv6
  359: .TP
  360: .BR -S ", " --tos " \fIn\fR"
  361: set the IP type of service. The usual prefixes for octal and hex can be used,
  362: i.e. 52, 064 and 0x34 all specify the same value.
  363: .TP
  364: .BR "--dscp " \fIdscp\fR
  365: set the IP DSCP bits.  Both numeric and symbolic values are accepted. Numeric
  366: values can be specified in decimal, octal and hex (see --tos above).
  367: .TP
  368: .BR -L ", " --flowlabel " \fIn\fR"
  369: set the IPv6 flow label (currently only supported on Linux)
  370: .TP
  371: .BR -X ", " --xbind " \fIname\fR"
  372: Bind SCTP associations to a specific subset of links using sctp_bindx(3).
  373: The \fB--B\fR flag will be ignored if this flag is specified.
  374: Normally SCTP will include the protocol addresses of all active links
  375: on the local host when setting up an association. Specifying at least
  376: one \fB--X\fR name will disable this behaviour.
  377: This flag must be specified for each link to be included in the
  378: association, and is supported for both iperf servers and clients
  379: (the latter are supported by passing the first \fB--X\fR argument to bind(2)).
  380: Hostnames are accepted as arguments and are resolved using
  381: getaddrinfo(3).
  382: If the \fB--4\fR or \fB--6\fR flags are specified, names
  383: which do not resolve to addresses within the
  384: specified protocol family will be ignored.
  385: .TP
  386: .BR --nstreams " \fIn\fR"
  387: Set number of SCTP streams.
  388: .TP
  389: .BR -Z ", " --zerocopy " "
  390: Use a "zero copy" method of sending data, such as sendfile(2),
  391: instead of the usual write(2).
  392: .TP
  393: .BR -O ", " --omit " \fIn\fR"
  394: Perform pre-test for N seconds and omit the pre-test statistics, to skip past the TCP slow-start
  395: period.
  396: .TP
  397: .BR -T ", " --title " \fIstr\fR"
  398: Prefix every output line with this string.
  399: .TP
  400: .BR --extra-data " \fIstr\fR"
  401: Specify an extra data string field to be included in JSON output.
  402: .TP
  403: .BR -C ", " --congestion " \fIalgo\fR"
  404: Set the congestion control algorithm (Linux and FreeBSD only).  An
  405: older
  406: .B --linux-congestion
  407: synonym for this flag is accepted but is deprecated.
  408: .TP
  409: .BR "--get-server-output"
  410: Get the output from the server.
  411: The output format is determined by the server (in particular, if the
  412: server was invoked with the \fB--json\fR flag, the output will be in
  413: JSON format, otherwise it will be in human-readable format).
  414: If the client is run with \fB--json\fR, the server output is included
  415: in a JSON object; otherwise it is appended at the bottom of the
  416: human-readable output.
  417: .TP
  418: .BR --udp-counters-64bit
  419: Use 64-bit counters in UDP test packets.
  420: The use of this option can help prevent counter overflows during long
  421: or high-bitrate UDP tests.  Both client and server need to be running
  422: at least version 3.1 for this option to work.  It may become the
  423: default behavior at some point in the future.
  424: .TP
  425: .BR --repeating-payload
  426: Use repeating pattern in payload, instead of random bytes.
  427: The same payload is used in iperf2 (ASCII '0..9' repeating).
  428: It might help to test and reveal problems in networking gear with hardware
  429: compression (including some WiFi access points), where iperf2 and iperf3
  430: perform differently, just based on payload entropy.
  431: .TP
  432: .BR --dont-fragment
  433: Set the IPv4 Don't Fragment (DF) bit on outgoing packets.
  434: Only applicable to tests doing UDP over IPv4.
  435: .TP
  436: .BR --username " \fIusername\fR"
  437: username to use for authentication to the iperf server (if built with
  438: OpenSSL support).
  439: The password will be prompted for interactively when the test is run.  Note,
  440: the password to use can also be specified via the IPERF3_PASSWORD environment
  441: variable. If this variable is present, the password prompt will be skipped.
  442: .TP
  443: .BR --rsa-public-key-path " \fIfile\fR"
  444: path to the RSA public key used to encrypt authentication credentials
  445: (if built with OpenSSL support)
  446: 
  447: .SH EXAMPLES
  448: .SS "Authentication - RSA Keypair"
  449: The authentication feature of iperf3 requires an RSA public keypair.
  450: The public key is used to encrypt the authentication token containing the
  451: user credentials, while the private key is used to decrypt the authentication token.
  452: The private key must be in PEM format and additionally must not have a
  453: password set.
  454: The public key must be in PEM format and use SubjectPrefixKeyInfo encoding.
  455: An example of a set of UNIX/Linux commands using OpenSSL
  456: to generate a correctly-formed keypair follows:
  457: .sp 1
  458: .in +.5i
  459: > openssl genrsa -des3 -out private.pem 2048
  460: .sp 0
  461: > openssl rsa -in private.pem -outform PEM -pubout -out public.pem
  462: .sp 0
  463: > openssl rsa -in private.pem -out private_not_protected.pem -outform PEM
  464: .in -.5i
  465: .sp 1
  466: After these commands, the public key will be contained in the file
  467: public.pem and the private key will be contained in the file
  468: private_not_protected.pem.
  469: .SS "Authentication - Authorized users configuration file"
  470: A simple plaintext file must be provided to the iperf3 server in order to specify
  471: the authorized user credentials.
  472: The file is a simple list of comma-separated pairs of a username and a
  473: corresponding password hash.
  474: The password hash is a SHA256 hash of the string "{$user}$password".
  475: The file can also contain commented lines (starting with the \fC#\fR
  476: character).
  477: An example of commands to generate the password hash on a UNIX/Linux system
  478: is given below:
  479: .sp 1
  480: .in +.5i
  481: > S_USER=mario S_PASSWD=rossi
  482: .sp 0
  483: > echo -n "{$S_USER}$S_PASSWD" | sha256sum | awk '{ print $1 }'
  484: .in -.5i
  485: .sp 1
  486: An example of a password file (with an entry corresponding to the
  487: above username and password) is given below:
  488: .sp 0
  489: .in +.5i
  490: > cat credentials.csv
  491: .sp 0
  492: # file format: username,sha256
  493: .sp 0
  494: mario,bf7a49a846d44b454a5d11e7acfaf13d138bbe0b7483aa3e050879700572709b
  495: .in -.5i
  496: .sp 1
  497: 
  498: .SH AUTHORS
  499: A list of the contributors to iperf3 can be found within the
  500: documentation located at
  501: \fChttps://software.es.net/iperf/dev.html#authors\fR.
  502: 
  503: .SH "SEE ALSO"
  504: libiperf(3),
  505: https://software.es.net/iperf