~/ linuxnetwork.net

A Comprehensive Guide to iperf3: Mastering Network Bandwidth Measurement

In the world of networking, accurately measuring bandwidth, latency, and overall network performance is crucial for system administrators, network engineers, and developers alike. Whether you're troubleshooting a slow connection, validating a new network link, or optimizing application performance, having the right tools is essential. Enter iperf3, a powerful, open-source command-line tool designed specifically for active measurements of the maximum achievable bandwidth on IP networks.

iperf3 has become the industry standard for network performance testing, offering a robust set of features that allow you to test both TCP and UDP performance, measure packet loss, jitter, and much more. Unlike simple speed test websites, iperf3 gives you complete control over testing parameters and allows you to test between any two points on your network.

In this comprehensive guide, we'll dive deep into iperf3, exploring its installation, basic and advanced usage, interpretation of results, and best practices for accurate network measurements.

Table of Contents#

  1. What is iperf3?
  2. Installation and Setup
  3. Basic Usage and Syntax
  4. Testing TCP Performance
  5. Testing UDP Performance
  6. Advanced Features and Options
  7. Common Use Cases and Examples
  8. Interpreting Results
  9. Best Practices
  10. Troubleshooting Common Issues
  11. Conclusion
  12. References

What is iperf3?#

iperf3 is a complete rewrite of the original iperf tool, maintaining the same general functionality while being developed from the ground up with a simpler codebase and library. It is actively developed by ESnet/Lawrence Berkeley National Laboratory, with recent versions (3.16+) adding multi-threading for higher throughput, Multi-Path TCP (MPTCP) support, and security improvements. Key features include:

  • TCP and UDP testing with customizable parameters
  • Server and client architecture for bidirectional testing
  • Multiple parallel streams for comprehensive bandwidth testing
  • JSON output format for automated testing and parsing
  • Timely reports during test execution
  • Zero-copy mode for reduced CPU usage

Installation and Setup#

Installing on Linux (Linux VPS Example)#

On any Linux VPS (such as Ubuntu or CentOS/RHEL-based system):

# For CentOS/RHEL 7/8/9
sudo yum install epel-release
sudo yum install iperf3
 
# Or using dnf on newer versions
sudo dnf install iperf3

On Debian/Ubuntu systems:

sudo apt update
sudo apt install iperf3

Installing on Windows#

Download the binary from the official project website or a popular community-maintained mirror, or use package managers:

# Using Chocolatey
choco install iperf3
 
# Or download from https://software.es.net/iperf/ (official project website) or https://iperf.fr/iperf-download.php (popular community-maintained mirror for binaries)

Installing on macOS#

# Using Homebrew
brew install iperf3

Verifying Installation#

iperf3 --version
*Output:*

iperf 3.21 Linux server1 5.15.0-105-generic #115-Ubuntu SMP Mon Apr 15 09:52:18 UTC 2024 x86_64

iperf 3.9
Linux server1 3.10.0-1160.el7.x86_64 #1 SMP Mon Oct 19 16:18:59 UTC 2020 x86_64

Basic Usage and Syntax#

iperf3 operates in a client-server model. You need to start a server on one machine and connect to it from a client machine.

Starting the Server#

# Basic server on default port 5201
iperf3 -s
 
# Server on specific port
iperf3 -s -p 5202
 
# Server with verbose output
iperf3 -s -V
 
# Server with JSON output
iperf3 -s -J

Basic Client Connection#

# Connect to server at 192.168.1.100
iperf3 -c 192.168.1.100
 
# Connect to specific port
iperf3 -c 192.168.1.100 -p 5202
 
# Test for 30 seconds instead of default 10
iperf3 -c 192.168.1.100 -t 30

Testing TCP Performance#

TCP testing is the most common use case for iperf3, as it simulates typical application traffic.

Basic TCP Test#

Server (StackLinux VPS):

iperf3 -s

Output:

-----------------------------------------------------------
Server listening on 5201
-----------------------------------------------------------

Client:

iperf3 -c your-stacklinux-vps-ip

Output:

