Return to iperf3.1 CVS log

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

iperf 3.3.9

    1: .TH IPERF3 1 "July 2020" 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 competely 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 -F ", " --file " \fIname\fR"
  121: Use a file as the source (on the sender) or sink (on the receiver) of
  122: data, rather than just generating random data or throwing it away.
  123: This feature is used for finding whether or not the storage subsystem
  124: is the bottleneck for file transfers.
  125: It does not turn iperf3 into a file transfer tool.
  126: The length, attributes, and in some cases contents of the received
  127: file may not match those of the original file.
  128: .TP
  129: .BR -A ", " --affinity " \fIn/n,m\fR"
  130: Set the CPU affinity, if possible (Linux, FreeBSD, and Windows only).
  131: On both the client and server you can set the local affinity by using
  132: the \fIn\fR form of this argument (where \fIn\fR is a CPU number).
  133: In addition, on the client side you can override the server's
  134: affinity for just that one test, using the \fIn,m\fR form of
  135: argument.
  136: Note that when using this feature, a process will only be bound
  137: to a single CPU (as opposed to a set containing potentialy multiple
  138: CPUs).
  139: .TP
  140: .BR -B ", " --bind " \fIhost\fR"
  141: bind to the specific interface associated with address \fIhost\fR.
  142: .TP
  143: .BR -V ", " --verbose " "
  144: give more detailed output 
  145: .TP
  146: .BR -J ", " --json " "
  147: output in JSON format
  148: .TP
  149: .BR --logfile " \fIfile\fR"
  150: send output to a log file.
  151: .TP
  152: .BR --forceflush " "
  153: force flushing output at every interval.
  154: Used to avoid buffering when sending output to pipe.
  155: .TP
  156: .BR --timestamps " [\fIformat\fR]"
  157: prepend a timestamp at the start of each output line.
  158: By default, timestamps have the format emitted by
  159: .BR ctime ( 1 ).
  160: Optionally, a format specification can be passed to customize the
  161: timestamps, see
  162: .BR strftime ( 3 ).
  163: .TP
  164: .BR -d ", " --debug " "
  165: emit debugging output.
  166: Primarily (perhaps exclusively) of use to developers.
  167: .TP
  168: .BR -v ", " --version " "
  169: show version information and quit
  170: .TP
  171: .BR -h ", " --help " "
  172: show a help synopsis
  173: 
  174: .SH "SERVER SPECIFIC OPTIONS"
  175: .TP
  176: .BR -s ", " --server " "
  177: run in server mode
  178: .TP
  179: .BR -D ", " --daemon " "
  180: run the server in background as a daemon
  181: .TP
  182: .BR -I ", " --pidfile " \fIfile\fR"
  183: write a file with the process ID, most useful when running as a daemon.
  184: .TP
  185: .BR -1 ", " --one-off
  186: handle one client connection, then exit.
  187: .TP
  188: .BR --server-bitrate-limit " \fIn\fR[KMGT]"
  189: set a limit on the server side, which will cause a test to abort if
  190: the client specifies a test of more than \fIn\fR bits per second, or
  191: if the average data sent or received by the client (including all data
  192: streams) is greater than \fIn\fR bits per second.  The default limit
  193: is zero, which implies no limit.  The interval over which to average
  194: the data rate is 5 seconds by default, but can be specified by adding
  195: a '/' and a number to the bitrate specifier.
  196: .TP
  197: .BR --rsa-private-key-path " \fIfile\fR"
  198: path to the RSA private key (not password-protected) used to decrypt 
  199: authentication credentials from the client (if built with OpenSSL
  200: support).
  201: .TP          
  202: .BR --authorized-users-path " \fIfile\fR"
  203: path to the configuration file containing authorized users credentials to run 
  204: iperf tests (if built with OpenSSL support).
  205: The file is a comma separated list of usernames and password hashes;
  206: more information on the structure of the file can be found in the
  207: EXAMPLES section.
  208: .SH "CLIENT SPECIFIC OPTIONS"
  209: .TP
  210: .BR -c ", " --client " \fIhost\fR"
  211: run in client mode, connecting to the specified server.
  212: By default, a test consists of sending data from the client to the
  213: server, unless the \-R flag is specified.
  214: .TP
  215: .BR --sctp
  216: use SCTP rather than TCP (FreeBSD and Linux)
  217: .TP
  218: .BR -u ", " --udp
  219: use UDP rather than TCP
  220: .TP
  221: .BR --connect-timeout " \fIn\fR"
  222: set timeout for establishing the initial control connection to the
  223: server, in milliseconds.
  224: The default behavior is the operating system's timeout for TCP
  225: connection establishment.
  226: Providing a shorter value may speed up detection of a down iperf3
  227: server.
  228: .TP
  229: .BR -b ", " --bitrate " \fIn\fR[KMGT]"
  230: set target bitrate to \fIn\fR bits/sec (default 1 Mbit/sec for UDP,
  231: unlimited for TCP/SCTP).
  232: If there are multiple streams (\-P flag), the throughput limit is applied
  233: separately to each stream.
  234: You can also add a '/' and a number to the bitrate specifier.
  235: This is called "burst mode".
  236: It will send the given number of packets without pausing, even if that
  237: temporarily exceeds the specified throughput limit.
  238: Setting the target bitrate to 0 will disable bitrate limits
  239: (particularly useful for UDP tests).
  240: This throughput limit is implemented internally inside iperf3, and is
  241: available on all platforms.
  242: Compare with the \--fq-rate flag.
  243: This option replaces the \--bandwidth flag, which is now deprecated
  244: but (at least for now) still accepted.
  245: .TP
  246: .BR --pacing-timer " \fIn\fR[KMGT]"
  247: set pacing timer interval in microseconds (default 1000 microseconds,
  248: or 1 ms).
  249: This controls iperf3's internal pacing timer for the \-b/\--bitrate
  250: option.
  251: The timer fires at the interval set by this parameter.
  252: Smaller values of the pacing timer parameter smooth out the traffic
  253: emitted by iperf3, but potentially at the cost of performance due to
  254: more frequent timer processing.
  255: .TP
  256: .BR --fq-rate " \fIn\fR[KMGT]"
  257: Set a rate to be used with fair-queueing based socket-level pacing,
  258: in bits per second.
  259: This pacing (if specified) will be in addition to any pacing due to
  260: iperf3's internal throughput pacing (\-b/\--bitrate flag), and both can be
  261: specified for the same test.
  262: Only available on platforms supporting the
  263: \fCSO_MAX_PACING_RATE\fR socket option (currently only Linux).
  264: The default is no fair-queueing based pacing.
  265: .TP
  266: .BR --no-fq-socket-pacing
  267: This option is deprecated and will be removed.
  268: It is equivalent to specifying --fq-rate=0.
  269: .TP
  270: .BR -t ", " --time " \fIn\fR"
  271: time in seconds to transmit for (default 10 secs)
  272: .TP
  273: .BR -n ", " --bytes " \fIn\fR[KMGT]"
  274: number of bytes to transmit (instead of \-t)
  275: .TP
  276: .BR -k ", " --blockcount " \fIn\fR[KMGT]"
  277: number of blocks (packets) to transmit (instead of \-t or \-n)
  278: .TP
  279: .BR -l ", " --length " \fIn\fR[KMGT]"
  280: length of buffer to read or write.  For TCP tests, the default value
  281: is 128KB.
  282: In the case of UDP, iperf3 tries to dynamically determine a reasonable
  283: sending size based on the path MTU; if that cannot be determined it
  284: uses 1460 bytes as a sending size.
  285: For SCTP tests, the default size is 64KB.
  286: .TP
  287: .BR --cport " \fIport\fR"
  288: bind data streams to a specific client port (for TCP and UDP only,
  289: default is to use an ephemeral port)
  290: .TP
  291: .BR -P ", " --parallel " \fIn\fR"
  292: 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.
  293: .TP
  294: .BR -R ", " --reverse
  295: reverse the direction of a test, so that the server sends data to the
  296: client
  297: .TP
  298: .BR --bidir
  299: test in both directions (normal and reverse), with both the client and
  300: server sending and receiving data simultaneously
  301: .TP
  302: .BR -w ", " --window " \fIn\fR[KMGT]"
  303: window size / socket buffer size (this gets sent to the server and used on that side too)
  304: .TP
  305: .BR -M ", " --set-mss " \fIn\fR"
  306: set TCP/SCTP maximum segment size (MTU - 40 bytes)
  307: .TP
  308: .BR -N ", " --no-delay " "
  309: set TCP/SCTP no delay, disabling Nagle's Algorithm
  310: .TP
  311: .BR -4 ", " --version4 " "
  312: only use IPv4
  313: .TP
  314: .BR -6 ", " --version6 " "
  315: only use IPv6
  316: .TP
  317: .BR -S ", " --tos " \fIn\fR"
  318: set the IP type of service. The usual prefixes for octal and hex can be used,
  319: i.e. 52, 064 and 0x34 all specify the same value.
  320: .TP
  321: .BR "--dscp " \fIdscp\fR
  322: set the IP DSCP bits.  Both numeric and symbolic values are accepted. Numeric
  323: values can be specified in decimal, octal and hex (see --tos above).
  324: .TP
  325: .BR -L ", " --flowlabel " \fIn\fR"
  326: set the IPv6 flow label (currently only supported on Linux)
  327: .TP
  328: .BR -X ", " --xbind " \fIname\fR"
  329: Bind SCTP associations to a specific subset of links using sctp_bindx(3).
  330: The \fB--B\fR flag will be ignored if this flag is specified.
  331: Normally SCTP will include the protocol addresses of all active links
  332: on the local host when setting up an association. Specifying at least
  333: one \fB--X\fR name will disable this behaviour.
  334: This flag must be specified for each link to be included in the
  335: association, and is supported for both iperf servers and clients
  336: (the latter are supported by passing the first \fB--X\fR argument to bind(2)).
  337: Hostnames are accepted as arguments and are resolved using
  338: getaddrinfo(3).
  339: If the \fB--4\fR or \fB--6\fR flags are specified, names
  340: which do not resolve to addresses within the
  341: specified protocol family will be ignored.
  342: .TP
  343: .BR --nstreams " \fIn\fR"
  344: Set number of SCTP streams.
  345: .TP
  346: .BR -Z ", " --zerocopy " "
  347: Use a "zero copy" method of sending data, such as sendfile(2),
  348: instead of the usual write(2).
  349: .TP
  350: .BR -O ", " --omit " \fIn\fR"
  351: Omit the first n seconds of the test, to skip past the TCP slow-start
  352: period.
  353: .TP
  354: .BR -T ", " --title " \fIstr\fR"
  355: Prefix every output line with this string.
  356: .TP
  357: .BR --extra-data " \fIstr\fR"
  358: Specify an extra data string field to be included in JSON output.
  359: .TP
  360: .BR -C ", " --congestion " \fIalgo\fR"
  361: Set the congestion control algorithm (Linux and FreeBSD only).  An
  362: older
  363: .B --linux-congestion
  364: synonym for this flag is accepted but is deprecated.
  365: .TP
  366: .BR "--get-server-output"
  367: Get the output from the server.
  368: The output format is determined by the server (in particular, if the
  369: server was invoked with the \fB--json\fR flag, the output will be in
  370: JSON format, otherwise it will be in human-readable format).
  371: If the client is run with \fB--json\fR, the server output is included
  372: in a JSON object; otherwise it is appended at the bottom of the
  373: human-readable output.
  374: .TP
  375: .BR --udp-counters-64bit
  376: Use 64-bit counters in UDP test packets.
  377: The use of this option can help prevent counter overflows during long
  378: or high-bitrate UDP tests.  Both client and server need to be running
  379: at least version 3.1 for this option to work.  It may become the
  380: default behavior at some point in the future.
  381: .TP
  382: .BR --repeating-payload
  383: Use repeating pattern in payload, instead of random bytes.
  384: The same payload is used in iperf2 (ASCII '0..9' repeating).
  385: It might help to test and reveal problems in networking gear with hardware
  386: compression (including some WiFi access points), where iperf2 and iperf3
  387: perform differently, just based on payload entropy.
  388: .TP
  389: .BR --username " \fIusername\fR" 
  390: username to use for authentication to the iperf server (if built with
  391: OpenSSL support).
  392: The password will be prompted for interactively when the test is run.  Note,
  393: the password to use can also be specified via the IPERF3_PASSWORD environment
  394: variable. If this variable is present, the password prompt will be skipped.
  395: .TP
  396: .BR --rsa-public-key-path " \fIfile\fR" 
  397: path to the RSA public key used to encrypt authentication credentials
  398: (if built with OpenSSL support)
  399: 
  400: .SH EXAMPLES
  401: .SS "Authentication - RSA Keypair"
  402: The authentication feature of iperf3 requires an RSA public keypair.
  403: The public key is used to encrypt the authentication token containing the 
  404: user credentials, while the private key is used to decrypt the authentication token.
  405: An example of a set of UNIX/Linux commands to generate correct keypair follows:
  406: .sp 1 
  407: .in +.5i
  408: > openssl genrsa -des3 -out private.pem 2048
  409: .sp 0
  410: > openssl rsa -in private.pem -outform PEM -pubout -out public.pem
  411: .sp 0
  412: > openssl rsa -in private.pem -out private_not_protected.pem -outform PEM  
  413: .in -.5i
  414: .sp 1
  415: After these commands, the public key will be contained in the file
  416: public.pem and the private key will be contained in the file
  417: private_not_protected.pem.
  418: .SS "Authentication - Authorized users configuration file"
  419: A simple plaintext file must be provided to the iperf3 server in order to specify 
  420: the authorized user credentials.
  421: The file is a simple list of comma-separated pairs of a username and a
  422: corresponding password hash.
  423: The password hash is a SHA256 hash of the string "{$user}$password".
  424: The file can also contain commented lines (starting with the \fC#\fR
  425: character).
  426: An example of commands to generate the password hash on a UNIX/Linux system
  427: is given below:
  428: .sp 1 
  429: .in +.5i
  430: > S_USER=mario S_PASSWD=rossi
  431: .sp 0
  432: > echo -n "{$S_USER}$S_PASSWD" | sha256sum | awk '{ print $1 }'
  433: .in -.5i
  434: .sp 1
  435: An example of a password file (with an entry corresponding to the
  436: above username and password) is given below:
  437: .sp 0
  438: .in +.5i
  439: > cat credentials.csv
  440: .sp 0
  441: # file format: username,sha256
  442: .sp 0
  443: mario,bf7a49a846d44b454a5d11e7acfaf13d138bbe0b7483aa3e050879700572709b
  444: .in -.5i
  445: .sp 1
  446: 
  447: .SH AUTHORS
  448: A list of the contributors to iperf3 can be found within the
  449: documentation located at
  450: \fChttps://software.es.net/iperf/dev.html#authors\fR.
  451: 
  452: .SH "SEE ALSO"
  453: libiperf(3),
  454: https://software.es.net/iperf