iperf2
Perform network throughput tests
Syntax:
iperf2 -s [ options ]
iperf2 -c server [ options ]
iperf2 -u -s [ options ]
iperf2 -u -c server [ options ]
Runs on:
QNX OS
Options:
General options
- -B host[:port][%device]
- --bind host[:port][%device]
- Bind to the host, IP address, or multicast address specified by host, and, optionally, a port, a device, or both.
- -b mean,[stdev]
- --bandwidth mean,[stdev]
- Set the target bandwidth and optional standard deviation.
- -C
- --compatibility
- For use with older versions; don't send extra messages.
- -e
- --enhanced
- Display enhanced output in reports. Otherwise, use legacy report (ver 2.0.5) formatting.
- -f a|b|k|m|g|B|K|M|G
- --format a|b|k|m|g|B|K|M|G
- The format to report: adaptive, bits, Kbits, Mbits, Gbits, Bytes, KBytes, MBytes, GBytes.
- -h
- --help
- Print a help synopsis.
- --hide-ips
- Obscure IP addresses in output. This is useful when you want to publish results and not display the full IP addresses. IPv4 only.
- -i t|f
- --interval t|f
- Sample or display interval reports every t seconds (default), or, if you specify, f, every frame or burst. The frame interval reporting is experimental. (Fast-sampling is not enabled.)
- -l n[k|m|K|M]
- --len n[k|m|K|M]
- Set the length of the read/write buffer size (TCP) or length (UDP) to n. Default is 128 K (TCP) or 1470 (UDP).
- --l2checks
- Perform layer 2 length checks on received UDP packets.
- -M n
- --mss n
- Set the TCP maximum segment size (MTU - 40 bytes).
- -m
- --print_mss
- Print the TCP maximum segment size (MTU - TCP/IP header).
- -N
- --nodelay
- Set TCP no delay, disabling Nagle's Algorithm.
- --NUM_REPORT_STRUCTS count
- Override the default shared memory size between the traffic threads and reporter thread to mitigate mutex lock contentions. The default value of 5000 should be sufficient for 1 Gb/s networks. Increase this value if you see a message that warns you that the reporter thread is too slow. If you don't see the warning message, increasing this value won't have any significant effect (other than to use some additional memory.)
- -o filename
- --output filename
- Output the report or error message to the specified file.
- --permit-key[=value]
- Set a key value that must match for the server to accept traffic on a connection. If you specify --permit-key without a value on the server, a key value is autogenerated and displayed in the server's initial settings report. The lifetime of the key is set using --permit-key-timeout (default 20 seconds). The value is required on clients. The value is also used as part of the transfer ID in reports. Setting the option on the client but not on the server also causes the server to reject the client's traffic. TCP only, no UDP support.
- -p m[-n]
- --port m[-n]
- Set the client or server port to send or listen on (default is 5001). Optionally, set a port range where m is the start of the range and n is the end (e.g., -p 6002-6008).
- --sum-dstip
- Sum traffic threads based upon the destination IP address (default is source IP address).
- --sum-only
- Set the output to sum reports only. Useful when -P is set to a large value.
- -t n
- --time n
- The time in seconds to listen for new traffic connections, receive traffic, or send traffic.
- -u
- --udp
- Use UDP rather than TCP.
- -v
- --version
- Print version information, and then exit.
- -w n[k|m|K|M]
- --window n[k|m|K|M]
- Set the TCP window size (socket buffer size).
- -x C|D|M|S|V
- --reportexclude C|D|M|S|V
- Exclude C(connection), D(data), M(multicast), S(settings),
or V(server) reports. Specify at least one argument. You can
specify multiple arguments (e.g.,
-x CDMSV
). - -y C|c
- --reportstyle C|c
- If set to C or c, report results as CSV (comma-separated values).
- -Z algo
- --tcp-congestion algo
- Set the default congestion-control algorithm to use for new connections. May require root privileges.
For available options, use the
net.inet.tcp.cc.available
sysctl variable (see sysctl). For more information about congestion control algorithms, see the FreeBSD modular congestion control documentation: https://www.freebsd.org/cgi/man.cgi?query=mod_cc&sektion=4&apropos=0&manpath=FreeBSD+13.1-RELEASE+and+Ports - -z
- --realtime
- Request real-time scheduler.
Server-specific options
- -1
- --singleclient
- Set the server to process only one client at a time.
- -B ip[%device]
- --bind ip[%device]
- Bind source IP address, and, optionally, source device for receiving.
- -b n[k|m|g|K|M|G]
- --bandwidth n[k|m|g|K|M|G]
- Set the target bandwidth to n bits/sec. For server, TCP only.
- -D
- --daemon
- Run the server as a daemon.
- -H host
- --ssm-host host
- Set the source host (IP address) for Source Specific Multicast (SSM) multicast (i.e., the S in the (S,G) entry).
- --histograms[=binwidth[u|m],bincount[,lowerci][,upperci]]
- Enable latency histograms for UDP packets (with -u), for TCP writes (with --trip-times), or for either UDP or TCP with --isochronous clients. The binning can be modified. Default binwidth is 1 millisecond; append u for microseconds or m for milliseconds. The bincount variable is total bins (default 1000). Specify the confidence interval between 0-100% with lowerci (default 5%) and upperci (default 95%) .
- --permit-key[=value]
- Set a key value that must match for the server to accept traffic from a client (client key is also set using --permit-key). If you specify --permit-keywithout a value on the server, the server automatically generates a globally unique key and displays it in its initial settings report. The lifetime of the key is set using --permit-key-timeout (default 20 seconds). TCP only, no UDP support.
- --permit-key-timeout value|0
- Set the lifetime of the permit key in seconds (default is 20), or specify 0 to disable the timer.
- -R
- --remove
- Remove the IPerfService (Windows only).
- -s
- --server
- Run in server mode.
- -t n
- --time n
- The time in seconds to listen for new traffic connections, receive traffic, or both (default is infinite).
- --tcp-rx-window-clamp n[k|m|K|M]
- Set the value of the TCP_WINDOW_CLAMP socket option, in bytes.
- -U
- --single_udp
- Run in single-threaded UDP mode.
- -V
- --ipv6_domain
- Enable IPv6 reception by setting the domain and socket to AF_INET6 (can receive on both IPv4 and IPv6).
Client-specific options
- -B ip | ip:port | ipv6 -V | ipv6:port -V
- --bind ip[%device]
- Bind source IP address, and, optionally, port as the source of traffic.
- -b n[k|m|g|K|M|G][,std_dev[k|m|g|K|M|G]] | n[k|m|g|K|M|G]pps
- --bandwidth n[k|m|g|K|M|G][,std_dev[k|m|g|K|M|G]] | n[k|m|g|K|M|G]pps
- Set the target bandwidth to n bits/sec (default 1 Mbit/sec) or
n packets/sec. Can be used with TCP or UDP. Optionally, for
variable loads, use the format
n
[k|m|g|K|M|G],
std_dev[k|m|g|K|M|G]
, where n is the mean and std_dev is the standard deviation. - --burst-period[=n]
- Set the burst period in seconds (default is 1). The assumed use case is low duty cycle traffic bursts.
- --burst-size[=n]
- Set the burst size in bytes. Defaults to 1 MB if not value is specified.
- -c host[%device]
- --client host[%device]
- Run in client mode, connecting to host, and, optionally, bind the device specified by dev to that output interface (SO_BINDTODEVICE socket option; requires root).
- --connect-only[=n]
- Only perform a TCP connect (or 3-way handshake), without any data transfer, which is useful to measure TCP connect() times. Optional value of n is the total number of connects to do (specify 0 (zero) to run forever). Note that -i rate limits the connects, -P creates bursts, and -t ends the client (which ends its connect attempts).
- --connect-retries[=n]
- Number of times to retry a TCP connect at the application level.
- -d
- --dualtest
- Do a bidirectional test simultaneously, using two unidirectional sockets.
- -F name
- --fileinput name
- Input the data to be transmitted from a file.
- --fq-rate n[k|m|g|K|M|G]
- Set a rate to use with fair-queueing based socket-level pacing, in bytes or bits per second. The suffixes indicate bytes/sec (uppercase) or bits/sec (lowercase).
- --full-duplex n[k|m|g|K|M|G]
- Run a full duplex test (i.e., traffic in both transmit and receive directions using the same socket).
- --histograms[=binwidth[u|m],bincount[,lowerci][,upperci]]
- Enable select()/write() histograms with --tcp-write-prefetch. The binning can be modified. Default binwidth is 100 microseconds; append u for microseconds or m for milliseconds. The bincount variable is total bins (default 10000). Specify the confidence interval between 0-100% with lowerci (default 5%) and upperci (default 95%), within 3 standard deviations.
- -I
- --stdin
- Input the data to be transmitted from stdin.
- --incr-dstip
- Increment the destination IP address when using the parallel option (-P).
- --incr-dstport
- Increment the destination port when using the parallel option (-P).
- --incr-srcip
- Increment the source IP address when using the parallel option (-P).
- --ipg n
- Set the inter-packet gap in seconds for packets, or within a frame/burst when --isochronous is set.
- --isochronous[=fps:mean,stdev | =fps:burst_sizep]
- Send isochronous traffic at a frequency in frames per second (default 60), with the load defined by mean (default 20m) and standard deviation (default 0) using a log normal distribution. For example, the default is 60:20m,0. The suffixes indicate bytes/sec (uppercase) or bits/sec (lowercase). Alternatively, the p suffix sets the burst size in packets (e.g., isochronous=2:25p sends two 25 packet bursts every second, or one 25 packet burst every 0.5 seconds.).
- -L n
- --listenport n
- The port to receive bidirectional tests back on.
- --local-only[=1|0]
- Set to 1 to limit traffic to the local network only (using SO_DONTROUTE); otherwise, set to zero.
- -n n[k|m|K|M]
- --num n[k|m|K|M]
- The number of bytes to transmit (instead of -t).
- --near-congestion[=n]
- Enable TCP write rate limiting per sampled round-trip time (RTT). The delay is applied after the number of bytes specified by -l have completed. The time delay is set by multiplying the RTT by the value of n. This value defaults to 0.5 if it is not set. Values less than 1 are supported but the value cannot be negative. This is an experimental feature. It is not likely stable on live networks. Suggested use is over controlled test networks.
- --no-connect-sync
- By default, parallel traffic threads (i.e., -P is greater than 1) synchronize after their TCP connects and prior to each sending traffic; that is, all the threads first complete (or error) the TCP 3-way handshake before any traffic thread starts sending. This option disables that synchronization. Each traffic thread starts sending immediately after completing its successful connect.
- --no-udp-fin
- Don't perform the UDP final server-to-client exchange, which means there won't be a final server report displayed on the client. All test packets are from the client to the server and no packets should be sent in the other direction. It's highly suggested that you set -t on the server if you use this option because only one trigger ending packet is sent from client to server and if it's lost then the server continues to run.
- -P n
- --parallel n
- The number of parallel client threads to run.
- --permit-key[=value]
- Set a key value that must match the server's value (also set using --permit-key) for the server to accept traffic from the client. TCP only, no UDP support.
- -R
- --reverse
- Reverse the traffic flow after header exchange. Useful for testing through firewalls.
- -r
- --tradeoff
- Do a bidirectional test individually: client-to-server, followed by server-to-client.
- -S
- --tos
- Set the socket's IP_TOS (byte) field.
- -T n
- --ttl n
- The time-to-live, for multicast (default 1).
- -t n|0
- --time n|0
- The time in seconds to transmit for (default 10 secs). Use 0 for infinite transmission.
- --tcp-write-prefetch n[k|m|K|M]
- Set TCP_NOTSENT_LOWAT on the socket and use event-based writes via select() on the socket.
- --trip-times
- Enable the measurement of end-to-end write-to-read latencies (client and server clocks must be synchronized).
- --txdelay-time
- Time in seconds to hold back or delay after the TCP connect and prior to the socket writes. For UDP it's the delay between the traffic thread starting and the first write.
- --txstart-time n.n
- Set the txstart-time to n.n using Unix or epoch time format. Supports microsecond
resolution (e.g., 1536014418.123456). For example, to delay one second using command substitution is
iperf2 -c 192.168.1.10 --txstart-time $(expr $(date +%s) + 1).$(date +%N).
- -V
- --ipv6_domain
- Set the domain to IPv6 (send packets over IPv6).
- -X
- --peerdetect
- Run peer version detection prior to traffic.
Description:
The iperf2 tool measures network throughput. It can test either TCP or UDP throughput. To perform an iperf2 test, you must establish both a server (to receive traffic) and a client (to generate and send traffic).
For a different version of this tool, see iperf3.
Environment variables:
- TCP_WINDOW_SIZE
- Controls the size of TCP buffers.
Contributing author:
iperf2 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, Tim Auckland tim.auckland at gmail.com, and Robert J. McMahon rjmcmahon at rjmcmahon.com.
See also http://iperf2.sourceforge.net/.