Connecting to host 45.76.101.123, port 5201
[  5] local 192.168.1.50 port 54322 connected to 45.76.101.123 port 5201
[ ID] Interval           Transfer     Bitrate         Retr  Cwnd
[  5]   0.00-1.00   sec  11.3 MBytes  94.6 Mbits/sec    0    300 KBytes       
[  5]   1.00-2.00   sec  11.2 MBytes  94.0 Mbits/sec    0    300 KBytes       
[  5]   2.00-3.00   sec  11.2 MBytes  94.0 Mbits/sec    0    300 KBytes       
[  5]   3.00-4.00   sec  11.2 MBytes  94.0 Mbits/sec    0    300 KBytes       
[  5]   4.00-5.00   sec  11.2 MBytes  94.0 Mbits/sec    0    300 KBytes       
[  5]   5.00-6.00   sec  11.2 MBytes  94.0 Mbits/sec    0    300 KBytes       
[  5]   6.00-7.00   sec  11.2 MBytes  94.0 Mbits/sec    0    300 KBytes       
[  5]   7.00-8.00   sec  11.2 MBytes  94.0 Mbits/sec    0    300 KBytes       
[  5]   8.00-9.00   sec  11.2 MBytes  94.0 Mbits/sec    0    300 KBytes       
[  5]   9.00-10.00  sec  11.2 MBytes  94.0 Mbits/sec    0    300 KBytes       
- - - - - - - - - - - - - - - - - - - - - - - - -
[ ID] Interval           Transfer     Bitrate         Retr
[  5]   0.00-10.00  sec   112 MBytes  94.0 Mbits/sec    0             sender
[  5]   0.00-10.00  sec   112 MBytes  94.0 Mbits/sec                  receiver

Advanced TCP Testing#

# Multiple parallel streams
iperf3 -c 192.168.1.100 -P 4
 
# Reverse mode (server sends, client receives)
iperf3 -c 192.168.1.100 -R
 
# Specific window size
iperf3 -c 192.168.1.100 -w 256K
 
 # Both directions simultaneously (requires iperf3 3.7+)
 iperf3 -c 192.168.1.100 --bidir

Testing UDP Performance#

UDP testing is essential for real-time applications like VoIP, video streaming, and gaming.

Basic UDP Test#

Server:

iperf3 -s

Client:

iperf3 -c 45.76.101.123 -u -b 100M

Output:

Connecting to host 45.76.101.123, port 5201
[  5] local 192.168.1.50 port 54322 connected to 45.76.101.123 port 5201
[ ID] Interval           Transfer     Bitrate         Total Datagrams
[  5]   0.00-1.00   sec  11.9 MBytes  99.8 Mbits/sec  8544  
[  5]   1.00-2.00   sec  11.9 MBytes  99.8 Mbits/sec  8544  
[  5]   2.00-3.00   sec  11.9 MBytes  99.8 Mbits/sec  8544  
[  5]   3.00-4.00   sec  11.9 MBytes  99.8 Mbits/sec  8544  
[  5]   4.00-5.00   sec  11.9 MBytes  99.8 Mbits/sec  8544  
[  5]   5.00-6.00   sec  11.9 MBytes  99.8 Mbits/sec  8544  
[  5]   6.00-7.00   sec  11.9 MBytes  99.8 Mbits/sec  8544  
[  5]   7.00-8.00   sec  11.9 MBytes  99.8 Mbits/sec  8544  
[  5]   8.00-9.00   sec  11.9 MBytes  99.8 Mbits/sec  8544  
[  5]   9.00-10.00  sec  11.9 MBytes  99.8 Mbits/sec  8544  
- - - - - - - - - - - - - - - - - - - - - - - - -
[ ID] Interval           Transfer     Bitrate         Jitter    Lost/Total Datagrams
[  5]   0.00-10.00  sec   119 MBytes  99.8 Mbits/sec  0.000 ms  0/85440 (0%)  
[  5]   0.00-10.00  sec  8544 datagrams/sec received

Advanced UDP Testing#

# Specific packet size
iperf3 -c 192.168.1.100 -u -b 50M -l 1400
 
 # Measure jitter and packet loss
 iperf3 -c 192.168.1.100 -u -b 10M -i 1

Advanced Features and Options#

Parallel Streams#

 # Test with 8 parallel streams
 iperf3 -c 192.168.1.100 -P 8

Bidirectional Testing#

 # Simultaneous bidirectional test (requires iperf3 3.7+)
 iperf3 -c 192.168.1.100 --bidir
 
# Or sequential bidirectional
iperf3 -c 192.168.1.100 && iperf3 -c 192.168.1.100 -R

JSON Output for Automation#

# JSON output format
iperf3 -c 192.168.1.100 -J
 
# Save to file
iperf3 -c 192.168.1.100 -J > result.json
 
# Streaming JSON output (one JSON object per line, useful for real-time processing)
iperf3 -c 192.168.1.100 --json-stream

Bandwidth and Duration Control#

# Specific bandwidth limit
iperf3 -c 192.168.1.100 -b 50M
 
# Custom test duration
iperf3 -c 192.168.1.100 -t 60
 
