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