Update on-line manpage to reflect iperf 3.1.5.
diff --git a/docs/invoking.rst b/docs/invoking.rst
index d239369..354b0b5 100644
--- a/docs/invoking.rst
+++ b/docs/invoking.rst
@@ -27,216 +27,227 @@
::
IPERF3(1) User Manuals IPERF3(1)
-
-
-
+
+
+
NAME
- iperf3 - perform network throughput tests
-
+ iperf3 - perform network throughput tests
+
SYNOPSIS
- iperf3 -s [ options ]
- iperf3 -c server [ options ]
-
-
+ iperf3 -s [ options ]
+ iperf3 -c server [ options ]
+
+
DESCRIPTION
- iperf3 is a tool for performing network throughput measurements. It
- can test either TCP or UDP throughput. To perform an iperf3 test the
- user must establish both a server and a client.
-
-
+ iperf3 is a tool for performing network throughput measurements. It
+ can test either TCP or UDP throughput. To perform an iperf3 test the
+ user must establish both a server and a client.
+
+
GENERAL OPTIONS
- -p, --port n
- set server port to listen on/connect to to n (default 5201)
-
- -f, --format
- [kmKM] format to report: Kbits, Mbits, KBytes, MBytes
-
- -i, --interval n
- pause n seconds between periodic bandwidth reports; default is
- 1, use 0 to disable
-
- -F, --file name
- client-side: read from the file and write to the network,
- instead of using random data; server-side: read from the network
- and write to the file, instead of throwing the data away
-
- -A, --affinity n/n,m
- Set the CPU affinity, if possible (Linux and FreeBSD only). On
- both the client and server you can set the local affinity by
- using the n form of this argument (where n is a CPU number). In
- addition, on the client side you can override the server's
- affinity for just that one test, using the n,m form of argument.
- Note that when using this feature, a process will only be bound
- to a single CPU (as opposed to a set containing potentialy mul-
- tiple CPUs).
-
- -B, --bind host
- bind to a specific interface
-
- -V, --verbose
- give more detailed output
-
- -J, --json
- output in JSON format
-
- --logfile file
- send output to a log file.
-
- --forceflush
- force flushing output at every interval. Used to avoid buffer-
- ing when sending output to pipe.
-
- -d, --debug
- emit debugging output. Primarily (perhaps exclusively) of use
- to developers.
-
- -v, --version
- show version information and quit
-
- -h, --help
- show a help synopsis
-
-
+ -p, --port n
+ set server port to listen on/connect to to n (default 5201)
+
+ -f, --format
+ [kmKM] format to report: Kbits, Mbits, KBytes, MBytes
+
+ -i, --interval n
+ pause n seconds between periodic bandwidth reports; default is
+ 1, use 0 to disable
+
+ -F, --file name
+ client-side: read from the file and write to the network,
+ instead of using random data; server-side: read from the network
+ and write to the file, instead of throwing the data away
+
+ -A, --affinity n/n,m
+ Set the CPU affinity, if possible (Linux and FreeBSD only). On
+ both the client and server you can set the local affinity by
+ using the n form of this argument (where n is a CPU number). In
+ addition, on the client side you can override the server's
+ affinity for just that one test, using the n,m form of argument.
+ Note that when using this feature, a process will only be bound
+ to a single CPU (as opposed to a set containing potentialy mul-
+ tiple CPUs).
+
+ -B, --bind host
+ bind to a specific interface
+
+ -V, --verbose
+ give more detailed output
+
+ -J, --json
+ output in JSON format
+
+ --logfile file
+ send output to a log file.
+
+ --forceflush
+ force flushing output at every interval. Used to avoid buffer-
+ ing when sending output to pipe.
+
+ -d, --debug
+ emit debugging output. Primarily (perhaps exclusively) of use
+ to developers.
+
+ -v, --version
+ show version information and quit
+
+ -h, --help
+ show a help synopsis
+
+
SERVER SPECIFIC OPTIONS
- -s, --server
- run in server mode
-
- -D, --daemon
- run the server in background as a daemon
-
- -I, --pidfile file
- write a file with the process ID, most useful when running as a
- daemon.
-
- -1, --one-off
- handle one client connection, then exit.
-
-
+ -s, --server
+ run in server mode
+
+ -D, --daemon
+ run the server in background as a daemon
+
+ -I, --pidfile file
+ write a file with the process ID, most useful when running as a
+ daemon.
+
+ -1, --one-off
+ handle one client connection, then exit.
+
+
CLIENT SPECIFIC OPTIONS
- -c, --client host
- run in client mode, connecting to the specified server
-
- --sctp use SCTP rather than TCP (FreeBSD and Linux)
-
- -u, --udp
- use UDP rather than TCP
-
- -b, --bandwidth n[KM]
- set target bandwidth to n bits/sec (default 1 Mbit/sec for UDP,
- unlimited for TCP). If there are multiple streams (-P flag),
- the bandwidth limit is applied separately to each stream. You
- can also add a '/' and a number to the bandwidth specifier.
- This is called "burst mode". It will send the given number of
- packets without pausing, even if that temporarily exceeds the
- specified bandwidth limit. Setting the target bandwidth to 0
- will disable bandwidth limits (particularly useful for UDP
- tests). On platforms supporting the SO_MAX_PACING_RATE socket
- option (currently only Linux), fair-queueing socket-level pac-
- ing, implemented in the kernel, will be used. On other plat-
- forms, iperf3 will implement its own rate control.
-
- --no-fq-socket-pacing
- disable the use of fair-queueing based socket-level pacing with
- the -b option, and rely on iperf3's internal rate control.
-
- -t, --time n
- time in seconds to transmit for (default 10 secs)
-
- -n, --bytes n[KM]
- number of bytes to transmit (instead of -t)
-
- -k, --blockcount n[KM]
- number of blocks (packets) to transmit (instead of -t or -n)
-
- -l, --length n[KM]
- length of buffer to read or write (default 128 KB for TCP, 8KB
- for UDP)
-
- --cport port
- bind data streams to a specific client port (for TCP and UDP
- only, default is to use an ephemeral port)
-
- -P, --parallel n
- number of parallel client streams to run
-
- -R, --reverse
- run in reverse mode (server sends, client receives)
-
- -w, --window n[KM]
- window size / socket buffer size (this gets sent to the server
- and used on that side too)
-
- -M, --set-mss n
- set TCP/SCTP maximum segment size (MTU - 40 bytes)
-
- -N, --no-delay
- set TCP/SCTP no delay, disabling Nagle's Algorithm
-
- -4, --version4
- only use IPv4
-
- -6, --version6
- only use IPv6
-
- -S, --tos n
- set the IP 'type of service'
-
- -L, --flowlabel n
- set the IPv6 flow label (currently only supported on Linux)
-
- -X, --xbind name
- Bind SCTP associations to a specific subset of links using
- sctp_bindx(3). The --B flag will be ignored if this flag is
- specified. Normally SCTP will include the protocol addresses of
- all active links on the local host when setting up an associa-
- tion. Specifying at least one --X name will disable this behav-
- iour. This flag must be specified for each link to be included
- in the association, and is supported for both iperf servers and
- clients (the latter are supported by passing the first --X argu-
- ment to bind(2)). Hostnames are accepted as arguments and are
- resolved using getaddrinfo(3). If the --4 or --6 flags are
- specified, names which do not resolve to addresses within the
- specified protocol family will be ignored.
-
- --nstreams n
- Set number of SCTP streams.
-
- -Z, --zerocopy
- Use a "zero copy" method of sending data, such as sendfile(2),
- instead of the usual write(2).
-
- -O, --omit n
- Omit the first n seconds of the test, to skip past the TCP slow-
- start period.
-
- -T, --title str
- Prefix every output line with this string.
-
- -C, --congestion algo
- Set the congestion control algorithm (Linux and FreeBSD only).
- An older --linux-congestion synonym for this flag is accepted
- but is deprecated.
-
- --get-server-output
- Get the output from the server. The output format is determined
- by the server (in particular, if the server was invoked with the
- --json flag, the output will be in JSON format, otherwise it
- will be in human-readable format). If the client is run with
- --json, the server output is included in a JSON object; other-
- wise it is appended at the bottom of the human-readable output.
-
-
+ -c, --client host
+ run in client mode, connecting to the specified server
+
+ --sctp use SCTP rather than TCP (FreeBSD and Linux)
+
+ -u, --udp
+ use UDP rather than TCP
+
+ -b, --bandwidth n[KM]
+ set target bandwidth to n bits/sec (default 1 Mbit/sec for UDP,
+ unlimited for TCP). If there are multiple streams (-P flag),
+ the bandwidth limit is applied separately to each stream. You
+ can also add a '/' and a number to the bandwidth specifier.
+ This is called "burst mode". It will send the given number of
+ packets without pausing, even if that temporarily exceeds the
+ specified bandwidth limit. Setting the target bandwidth to 0
+ will disable bandwidth limits (particularly useful for UDP
+ tests). This bandwidth limit is implemented internally inside
+ iperf3, and is available on all platforms. Compare with the
+ --fq-rate flag.
+
+ --fq-rate n[KM]
+ Set a rate to be used with fair-queueing based socket-level pac-
+ ing, in bits per second. This pacing (if specified) will be in
+ addition to any pacing due to iperf3's internal bandwidth pacing
+ (-b flag), and both can be specified for the same test. Only
+ available on platforms supporting the SO_MAX_PACING_RATE socket
+ option (currently only Linux). The default is no fair-queueing
+ based pacing.
+
+ --no-fq-socket-pacing
+ This option is deprecated and will be removed. It is equivalent
+ to specifying --fq-rate=0.
+
+ -t, --time n
+ time in seconds to transmit for (default 10 secs)
+
+ -n, --bytes n[KM]
+ number of bytes to transmit (instead of -t)
+
+ -k, --blockcount n[KM]
+ number of blocks (packets) to transmit (instead of -t or -n)
+
+ -l, --length n[KM]
+ length of buffer to read or write. For TCP tests, the default
+ value is 128KB. In the case of UDP, iperf3 tries to dynamically
+ determine a reasonable sending size based on the path MTU; if
+ that cannot be determined it uses 1460 bytes as a sending size.
+ For SCTP tests, the default size is 64KB.
+
+ --cport port
+ bind data streams to a specific client port (for TCP and UDP
+ only, default is to use an ephemeral port)
+
+ -P, --parallel n
+ number of parallel client streams to run
+
+ -R, --reverse
+ run in reverse mode (server sends, client receives)
+
+ -w, --window n[KM]
+ window size / socket buffer size (this gets sent to the server
+ and used on that side too)
+
+ -M, --set-mss n
+ set TCP/SCTP maximum segment size (MTU - 40 bytes)
+
+ -N, --no-delay
+ set TCP/SCTP no delay, disabling Nagle's Algorithm
+
+ -4, --version4
+ only use IPv4
+
+ -6, --version6
+ only use IPv6
+
+ -S, --tos n
+ set the IP 'type of service'
+
+ -L, --flowlabel n
+ set the IPv6 flow label (currently only supported on Linux)
+
+ -X, --xbind name
+ Bind SCTP associations to a specific subset of links using
+ sctp_bindx(3). The --B flag will be ignored if this flag is
+ specified. Normally SCTP will include the protocol addresses of
+ all active links on the local host when setting up an associa-
+ tion. Specifying at least one --X name will disable this behav-
+ iour. This flag must be specified for each link to be included
+ in the association, and is supported for both iperf servers and
+ clients (the latter are supported by passing the first --X argu-
+ ment to bind(2)). Hostnames are accepted as arguments and are
+ resolved using getaddrinfo(3). If the --4 or --6 flags are
+ specified, names which do not resolve to addresses within the
+ specified protocol family will be ignored.
+
+ --nstreams n
+ Set number of SCTP streams.
+
+ -Z, --zerocopy
+ Use a "zero copy" method of sending data, such as sendfile(2),
+ instead of the usual write(2).
+
+ -O, --omit n
+ Omit the first n seconds of the test, to skip past the TCP slow-
+ start period.
+
+ -T, --title str
+ Prefix every output line with this string.
+
+ -C, --congestion algo
+ Set the congestion control algorithm (Linux and FreeBSD only).
+ An older --linux-congestion synonym for this flag is accepted
+ but is deprecated.
+
+ --get-server-output
+ Get the output from the server. The output format is determined
+ by the server (in particular, if the server was invoked with the
+ --json flag, the output will be in JSON format, otherwise it
+ will be in human-readable format). If the client is run with
+ --json, the server output is included in a JSON object; other-
+ wise it is appended at the bottom of the human-readable output.
+
+
AUTHORS
- A list of the contributors to iperf3 can be found within the documenta-
- tion located at http://software.es.net/iperf/dev.html#authors.
-
-
+ A list of the contributors to iperf3 can be found within the documenta-
+ tion located at http://software.es.net/iperf/dev.html#authors.
+
+
SEE ALSO
- libiperf(3), http://software.es.net/iperf
-
-
-
- ESnet May 2016 IPERF3(1)
+ libiperf(3), http://software.es.net/iperf
+
+
+
+ ESnet January 2017 IPERF3(1)
The iperf3 manual page will typically be installed in manual
section 1.
