iperf3: Usage, Options & Common CI Errors
iperf3 measures TCP/UDP throughput between a client and a server.
iperf3 benchmarks the network path between two endpoints. It is strictly client/server: one side runs -s, the other -c, and iperf3 is notoriously incompatible with the older iperf2.
What it does
iperf3 runs a server (-s) on one host and a client (-c) on another to measure achievable TCP or UDP throughput, jitter, and loss. It reports per-interval and summary bandwidth between the two.
Common usage
iperf3 -s # server side
iperf3 -c server.host # client side
iperf3 -c server.host -t 30 -P 4 # 30s, 4 parallel streams
iperf3 -c server.host -u -b 100M # UDP at 100 Mbit/s
iperf3 -c server.host -R # reverse (download) testOptions
| Flag | What it does |
|---|---|
| -s / -c <host> | Run as server / connect as client |
| -t <secs> | Test duration (client) |
| -P <N> | Number of parallel streams |
| -u -b <rate> | UDP mode at a target bitrate |
| -R | Reverse: server sends to client |
| -p <port> | Use a non-default port (default 5201) |
Common errors in CI
"iperf3: error - unable to connect to server: Connection refused" means no -s server is listening (start it first, or the port/host is wrong). "the server is busy running a test. try again later" - iperf3 serves one client at a time by default; use -p with multiple servers or serialize. iperf3 is NOT wire-compatible with iperf2: pointing iperf3 -c at an iperf2 server gives "received an unknown control message". Firewalls/security groups blocking 5201 surface as a connect timeout.
Using this in CI
A runner shell is not a login shell. It does not read your dotfiles, it usually has no TTY, and by default it does not stop on the first error, so a failing command in the middle of a multi-line run block can leave the job green.
# make the shell behave the way you assume it does
- name: Build
shell: bash
run: |
set -euo pipefail # exit on error, undefined vars, and pipeline failures
./do-the-thing | tee out.log