| .TH IPERF 1 "January 2015" 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 only). |
| On both the client and server you can set the local affinity; |
| in addition, on the client side you can override the server's |
| affinity for just that one test, using the n,m form. |
| .TP |
| .BR -V ", " --verbose " " |
| give more detailed output |
| .TP |
| .BR -J ", " --json " " |
| output in JSON format |
| .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 -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 -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). |
| .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 -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 -B ", " --bind " \fIn\fR[KM]" |
| bind to a specific interface or multicast address |
| .TP |
| .BR -M ", " --set-mss " \fIn\fR" |
| set TCP maximum segment size (MTU - 40 bytes) |
| .TP |
| .BR -N ", " --no-delay " " |
| set TCP 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 -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 ", " --linux-congestion " \fIalgo\fR" |
| Set the congestion control algorithm (linux only). |
| .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 |
| Iperf was originally written by Mark Gates and Alex Warshavsky. |
| Man page and maintence by Jon Dugan <jdugan at x1024 dot net>. |
| Other contributions from Ajay Tirumala, Jim Ferguson, |
| Feng Qin, |
| Kevin Gibbs, |
| John Estabrook <jestabro at ncsa.uiuc.edu>, |
| Andrew Gallatin <gallatin at gmail.com>, |
| Stephen Hemminger <shemminger at linux-foundation.org> |
| |
| .SH "SEE ALSO" |
| libiperf(3), |
| http://software.es.net/iperf |