Annotation of embedaddon/iperf/src/iperf3.1, revision 1.1.1.2
1.1.1.2 ! misho 1: .TH IPERF3 1 "July 2020" 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
9: .B iperf3 -c
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.
! 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.
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
120: .BR -F ", " --file " \fIname\fR"
1.1.1.2 ! misho 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.
1.1 misho 128: .TP
129: .BR -A ", " --affinity " \fIn/n,m\fR"
1.1.1.2 ! misho 130: Set the CPU affinity, if possible (Linux, FreeBSD, and Windows only).
1.1 misho 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"
1.1.1.2 ! misho 141: bind to the specific interface associated with address \fIhost\fR.
1.1 misho 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
1.1.1.2 ! misho 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
1.1 misho 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.
1.1.1.2 ! misho 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.
1.1 misho 208: .SH "CLIENT SPECIFIC OPTIONS"
209: .TP
210: .BR -c ", " --client " \fIhost\fR"
1.1.1.2 ! misho 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.
1.1 misho 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
1.1.1.2 ! misho 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
1.1 misho 233: separately to each stream.
1.1.1.2 ! misho 234: You can also add a '/' and a number to the bitrate specifier.
1.1 misho 235: This is called "burst mode".
236: It will send the given number of packets without pausing, even if that
1.1.1.2 ! misho 237: temporarily exceeds the specified throughput limit.
! 238: Setting the target bitrate to 0 will disable bitrate limits
1.1 misho 239: (particularly useful for UDP tests).
1.1.1.2 ! misho 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.
1.1 misho 265: .TP
266: .BR --no-fq-socket-pacing
1.1.1.2 ! misho 267: This option is deprecated and will be removed.
! 268: It is equivalent to specifying --fq-rate=0.
1.1 misho 269: .TP
270: .BR -t ", " --time " \fIn\fR"
271: time in seconds to transmit for (default 10 secs)
272: .TP
1.1.1.2 ! misho 273: .BR -n ", " --bytes " \fIn\fR[KMGT]"
1.1 misho 274: number of bytes to transmit (instead of \-t)
275: .TP
1.1.1.2 ! misho 276: .BR -k ", " --blockcount " \fIn\fR[KMGT]"
1.1 misho 277: number of blocks (packets) to transmit (instead of \-t or \-n)
278: .TP
1.1.1.2 ! misho 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.
1.1 misho 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"
1.1.1.2 ! misho 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.
1.1 misho 293: .TP
294: .BR -R ", " --reverse
1.1.1.2 ! misho 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
1.1 misho 301: .TP
1.1.1.2 ! misho 302: .BR -w ", " --window " \fIn\fR[KMGT]"
1.1 misho 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"
1.1.1.2 ! misho 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).
1.1 misho 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
1.1.1.2 ! misho 357: .BR --extra-data " \fIstr\fR"
! 358: Specify an extra data string field to be included in JSON output.
! 359: .TP
1.1 misho 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.
1.1.1.2 ! misho 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
1.1 misho 446:
447: .SH AUTHORS
448: A list of the contributors to iperf3 can be found within the
449: documentation located at
1.1.1.2 ! misho 450: \fChttps://software.es.net/iperf/dev.html#authors\fR.
1.1 misho 451:
452: .SH "SEE ALSO"
453: libiperf(3),
1.1.1.2 ! misho 454: 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