How to test bandwidth → iperf3 -s / iperf3 -c
How to Test Bandwidth Using iperf3: Complete Guide to Server and Client Commands
Table of Contents
1. [Introduction](#introduction)
2. [Prerequisites and Requirements](#prerequisites-and-requirements)
3. [Understanding iperf3 Basics](#understanding-iperf3-basics)
4. [Installing iperf3](#installing-iperf3)
5. [Setting Up the iperf3 Server](#setting-up-the-iperf3-server)
6. [Running iperf3 Client Tests](#running-iperf3-client-tests)
7. [Advanced iperf3 Options and Parameters](#advanced-iperf3-options-and-parameters)
8. [Practical Examples and Use Cases](#practical-examples-and-use-cases)
9. [Interpreting Test Results](#interpreting-test-results)
10. [Common Issues and Troubleshooting](#common-issues-and-troubleshooting)
11. [Best Practices and Professional Tips](#best-practices-and-professional-tips)
12. [Security Considerations](#security-considerations)
13. [Conclusion](#conclusion)
Introduction
Network bandwidth testing is a critical aspect of network administration, troubleshooting, and performance optimization. Whether you're diagnosing slow network connections, validating network upgrades, or ensuring service level agreements are met, accurate bandwidth measurement is essential. iperf3 stands out as the industry-standard tool for network performance testing, offering reliable and comprehensive bandwidth measurement capabilities.
This comprehensive guide will teach you everything you need to know about using iperf3 to test network bandwidth, from basic server-client setups to advanced testing scenarios. You'll learn how to set up iperf3 servers using `iperf3 -s`, connect clients with `iperf3 -c `, interpret results, and troubleshoot common issues. By the end of this article, you'll have the expertise to conduct professional-grade network bandwidth testing in any environment.
Prerequisites and Requirements
System Requirements
Before diving into iperf3 testing, ensure your systems meet the following requirements:
- Operating System: Linux, macOS, Windows, or FreeBSD
- Network Connectivity: Two or more networked devices
- Administrative Access: Root or administrator privileges for installation
- Available Ports: Default port 5201 (TCP/UDP) or custom ports
- Memory: Minimum 64MB RAM available
- CPU: Any modern processor (testing may be CPU-limited on older hardware)
Network Prerequisites
- Firewall Configuration: Ensure iperf3 ports are open
- Network Topology Understanding: Know your network path and potential bottlenecks
- IP Addressing: Valid IP addresses on both server and client systems
- Time Synchronization: Synchronized clocks for accurate measurements
Knowledge Prerequisites
- Basic command-line interface familiarity
- Understanding of network concepts (TCP/UDP, bandwidth, throughput)
- Knowledge of IP addressing and networking fundamentals
Understanding iperf3 Basics
What is iperf3?
iperf3 is a network performance measurement tool designed to test maximum achievable bandwidth on IP networks. It supports tuning various parameters related to timing, buffers, and protocols (TCP, UDP, SCTP with IPv4 and IPv6). Unlike its predecessor iperf2, iperf3 features a complete rewrite with a more accurate measurement engine and simplified architecture.
Key Features
- Protocol Support: TCP, UDP, and SCTP testing
- IPv4 and IPv6: Full support for both IP versions
- Bidirectional Testing: Simultaneous upload and download testing
- Multiple Streams: Parallel connection testing
- JSON Output: Machine-readable results for automation
- Real-time Reporting: Live bandwidth measurements during tests
- Cross-platform: Available on all major operating systems
How iperf3 Works
iperf3 operates on a client-server model:
1. Server Mode: One system runs `iperf3 -s` to listen for incoming connections
2. Client Mode: Another system runs `iperf3 -c ` to initiate the test
3. Data Transfer: Client sends/receives data to/from server
4. Measurement: Both systems measure throughput, packet loss, and other metrics
5. Reporting: Results are displayed on both client and server
Installing iperf3
Linux Installation
Ubuntu/Debian Systems
```bash
sudo apt update
sudo apt install iperf3
```
CentOS/RHEL/Fedora Systems
```bash
CentOS/RHEL 7/8
sudo yum install iperf3
Fedora/CentOS 8+
sudo dnf install iperf3
```
Arch Linux
```bash
sudo pacman -S iperf3
```
macOS Installation
Using Homebrew
```bash
brew install iperf3
```
Using MacPorts
```bash
sudo port install iperf3
```
Windows Installation
Using Chocolatey
```powershell
choco install iperf3
```
Manual Installation
1. Download iperf3 Windows binary from the official website
2. Extract to a directory in your PATH
3. Open Command Prompt or PowerShell as Administrator
Verifying Installation
After installation, verify iperf3 is working correctly:
```bash
iperf3 --version
```
Expected output:
```
iperf 3.x.x (date)
Linux hostname 5.x.x-x-generic x86_64
Optional features available: CPU affinity setting, IPv6 flow label, TCP congestion algorithm setting, sendfile / zerocopy, socket pacing
```
Setting Up the iperf3 Server
Basic Server Setup
The foundation of any iperf3 test is establishing a server that listens for incoming client connections. The basic server command is straightforward:
```bash
iperf3 -s
```
When executed, this command produces output similar to:
```
-----------------------------------------------------------
Server listening on 5201
-----------------------------------------------------------
```
The server is now ready to accept client connections on the default port 5201.
Server Configuration Options
Custom Port Configuration
To run the server on a different port:
```bash
iperf3 -s -p 8080
```
This is useful when:
- Default port 5201 is blocked by firewalls
- Running multiple iperf3 servers on the same host
- Complying with organizational port policies
Binding to Specific Interfaces
By default, iperf3 binds to all available interfaces. To bind to a specific interface:
```bash
Bind to specific IP address
iperf3 -s -B 192.168.1.100
Bind to specific interface
iperf3 -s -B eth0
```
Running Server as Daemon
For production environments, run iperf3 server as a background daemon:
```bash
Linux/macOS
iperf3 -s -D
Alternative with nohup
nohup iperf3 -s > /dev/null 2>&1 &
```
Server with Authentication
For secure testing environments, enable authentication:
```bash
iperf3 -s --rsa-private-key-path server.key --authorized-users-path users.txt
```
Advanced Server Configuration
IPv6 Server Setup
To run an IPv6-only server:
```bash
iperf3 -s -6
```
For dual-stack (IPv4 and IPv6):
```bash
iperf3 -s -4 -6
```
Server Logging
Enable detailed server logging:
```bash
iperf3 -s --logfile /var/log/iperf3-server.log --forceflush
```
One-off Server Mode
For single-use testing, configure the server to exit after one client test:
```bash
iperf3 -s -1
```
Running iperf3 Client Tests
Basic Client Connection
Once your server is running, connect from a client system:
```bash
iperf3 -c
```
Example:
```bash
iperf3 -c 192.168.1.100
```
Understanding Client Output
A typical client test produces output like:
```
Connecting to host 192.168.1.100, port 5201
[ 5] local 192.168.1.101 port 54320 connected to 192.168.1.100 port 5201
[ ID] Interval Transfer Bitrate Retr Cwnd
[ 5] 0.00-1.00 sec 112 MBytes 941 Mbits/sec 0 408 KBytes
[ 5] 1.00-2.00 sec 110 MBytes 924 Mbits/sec 0 408 KBytes
[ 5] 2.00-3.00 sec 112 MBytes 941 Mbits/sec 0 408 KBytes
...
- - - - - - - - - - - - - - - - - - - - - - - - -
[ ID] Interval Transfer Bitrate Retr
[ 5] 0.00-10.00 sec 1.09 GBytes 937 Mbits/sec 0 sender
[ 5] 0.00-10.00 sec 1.09 GBytes 937 Mbits/sec receiver
```
Client Configuration Options
Test Duration
Specify custom test duration:
```bash
30-second test
iperf3 -c 192.168.1.100 -t 30
Transfer specific amount of data
iperf3 -c 192.168.1.100 -n 1G
```
Reverse Mode Testing
Test download speed (server sends to client):
```bash
iperf3 -c 192.168.1.100 -R
```
Bidirectional Testing
Test both upload and download simultaneously:
```bash
iperf3 -c 192.168.1.100 --bidir
```
Multiple Parallel Streams
Increase concurrent connections to test aggregate bandwidth:
```bash
4 parallel streams
iperf3 -c 192.168.1.100 -P 4
```
UDP Testing
By default, iperf3 uses TCP. For UDP testing:
```bash
Basic UDP test
iperf3 -c 192.168.1.100 -u
UDP with specific bandwidth target
iperf3 -c 192.168.1.100 -u -b 100M
UDP with packet loss reporting
iperf3 -c 192.168.1.100 -u -b 1G --enhanced
```
Advanced iperf3 Options and Parameters
Window Size and Buffer Tuning
Optimize performance by adjusting TCP window size and socket buffers:
```bash
Set TCP window size
iperf3 -c 192.168.1.100 -w 1M
Set socket buffer size
iperf3 -c 192.168.1.100 -l 128K
```
CPU Affinity and Performance Optimization
For high-performance testing, bind iperf3 to specific CPU cores:
```bash
Bind to CPU core 2
iperf3 -c 192.168.1.100 -A 2
Server with CPU affinity
iperf3 -s -A 1
```
Output Formatting and Reporting
JSON Output
Generate machine-readable JSON output for automation:
```bash
iperf3 -c 192.168.1.100 -J > results.json
```
Custom Reporting Intervals
Change the reporting interval:
```bash
Report every 5 seconds
iperf3 -c 192.168.1.100 -i 5
```
Bandwidth Format
Specify bandwidth display format:
```bash
Display in bits per second
iperf3 -c 192.168.1.100 --format bits
Display in Kbytes
iperf3 -c 192.168.1.100 --format K
```
Advanced Protocol Options
TCP Congestion Control
Test with specific TCP congestion algorithms:
```bash
Use BBR congestion control
iperf3 -c 192.168.1.100 -C bbr
Use CUBIC (default on many systems)
iperf3 -c 192.168.1.100 -C cubic
```
IPv6 Testing
Force IPv6 testing:
```bash
iperf3 -c 2001:db8::1 -6
```
DSCP Marking
Set DSCP (Differentiated Services Code Point) for QoS testing:
```bash
iperf3 -c 192.168.1.100 --dscp 46
```
Practical Examples and Use Cases
Example 1: Basic LAN Speed Test
Test bandwidth between two systems on a local network:
Server (192.168.1.100):
```bash
iperf3 -s
```
Client (192.168.1.101):
```bash
iperf3 -c 192.168.1.100 -t 60
```
This runs a 60-second TCP test to measure maximum throughput.
Example 2: WAN Connection Testing
Test internet connection speed through a remote server:
Remote Server:
```bash
iperf3 -s -p 443 # Use HTTPS port to bypass firewalls
```
Local Client:
```bash
Test upload speed
iperf3 -c remote-server.example.com -p 443 -t 30
Test download speed
iperf3 -c remote-server.example.com -p 443 -R -t 30
```
Example 3: Wi-Fi Performance Testing
Compare wired vs. wireless performance:
Wired Baseline Test:
```bash
iperf3 -c 192.168.1.100 -P 4 -t 30
```
Wireless Test:
```bash
iperf3 -c 192.168.1.100 -P 4 -t 30 --title "WiFi_Test"
```
Example 4: UDP Packet Loss Testing
Test UDP performance and packet loss:
Server:
```bash
iperf3 -s
```
Client:
```bash
Test with 100 Mbps UDP
iperf3 -c 192.168.1.100 -u -b 100M -t 30
Test with 1 Gbps UDP to find breaking point
iperf3 -c 192.168.1.100 -u -b 1G -t 30
```
Example 5: Automated Testing Script
Create a comprehensive testing script:
```bash
#!/bin/bash
SERVER="192.168.1.100"
RESULTS_DIR="/tmp/iperf3_results"
mkdir -p $RESULTS_DIR
echo "Starting comprehensive bandwidth tests..."
TCP Upload Test
echo "TCP Upload Test..."
iperf3 -c $SERVER -t 30 -J > "$RESULTS_DIR/tcp_upload.json"
TCP Download Test
echo "TCP Download Test..."
iperf3 -c $SERVER -R -t 30 -J > "$RESULTS_DIR/tcp_download.json"
UDP Test
echo "UDP Test..."
iperf3 -c $SERVER -u -b 1G -t 30 -J > "$RESULTS_DIR/udp_test.json"
Multiple Streams Test
echo "Multiple Streams Test..."
iperf3 -c $SERVER -P 8 -t 30 -J > "$RESULTS_DIR/multi_stream.json"
echo "Tests completed. Results saved to $RESULTS_DIR"
```
Example 6: QoS and Traffic Shaping Validation
Test Quality of Service implementations:
```bash
High priority traffic (DSCP EF - Expedited Forwarding)
iperf3 -c 192.168.1.100 --dscp 46 -t 30 --title "High_Priority"
Best effort traffic (DSCP 0)
iperf3 -c 192.168.1.100 --dscp 0 -t 30 --title "Best_Effort"
Bulk data traffic (DSCP AF11)
iperf3 -c 192.168.1.100 --dscp 10 -t 30 --title "Bulk_Data"
```
Interpreting Test Results
Understanding TCP Results
Key metrics in TCP test results:
- Transfer: Total amount of data transferred
- Bitrate: Average throughput in bits per second
- Retr: Number of TCP retransmissions (should be low)
- Cwnd: TCP congestion window size
Good TCP Results Indicators:
- Consistent bitrate throughout the test
- Zero or minimal retransmissions
- Stable congestion window size
Poor TCP Results Indicators:
- Fluctuating bitrate
- High retransmission count
- Constantly changing congestion window
Understanding UDP Results
UDP test results include additional metrics:
- Jitter: Variation in packet arrival times
- Lost/Total Datagrams: Packet loss statistics
- Out-of-Order: Packets received out of sequence
Sample UDP Output:
```
[ ID] Interval Transfer Bitrate Jitter Lost/Total Datagrams
[ 5] 0.00-10.00 sec 114 MBytes 95.4 Mbits/sec 0.015 ms 0/14596 (0%)
```
Performance Baselines
Establish performance baselines for different network types:
| Network Type | Expected Throughput | Acceptable Packet Loss |
|--------------|-------------------|----------------------|
| Gigabit Ethernet | 900+ Mbps | < 0.01% |
| Fast Ethernet | 90+ Mbps | < 0.01% |
| 802.11ac Wi-Fi | 200-600 Mbps | < 0.1% |
| 802.11n Wi-Fi | 50-200 Mbps | < 0.1% |
| Internet (Cable) | 80-90% of rated speed | < 0.1% |
Common Issues and Troubleshooting
Connection Issues
"Connection Refused" Error
Problem: Client cannot connect to server.
Solutions:
1. Verify server is running:
```bash
ps aux | grep iperf3
```
2. Check if port is listening:
```bash
netstat -tlnp | grep 5201
```
3. Test basic connectivity:
```bash
telnet server_ip 5201
```
4. Check firewall rules:
```bash
# Linux (iptables)
sudo iptables -L | grep 5201
# Linux (firewalld)
sudo firewall-cmd --list-ports
```
Firewall Configuration
Linux (iptables):
```bash
sudo iptables -A INPUT -p tcp --dport 5201 -j ACCEPT
sudo iptables -A INPUT -p udp --dport 5201 -j ACCEPT
```
Linux (firewalld):
```bash
sudo firewall-cmd --permanent --add-port=5201/tcp
sudo firewall-cmd --permanent --add-port=5201/udp
sudo firewall-cmd --reload
```
Windows:
```powershell
New-NetFirewallRule -DisplayName "iperf3" -Direction Inbound -Protocol TCP -LocalPort 5201 -Action Allow
New-NetFirewallRule -DisplayName "iperf3 UDP" -Direction Inbound -Protocol UDP -LocalPort 5201 -Action Allow
```
Performance Issues
Lower Than Expected Throughput
Potential Causes and Solutions:
1. CPU Limitations:
```bash
# Monitor CPU usage during test
top -p $(pgrep iperf3)
# Use CPU affinity
iperf3 -c server -A 2
```
2. Network Interface Limitations:
```bash
# Check interface statistics
ethtool eth0
# Verify link speed
cat /sys/class/net/eth0/speed
```
3. Buffer Size Issues:
```bash
# Increase socket buffer
iperf3 -c server -w 2M
# Check system buffer limits
cat /proc/sys/net/core/rmem_max
cat /proc/sys/net/core/wmem_max
```
4. Multiple Streams:
```bash
# Use parallel streams
iperf3 -c server -P 4
```
High Packet Loss in UDP Tests
Troubleshooting Steps:
1. Reduce Test Bandwidth:
```bash
iperf3 -c server -u -b 100M
```
2. Increase Buffer Size:
```bash
iperf3 -c server -u -b 500M -l 1472
```
3. Check System Buffer Settings:
```bash
# Increase UDP buffer sizes
sudo sysctl -w net.core.rmem_max=134217728
sudo sysctl -w net.core.wmem_max=134217728
```
System-Specific Issues
macOS Performance Issues
macOS may have lower performance due to system limitations:
```bash
Increase socket buffer size
iperf3 -c server -w 1M
Use multiple streams
iperf3 -c server -P 8
```
Windows Performance Optimization
```powershell
Disable Windows Auto-Tuning (if problematic)
netsh int tcp set global autotuninglevel=disabled
Check TCP settings
netsh int tcp show global
```
Linux Kernel Tuning
For high-performance testing:
```bash
Increase network buffers
echo 'net.core.rmem_max = 134217728' >> /etc/sysctl.conf
echo 'net.core.wmem_max = 134217728' >> /etc/sysctl.conf
echo 'net.ipv4.tcp_rmem = 4096 65536 134217728' >> /etc/sysctl.conf
echo 'net.ipv4.tcp_wmem = 4096 65536 134217728' >> /etc/sysctl.conf
Apply settings
sudo sysctl -p
```
Best Practices and Professional Tips
Testing Methodology
Establish Baseline Performance
Before troubleshooting network issues:
1. Document Normal Performance:
```bash
# Create baseline test
iperf3 -c server -t 60 -J > baseline_$(date +%Y%m%d).json
```
2. Test Multiple Times:
```bash
# Run multiple tests and average results
for i in {1..5}; do
iperf3 -c server -t 30 --title "Test_$i"
sleep 10
done
```
3. Test Different Times:
- Peak hours vs. off-peak hours
- Different days of the week
- Various network load conditions
Comprehensive Testing Strategy
1. Layer Testing:
- Physical layer (cable testing)
- Network layer (ping, traceroute)
- Transport layer (iperf3)
- Application layer (real application testing)
2. Direction Testing:
```bash
# Upload test
iperf3 -c server -t 30
# Download test
iperf3 -c server -R -t 30
# Bidirectional test
iperf3 -c server --bidir -t 30
```
3. Protocol Testing:
```bash
# TCP performance
iperf3 -c server -t 30
# UDP performance and packet loss
iperf3 -c server -u -b 1G -t 30
```
Production Environment Considerations
Security Best Practices
1. Use Non-Standard Ports:
```bash
iperf3 -s -p 8080
```
2. Implement Access Controls:
```bash
# Bind to specific interface
iperf3 -s -B 192.168.1.100
```
3. Use Authentication:
```bash
iperf3 -s --rsa-private-key-path /etc/iperf3/server.key
```
4. Limit Test Duration:
```bash
# Client-side timeout
timeout 300 iperf3 -c server
```
Automation and Monitoring
1. Automated Testing Scripts:
```bash
#!/bin/bash
# Network monitoring script
SERVER="monitoring-server.local"
ALERT_THRESHOLD=800 # Mbps
RESULT=$(iperf3 -c $SERVER -t 10 -J)
BANDWIDTH=$(echo $RESULT | jq '.end.sum_sent.bits_per_second')
BANDWIDTH_MBPS=$((BANDWIDTH / 1000000))
if [ $BANDWIDTH_MBPS -lt $ALERT_THRESHOLD ]; then
echo "ALERT: Bandwidth below threshold: ${BANDWIDTH_MBPS}Mbps" | \
mail -s "Network Performance Alert" admin@company.com
fi
```
2. Integration with Monitoring Systems:
```bash
# Output for Nagios/Icinga
iperf3 -c server -t 10 -J | jq '.end.sum_sent.bits_per_second'
# Output for Zabbix
iperf3 -c server -t 10 | grep "sender" | awk '{print $7}'
```
Performance Optimization Tips
Client-Side Optimization
1. Use Appropriate Test Duration:
- Short tests (10s): Quick checks
- Medium tests (30s): Standard testing
- Long tests (60s+): Detailed analysis
2. Optimize Parallel Streams:
```bash
# Start with single stream
iperf3 -c server -t 30
# Increase streams if single stream is CPU-limited
iperf3 -c server -P 4 -t 30
```
3. CPU Affinity for High-Speed Networks:
```bash
# Bind to specific CPU core
iperf3 -c server -A 2 -t 30
```
Server-Side Optimization
1. Dedicated Testing Server:
- Use dedicated hardware for testing
- Minimize other network services
- Optimize system for network performance
2. Multiple Server Instances:
```bash
# Run multiple servers on different ports
iperf3 -s -p 5201 -D
iperf3 -s -p 5202 -D
iperf3 -s -p 5203 -D
```
Security Considerations
Network Security
Firewall Configuration
When implementing iperf3 in production environments, carefully configure firewalls:
1. Restrict Source IPs:
```bash
# iptables example
sudo iptables -A INPUT -p tcp --dport 5201 -s 192.168.1.0/24 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 5201 -j DROP
```
2. Use VPN for Remote Testing:
- Establish VPN tunnel before testing
- Use private IP addresses within VPN
Authentication and Authorization
1. RSA Key Authentication:
```bash
# Generate RSA key pair
openssl genrsa -out server.key 2048
openssl rsa -in server.key -pubout -out server.pub
# Server with authentication
iperf3 -s --rsa-private-key-path server.key
# Client with authentication
iperf3 -c server --rsa-public-key-path server.pub
```
2. User Management:
Create authorized users file:
```
# /etc/iperf3/users.txt
user1,password1
user2,password2
```
Operational Security
Monitoring and Logging
1. Enable Detailed Logging:
```bash
iperf3 -s --logfile /var/log/iperf3.log --forceflush
```
2. Monitor for Abuse:
```bash
# Watch for excessive connections
netstat -an | grep :5201 | wc -l
# Monitor bandwidth usage
iftop -i eth0
```
Resource Protection
1. Limit Test Duration:
```bash
# Use timeout to prevent long-running tests
timeout 300 iperf3 -s -1
```
2. Process Monitoring:
```bash
# Monitor iperf3 resource usage
ps aux | grep iperf3
top -p $(pgrep iperf3)
```
Conclusion
iperf3 is an indispensable tool for network administrators, engineers, and anyone responsible for network performance. This comprehensive guide has covered everything from basic server-client setup using `iperf3 -s` and `iperf3 -c ` to advanced testing scenarios, troubleshooting, and security considerations.
Key Takeaways
1. Versatile Testing Capability: iperf3 supports TCP, UDP, and SCTP protocols with IPv4 and IPv6, making it suitable for diverse network testing scenarios.
2. Simple Yet Powerful: The basic commands are straightforward, but the tool offers extensive options for advanced testing requirements.
3. Cross-Platform Compatibility: Available on all major operating systems, ensuring consistent testing across heterogeneous environments.
4. Professional Features: JSON output, authentication, and advanced reporting make it suitable for enterprise environments.
5. Troubleshooting Essential: Understanding common issues and their solutions is crucial for reliable network testing.
Next Steps
To further enhance your network testing capabilities:
1. Practice Regularly: Set up test environments and practice different scenarios
2. Automate Testing: Create scripts for regular network monitoring
3. Integrate with Monitoring: Connect iperf3 results to your network monitoring systems
4. Stay Updated: Keep iperf3 updated to benefit from latest features and bug fixes
5. Document Results: Maintain historical performance data for trend analysis
Advanced Learning
Consider exploring these related topics:
- Network Performance Tuning: Optimize TCP/IP stack parameters
- Quality of Service (QoS): Implement and test traffic prioritization
- Network Monitoring Tools: Integrate iperf3 with tools like Nagios, Zabbix, or PRTG
- High-Performance Networking: Explore technologies like DPDK and SR-IOV
- Network Automation: Use tools like Ansible or Python to automate testing workflows
By mastering iperf3, you've gained a powerful ally in maintaining and optimizing network performance. Whether you're troubleshooting connectivity issues, validating network upgrades, or ensuring service level agreements are met, the skills and knowledge gained from this guide will serve you well in your networking endeavors.
Remember that network testing is both an art and a science. While iperf3 provides the technical measurements, interpreting results and making informed decisions requires experience and understanding of your specific network environment. Continue practicing, stay curious, and always validate your findings with multiple testing approaches.