Iperf3 uses the
-w flag to set the TCP window size for the socket, not the operating system kernel buffer limits. Specifying an appropriate window size is critical for high-bandwidth, high-latency networks because it allows more data to be in flight before requiring an acknowledgment. Without this adjustment, throughput often remains artificially low due to insufficient buffering capacity on the client or server side.
Why Window Size Matters in Iperf3
The primary reason network throughput falls short of theoretical maximums is often the TCP window size. In standard networking, the sender can transmit a certain amount of data before needing an acknowledgement from the receiver. This amount is defined by the window size. If the window size is too small relative to the bandwidth-delay product (BDP) of the network path, the connection will stall frequently waiting for acknowledgements, leading to poor performance.
When you run Iperf3 without specifying the window size, it defaults to a value determined by the underlying operating system. On many systems, this default might be 64KB or 128KB, which is sufficient for local area networks but disastrous for wide area networks or high-speed links with significant latency. The
-w option explicitly sets this parameter, allowing you to optimize the socket behavior for your specific test environment.
It is important to distinguish between the Iperf3 socket window and OS-level buffer limits. While
-w tells the application what window size to request via the
setsockopt system call, the operating system may still enforce its own upper limits on socket buffers. If the OS limit is lower than the requested window size, the actual effective window will be capped at the OS limit. Therefore, while
-w is essential, it is not the only factor influencing final throughput.
How to Use the -w Flag Correctly
To specify the window size in Iperf3, use the
-w flag followed by the desired size. The size can be specified in bytes, kilobytes (K), megabytes (M), or gigabytes (G). For example, to set a window size of 1 megabyte, you would use
-w 1M.
On the server side, you start the Iperf3 daemon with the following command:
iperf3 -s -w 1M
On the client side, you must also specify the same window size to ensure both ends are negotiating correctly. Running the client with:
iperf3 -c [server_ip] -w 1M
If you omit the
-w flag on either side, Iperf3 will attempt to use the default system setting. In high-performance testing scenarios, it is best practice to explicitly define this on both ends to avoid ambiguity and ensure consistent results. Mismatched window sizes can lead to suboptimal performance where one side is constrained by a smaller buffer than the other.
Calculating the Optimal Window Size
Determining the right window size involves understanding the Bandwidth-Delay Product (BDP). The BDP represents the amount of data that can be in transit on the network link at any given time. It is calculated as:
BDP = Bandwidth × Round-Trip Time (RTT)
For instance, if you have a 1 Gbps link with a 50ms RTT, the BDP is approximately 6.25 MB. Setting the window size slightly above this value ensures the pipe stays full. However, setting it excessively high does not provide additional benefits and may consume unnecessary memory resources.
A common approach is to start with a reasonable default like 1M or 2M and observe the throughput. If the throughput is limited by latency rather than bandwidth, increasing the window size further may help. Conversely, if the throughput plateaus despite increasing the window size, other factors such as CPU limitations, NIC offloading features, or OS kernel buffer limits are likely the bottleneck.
Troubleshooting Common Issues
Even with the correct
-w setting, users may encounter issues where the window size appears ignored or throughput remains low. One common issue is that the operating system rejects the requested socket buffer size because it exceeds system-defined limits. On Linux, these limits are controlled by parameters such as
net.core.rmem_max and
net.core.wmem_max. If the Iperf3 request exceeds these values, the kernel will clamp the window size to the maximum allowed.
Another potential problem is firewall interference. Some firewalls may drop packets or alter TCP flags in ways that disrupt large window negotiations. Ensure that no intermediate network devices are interfering with the TCP handshake or data transmission. Additionally, verify that both the client and server are running compatible versions of Iperf3 to avoid protocol mismatches.
Understanding 'Connection' and 'Session' in Networking is crucial when interpreting these results, as a single session may involve multiple TCP connections depending on the test configuration. For more complex network setups, such as those involving virtual machines or nested routers, refer to guides on
Understanding 'Connection' and 'Session' in Networking to better diagnose where bottlenecks occur.
Best Practices for Network Testing
Always run Iperf3 tests multiple times to account for variability. Network conditions can fluctuate, and a single run may not represent typical performance. Use the
-t flag to extend the test duration, providing a more stable average. Combine this with explicit window sizing using
-w to isolate TCP layer performance from other variables.
Remember that Iperf3 measures transport-layer throughput. It does not account for application-layer overheads or file system I/O speeds. For end-to-end application performance, consider complementing Iperf3 tests with real-world application benchmarks. Understanding how different network segments interact, such as when
Combining Two Networks into One Network on Huawei EG8145V5 Router, can also provide context for why certain bottlenecks appear in isolated Iperf3 tests.
Frequently Asked Questions
Does -w change the OS kernel buffer size?
No, the
-w flag only requests a specific window size for the TCP socket via socket options. It does not modify the operating system's global kernel buffer limits, which are separate system parameters that may cap the effective window size.
What happens if I set -w higher than the OS max?
If the requested window size exceeds the OS-defined maximum socket buffer limits, the kernel will typically clamp the value down to the maximum allowed. You should check your system's
net.core.wmem_max settings to determine the true upper bound.
Can Iperf3 test UDP with a window size?
No, the
-w flag is specific to TCP connections. UDP is connectionless and does not use TCP windows or acknowledgements, so window size adjustments do not apply to UDP traffic tests.
Why is my throughput still low after setting -w?
Low throughput despite adequate window sizing usually indicates other bottlenecks such as CPU saturation, NIC offloading issues, or physical layer limitations. Check system resource usage and verify that no firewalls are dropping packets.
Should I use the same -w value on client and server?
Yes, it is best practice to specify the same window size on both ends. While TCP negotiation handles mismatches, explicit configuration ensures predictable behavior and avoids reliance on potentially inconsistent default system settings.