iperf3 Bandwidth Testing Guide: TCP/UDP Commands Explained

iperf3 is the standard command-line tool for measuring real network throughput, jitter and packet loss between two machines. It works on a simple client-server model — one host listens, the other generates traffic — and the numbers it produces tell you immediately whether a link is running at line rate or where the bottleneck is. This guide covers installation, TCP and UDP testing, parallel streams, reverse tests, JSON output for automation and the tuning knobs that make results accurate on fast links.

Installation and Server Setup

# Debian/Ubuntu
apt install iperf3
# RHEL/CentOS
yum install iperf3

Start the server on the receiving host (listens on TCP 5201 by default):

iperf3 -s
iperf3 -s -p 9000        # custom port
iperf3 -s -1             # accept one test, then exit
iperf3 -s -D             # run as daemon

Open the port in the firewall on the server side before testing: ufw allow 5201/tcp and ufw allow 5201/udp when you also test UDP.

Running Client Tests

iperf3 -c 192.168.1.10            # basic 10-second TCP test
iperf3 -c 192.168.1.10 -t 30      # longer test
iperf3 -c 192.168.1.10 -i 2       # report every 2 seconds
iperf3 -c 192.168.1.10 -P 8       # 8 parallel streams

On 10G/25G links a single TCP stream often tops out at 3-5 Gbps because one CPU core cannot keep up; use -P parallel streams to saturate the link. To measure the opposite direction add -R (server sends to client), useful on asymmetric paths, or --bidir (both directions at once, iperf3 3.7+) for simultaneous throughput.

UDP Tests: Jitter and Packet Loss

TCP hides loss through retransmission, so UDP is the better test when you want jitter and loss numbers — important for VoIP, video and real-time traffic. Always set the target bandwidth with -b, otherwise iperf3 defaults to a useless 1 Mbps:

iperf3 -c 192.168.1.10 -u -b 100M
iperf3 -c 192.168.1.10 -u -b 1G -t 30
iperf3 -c 192.168.1.10 -u -b 500M -l 1400    # 1400-byte packets like real traffic

[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams
[  5]   0.00-10.00  sec   596 MBytes   500 Mbits/sec  0.025 ms  0/427225 (0%)

Jitter near 0 ms with 0% loss means the path is clean; any loss above 0% at your target rate means the link cannot sustain that bandwidth.

JSON Output for Automation and Monitoring

iperf3 -c 192.168.1.10 -J > result.json

The -J flag emits structured JSON that scripts can parse with jq — for example .end.sum_received.bits_per_second — and feed to Grafana or a log file for trend analysis. Combine with -P 2 and -t 20 for a repeatable daily check, and alert when throughput drops below a threshold.

Tuning and Troubleshooting

• Throughput lower than expected: CPU bottleneck (add -P), small TCP window (-w 4M for high-BDP paths), or NIC offloads; verify the interface first with ethtool diagnostics.
• Unable to connect: firewall blocking 5201; check with ss -lntp | grep 5201 on the server.
• UDP 100% loss: firewall dropping UDP or the path cannot sustain the configured -b.
• Server busy: kill stale instances with pkill iperf3.
• 40G+ links: run several server instances on different ports to work around the single-threaded CPU limit.

iperf3 pairs well with the packet-level view from tcpdump BPF filters when you need to confirm retransmissions, and with the host-side checks in our Linux network troubleshooting guide.

原文链接：https://linux-shell.org/linux-shell/iperf3