Basic workflow
bash
# On host A - server side
iperf3 -s # listens on :5201
# On host B - client, connects to A
iperf3 -c 10.0.0.1 # 10 seconds by default
iperf3 -c 10.0.0.1 -t 30 # 30-second test
The client prints an interval table followed by a summary:
[ ID] Interval Transfer Bitrate Retr Cwnd
[ 5] 0.00-1.00 sec 1.10 GBytes 9.45 Gbits/sec 0 1.62 MBytes
...
[ ID] Interval Transfer Bitrate Retr
[ 5] 0.00-10.00 sec 10.9 GBytes 9.41 Gbits/sec 0 sender
[ 5] 0.00-10.00 sec 10.9 GBytes 9.41 Gbits/sec receiver
Watch Bitrate (throughput) and Retr (TCP retransmits). A non-zero
Retr indicates packet loss or congestion along the path.
Useful flags
bash
iperf3 -s -D # run server as a daemon (detach from terminal)
iperf3 -s -p 9999 # use a different port
iperf3 -c host -P 4 # -P: 4 parallel streams (breaks single-flow limit)
iperf3 -c host -R # reverse: server sends to client (tests downlink)
iperf3 -c host -u -b 100M # UDP mode, target 100 Mbit/s
iperf3 -c host -t 60 -i 2 # 60-second test, report every 2 seconds
iperf3 -c host -J # JSON output (for scripting)
Reading the output
- TCP test, low throughput, retr > 0: packet loss on the path. Check cmd-tc qdisc, MTU, and congestion control in tcp-states.
- TCP test, low throughput, retr = 0: bandwidth-delay product issue. The window is too small or the test is CPU-bound.
- UDP test, packet loss > 0%: real loss on the route.
Paired test with tc netem
A standard exercise: measure the baseline, degrade the network, then compare:
bash
# Baseline
iperf3 -c server -t 5
# Add degradation on the outgoing interface
sudo tc qdisc add dev eth0 root netem delay 50ms loss 1%
iperf3 -c server -t 5
# -> Bitrate should drop sharply (TCP cannot ramp up under packet loss)
# Remove the degradation
sudo tc qdisc del dev eth0 root
iperf2 vs iperf3
- iperf2 (also called
iperf) is the older tool. It supports multiple threads and works well for UDP testing. - iperf3 is the modern replacement. It is single-threaded, produces cleaner reports, and supports JSON output.
For a simultaneous bidirectional test with iperf3, run two parallel
instances (-c host and -c host -R in parallel). iperf2 handled
this with a single -d flag.
Capabilities in containers
For UDP testing above the user quota, you may need CAP_NET_RAW.
A basic TCP test works without elevated privileges.