| .TH IPERF3 1 "May 2016" ESnet "User Manuals" |
| .SH NAME |
| iperf3 \- perform network throughput tests |
| .SH SYNOPSIS |
| .B iperf3 -s [ |
| .I options |
| .B ] |
| .br |
| .B iperf3 -c |
| .I server |
| .B [ |
| .I options |
| .B ] |
| |
| .SH 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. |
| |
| .SH "GENERAL OPTIONS" |
| .TP |
| .BR -p ", " --port " \fIn\fR" |
| set server port to listen on/connect to to \fIn\fR (default 5201) |
| .TP |
| .BR -f ", " --format " " |
| [kmKM] format to report: Kbits, Mbits, KBytes, MBytes |
| .TP |
| .BR -i ", " --interval " \fIn\fR" |
| pause \fIn\fR seconds between periodic bandwidth reports; |
| default is 1, use 0 to disable |
| .TP |
| .BR -F ", " --file " \fIname\fR" |
| 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 |
| .TP |
| .BR -A ", " --affinity " \fIn/n,m\fR" |
| 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 \fIn\fR form of this argument (where \fIn\fR is a CPU number). |
| In addition, on the client side you can override the server's |
| affinity for just that one test, using the \fIn,m\fR 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 multiple |
| CPUs). |
| .TP |
| .BR -B ", " --bind " \fIhost\fR" |
| bind to a specific interface |
| .TP |
| .BR -V ", " --verbose " " |
| give more detailed output |
| .TP |
| .BR -J ", " --json " " |
| output in JSON format |
| .TP |
| .BR --logfile " \fIfile\fR" |
| send output to a log file. |
| .TP |
| .BR --forceflush " " |
| force flushing output at every interval. |
| Used to avoid buffering when sending output to pipe. |
| .TP |
| .BR -d ", " --debug " " |
| emit debugging output. |
| Primarily (perhaps exclusively) of use to developers. |
| .TP |
| .BR -v ", " --version " " |
| show version information and quit |
| .TP |
| .BR -h ", " --help " " |
| show a help synopsis |
| |
| .SH "SERVER SPECIFIC OPTIONS" |
| .TP |
| .BR -s ", " --server " " |
| run in server mode |
| .TP |
| .BR -D ", " --daemon " " |
| run the server in background as a daemon |
| .TP |
| .BR -I ", " --pidfile " \fIfile\fR" |
| write a file with the process ID, most useful when running as a daemon. |
| .TP |
| .BR -1 ", " --one-off |
| handle one client connection, then exit. |
| |
| .SH "CLIENT SPECIFIC OPTIONS" |
| .TP |
| .BR -c ", " --client " \fIhost\fR" |
| run in client mode, connecting to the specified server |
| .TP |
| .BR --sctp |
| use SCTP rather than TCP (FreeBSD and Linux) |
| .TP |
| .BR -u ", " --udp |
| use UDP rather than TCP |
| .TP |
| .BR -b ", " --bandwidth " \fIn\fR[KM]" |
| set target bandwidth to \fIn\fR 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 \fCSO_MAX_PACING_RATE\fR socket option |
| (currently only Linux), fair-queueing socket-level pacing, implemented in |
| the kernel, will be used. |
| On other platforms, iperf3 will implement its own rate control. |
| .TP |
| .BR --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. |
| .TP |
| .BR -t ", " --time " \fIn\fR" |
| time in seconds to transmit for (default 10 secs) |
| .TP |
| .BR -n ", " --bytes " \fIn\fR[KM]" |
| number of bytes to transmit (instead of \-t) |
| .TP |
| .BR -k ", " --blockcount " \fIn\fR[KM]" |
| number of blocks (packets) to transmit (instead of \-t or \-n) |
| .TP |
| .BR -l ", " --length " \fIn\fR[KM]" |
| length of buffer to read or write (default 128 KB for TCP, 8KB for UDP) |
| .TP |
| .BR --cport " \fIport\fR" |
| bind data streams to a specific client port (for TCP and UDP only, |
| default is to use an ephemeral port) |
| .TP |
| .BR -P ", " --parallel " \fIn\fR" |
| number of parallel client streams to run |
| .TP |
| .BR -R ", " --reverse |
| run in reverse mode (server sends, client receives) |
| .TP |
| .BR -w ", " --window " \fIn\fR[KM]" |
| window size / socket buffer size (this gets sent to the server and used on that side too) |
| .TP |
| .BR -M ", " --set-mss " \fIn\fR" |
| set TCP/SCTP maximum segment size (MTU - 40 bytes) |
| .TP |
| .BR -N ", " --no-delay " " |
| set TCP/SCTP no delay, disabling Nagle's Algorithm |
| .TP |
| .BR -4 ", " --version4 " " |
| only use IPv4 |
| .TP |
| .BR -6 ", " --version6 " " |
| only use IPv6 |
| .TP |
| .BR -S ", " --tos " \fIn\fR" |
| set the IP 'type of service' |
| .TP |
| .BR -L ", " --flowlabel " \fIn\fR" |
| set the IPv6 flow label (currently only supported on Linux) |
| .TP |
| .BR -X ", " --xbind " \fIname\fR" |
| Bind SCTP associations to a specific subset of links using sctp_bindx(3). |
| The \fB--B\fR 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 association. Specifying at least |
| one \fB--X\fR name will disable this behaviour. |
| 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 \fB--X\fR argument to bind(2)). |
| Hostnames are accepted as arguments and are resolved using |
| getaddrinfo(3). |
| If the \fB--4\fR or \fB--6\fR flags are specified, names |
| which do not resolve to addresses within the |
| specified protocol family will be ignored. |
| .TP |
| .BR --nstreams " \fIn\fR" |
| Set number of SCTP streams. |
| .TP |
| .BR -Z ", " --zerocopy " " |
| Use a "zero copy" method of sending data, such as sendfile(2), |
| instead of the usual write(2). |
| .TP |
| .BR -O ", " --omit " \fIn\fR" |
| Omit the first n seconds of the test, to skip past the TCP slow-start |
| period. |
| .TP |
| .BR -T ", " --title " \fIstr\fR" |
| Prefix every output line with this string. |
| .TP |
| .BR -C ", " --congestion " \fIalgo\fR" |
| Set the congestion control algorithm (Linux and FreeBSD only). An |
| older |
| .B --linux-congestion |
| synonym for this flag is accepted but is deprecated. |
| .TP |
| .BR "--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 \fB--json\fR flag, the output will be in |
| JSON format, otherwise it will be in human-readable format). |
| If the client is run with \fB--json\fR, the server output is included |
| in a JSON object; otherwise it is appended at the bottom of the |
| human-readable output. |
| |
| .SH AUTHORS |
| A list of the contributors to iperf3 can be found within the |
| documentation located at |
| \fChttp://software.es.net/iperf/dev.html#authors\fR. |
| |
| .SH "SEE ALSO" |
| libiperf(3), |
| http://software.es.net/iperf |