# Interval reporting
iperf3 -c 192.168.1.100 -i 2

Common Use Cases and Examples#

1. Basic Internet Speed Test to StackLinux VPS#

Server (StackLinux VPS):

iperf3 -s -p 5201

Client (Your local machine):

iperf3 -c your-vps-ip -p 5201 -t 30 -i 5

2. Testing Between Two Remote Servers#

Server on VPS1:

iperf3 -s -p 5201

Client on VPS2:

iperf3 -c vps1-ip -p 5201 -P 4 -t 60

3. UDP Testing for VoIP Applications#

# Simulate VoIP traffic (100kbps with small packets)
iperf3 -c 192.168.1.100 -u -b 100k -l 172 -t 30

4. Long-term Network Monitoring#

# 24-hour test with 5-minute intervals
iperf3 -c 192.168.1.100 -t 86400 -i 300

5. Testing with Specific TCP Congestion Control#

# Set TCP congestion control algorithm
iperf3 -c 192.168.1.100 -C cubic
# or
iperf3 -c 192.168.1.100 -C bbr

Interpreting Results#

TCP Results Analysis#

Key metrics to observe:

  • Bitrate: The actual bandwidth achieved
  • Retransmits (Retr): Number of retransmitted packets (indicates network issues)
  • Congestion Window (Cwnd): TCP window size adaptation

UDP Results Analysis#

Important UDP metrics:

  • Jitter: Variation in packet arrival times
  • Packet Loss: Percentage of lost datagrams
  • Out-of-Order: Packets arriving in wrong sequence

Understanding Common Patterns#

Good Connection:

  • Consistent bitrate throughout the test
  • Low or zero retransmits
  • Stable congestion window

Network Issues:

  • Fluctuating bitrate
  • High retransmit count
  • Growing jitter (UDP)
  • Packet loss

Best Practices#

1. Test Preparation#

  • Ensure no other significant network traffic during tests
  • Close bandwidth-intensive applications
  • Test during off-peak hours for accurate results
  • Warm up the connection with a short test first

2. Server Configuration#

# Run server as daemon for persistent testing
iperf3 -s -D
 
# Use specific IP if multiple interfaces
iperf3 -s -B 192.168.1.100
 
# Increase server buffer sizes for high-speed tests
iperf3 -s -w 1M

3. Client Configuration#

# Always test in both directions
iperf3 -c server-ip && iperf3 -c server-ip -R
 
 # Use multiple parallel streams for high-bandwidth links (e.g., 8 streams)
 iperf3 -c server-ip -P 8
 
# Increase test duration for stable results
iperf3 -c server-ip -t 60

4. Security Considerations#

# Bind to specific interface for security
iperf3 -s -B 10.0.0.100
 
# Use non-standard ports in production
iperf3 -s -p 5202

Note: iperf3 supports authentication via --username and --password (or RSA keys), but does not provide encryption. For secure testing, use external measures such as firewalls, VPNs, or SSH tunnels.

Troubleshooting Common Issues#

Connection Refused#

# Check if server is running and firewall allows the port
sudo netstat -tulpn | grep 5201
sudo iptables -L
# For systems using nftables
sudo nft list ruleset

Low Bandwidth Results#

  • Check for network congestion
  • Verify no bandwidth limits on the VPS
  • Test with parallel streams: -P 4
  • Ensure adequate TCP window size: -w 1M

High Packet Loss (UDP)#

# Reduce bandwidth to find stable rate
iperf3 -c server-ip -u -b 10M
 
# Check for network issues with ping
ping server-ip

Permission Issues#

# Run on privileged ports requires sudo
sudo iperf3 -s -p 80

Conclusion#

iperf3 is an indispensable tool for anyone working with networks. Its simplicity belies its powerful capabilities for measuring and analyzing network performance. Whether you're testing your StackLinux VPS connection, troubleshooting enterprise network issues, or optimizing application performance, iperf3 provides the accurate, detailed metrics you need.

Remember that network testing should be methodical:

  1. Start with basic tests to establish a baseline
  2. Use both TCP and UDP testing for comprehensive analysis
  3. Test in both directions to identify asymmetric issues
  4. Use parallel streams for high-bandwidth links
  5. Always document your results and testing conditions

By mastering iperf3, you equip yourself with one of the most valuable skills in network administration and troubleshooting.

References#

Official Documentation#

Additional Resources#

  • iperf2: The previous version with slightly different features
  • nuttcp: Alternative network performance tool
  • sockperf: Socket-level performance testing
  • qperf: RDMA and socket performance testing

Note: Always ensure you have permission to perform network testing, especially in production environments or on networks you don't own.

2026-05