Annotation of embedaddon/iperf/src/iperf3.1, revision 1.1.1.3
1.1.1.3 ! misho 1: .TH IPERF3 1 "September 2022" ESnet "User Manuals"
1.1 misho 2: .SH NAME
3: iperf3 \- perform network throughput tests
4: .SH SYNOPSIS
5: .B iperf3 -s [
6: .I options
7: .B ]
8: .br
1.1.1.3 ! misho 9: .B iperf3 -c
1.1 misho 10: .I server
11: .B [
12: .I options
13: .B ]
14:
15: .SH DESCRIPTION
1.1.1.2 misho 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.
1.1.1.3 ! misho 99: Because the contents of the JSON structure are only completely known
1.1.1.2 misho 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.
1.1 misho 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 " "
1.1.1.2 misho 114: [kmgtKMGT] format to report: Kbits/Mbits/Gbits/Tbits
1.1 misho 115: .TP
116: .BR -i ", " --interval " \fIn\fR"
1.1.1.2 misho 117: pause \fIn\fR seconds between periodic throughput reports;
1.1 misho 118: default is 1, use 0 to disable
119: .TP
1.1.1.3 ! misho 120: .BR -I ", " --pidfile " \fIfile\fR"
! 121: write a file with the process ID, most useful when running as a daemon.
! 122: .TP
1.1 misho 123: .BR -F ", " --file " \fIname\fR"
1.1.1.2 misho 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.
1.1 misho 131: .TP
132: .BR -A ", " --affinity " \fIn/n,m\fR"
1.1.1.2 misho 133: Set the CPU affinity, if possible (Linux, FreeBSD, and Windows only).
1.1 misho 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
1.1.1.3 ! misho 140: to a single CPU (as opposed to a set containing potentially multiple
1.1 misho 141: CPUs).
142: .TP
1.1.1.3 ! misho 143: .BR -B ", " --bind " \fIhost\fR[\fB%\fIdev\fR]"
1.1.1.2 misho 144: bind to the specific interface associated with address \fIhost\fR.
1.1.1.3 ! misho 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.)
1.1 misho 153: .TP
154: .BR -V ", " --verbose " "
1.1.1.3 ! misho 155: give more detailed output
1.1 misho 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
1.1.1.2 misho 163: .BR --forceflush " "
164: force flushing output at every interval.
165: Used to avoid buffering when sending output to pipe.
166: .TP
1.1.1.3 ! misho 167: .BR --timestamps "[\fB=\fIformat\fR]"
1.1.1.2 misho 168: prepend a timestamp at the start of each output line.
169: By default, timestamps have the format emitted by
170: .BR ctime ( 1 ).
1.1.1.3 ! misho 171: Optionally, \fC=\fR followed by
! 172: a format specification can be passed to customize the
1.1.1.2 misho 173: timestamps, see
174: .BR strftime ( 3 ).
1.1.1.3 ! misho 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.
1.1.1.2 misho 190: .TP
1.1 misho 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
1.1.1.3 ! misho 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.
1.1.1.2 misho 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"
1.1.1.3 ! misho 228: path to the RSA private key (not password-protected) used to decrypt
1.1.1.2 misho 229: authentication credentials from the client (if built with OpenSSL
230: support).
1.1.1.3 ! misho 231: .TP
1.1.1.2 misho 232: .BR --authorized-users-path " \fIfile\fR"
1.1.1.3 ! misho 233: path to the configuration file containing authorized users credentials to run
1.1.1.2 misho 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.
1.1.1.3 ! misho 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.
1.1 misho 242: .SH "CLIENT SPECIFIC OPTIONS"
243: .TP
1.1.1.3 ! misho 244: .BR -c ", " --client " \fIhost\fR[\fB%\fIdev\fR]"
1.1.1.2 misho 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.
1.1.1.3 ! misho 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.
1.1 misho 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
1.1.1.2 misho 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
1.1 misho 270: separately to each stream.
1.1.1.2 misho 271: You can also add a '/' and a number to the bitrate specifier.
1.1 misho 272: This is called "burst mode".
273: It will send the given number of packets without pausing, even if that
1.1.1.2 misho 274: temporarily exceeds the specified throughput limit.
275: Setting the target bitrate to 0 will disable bitrate limits
1.1 misho 276: (particularly useful for UDP tests).
1.1.1.2 misho 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.
1.1 misho 302: .TP
303: .BR --no-fq-socket-pacing
1.1.1.2 misho 304: This option is deprecated and will be removed.
305: It is equivalent to specifying --fq-rate=0.
1.1 misho 306: .TP
307: .BR -t ", " --time " \fIn\fR"
308: time in seconds to transmit for (default 10 secs)
309: .TP
1.1.1.2 misho 310: .BR -n ", " --bytes " \fIn\fR[KMGT]"
1.1 misho 311: number of bytes to transmit (instead of \-t)
312: .TP
1.1.1.2 misho 313: .BR -k ", " --blockcount " \fIn\fR[KMGT]"
1.1 misho 314: number of blocks (packets) to transmit (instead of \-t or \-n)
315: .TP
1.1.1.2 misho 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.
1.1 misho 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"
1.1.1.2 misho 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.
1.1 misho 330: .TP
331: .BR -R ", " --reverse
1.1.1.2 misho 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
1.1 misho 338: .TP
1.1.1.2 misho 339: .BR -w ", " --window " \fIn\fR[KMGT]"
1.1.1.3 ! misho 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)).
1.1 misho 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"
1.1.1.2 misho 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).
1.1 misho 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"
1.1.1.3 ! misho 394: Perform pre-test for N seconds and omit the pre-test statistics, to skip past the TCP slow-start
1.1 misho 395: period.
396: .TP
397: .BR -T ", " --title " \fIstr\fR"
398: Prefix every output line with this string.
399: .TP
1.1.1.2 misho 400: .BR --extra-data " \fIstr\fR"
401: Specify an extra data string field to be included in JSON output.
402: .TP
1.1 misho 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.
1.1.1.2 misho 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
1.1.1.3 ! misho 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"
1.1.1.2 misho 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
1.1.1.3 ! misho 443: .BR --rsa-public-key-path " \fIfile\fR"
1.1.1.2 misho 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.
1.1.1.3 ! misho 450: The public key is used to encrypt the authentication token containing the
1.1.1.2 misho 451: user credentials, while the private key is used to decrypt the authentication token.
1.1.1.3 ! misho 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
1.1.1.2 misho 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
1.1.1.3 ! misho 463: > openssl rsa -in private.pem -out private_not_protected.pem -outform PEM
1.1.1.2 misho 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"
1.1.1.3 ! misho 470: A simple plaintext file must be provided to the iperf3 server in order to specify
1.1.1.2 misho 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:
1.1.1.3 ! misho 479: .sp 1
1.1.1.2 misho 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
1.1 misho 497:
498: .SH AUTHORS
499: A list of the contributors to iperf3 can be found within the
500: documentation located at
1.1.1.2 misho 501: \fChttps://software.es.net/iperf/dev.html#authors\fR.
1.1 misho 502:
503: .SH "SEE ALSO"
504: libiperf(3),
1.1.1.2 misho 505: https://software.es.net/iperf
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to iperf3.1 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / iperf / src