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