Configuration reference¶

For aggregate rate targets, explicit units, plan estimates, and capability inspection, see rate intent and capabilities. ClientConfig.rate remains the low-level per-stream bits/s setting. The native option inventory maps every supported-version CLI flag to a Python facility or an explicit application concern; the control recipes show practical combinations.

Since 0.3.0, ClientConfig is a mutable standard-library dataclass. Its constructor validates types, bounds, and option combinations. Pydantic APIs such as model_validate() and model_dump() are not provided.

from dataclasses import asdict, replace

from iperf3_lib import ClientConfig, Protocol

config = ClientConfig(server="127.0.0.1", protocol=Protocol.TCP, duration=5)
reverse_config = replace(config, reverse=True)
print(asdict(config))

Use a fresh instance or dataclasses.replace() when changing a validated configuration. Direct attribute assignment does not rerun validation, and a Client retains the configuration object passed to it. Each run() validates and executes a detached snapshot at admission, so later mutations cannot change an active run. The result records that request separately from settings verified through native output.

Client fields¶

Integer fields reject booleans, floats, and numeric strings. Boolean options require actual bool values. Interval fields explicitly accept finite numbers. An invalid type raises TypeError; an out-of-range value or invalid combination raises ValueError. reverse=True with bidirectional=True is invalid.

The server annotation remains str, although runtime construction also accepts standard-library IP address objects. Passing str(address) is compatible with both the runtime and that static annotation. The constructor does not validate whether a hostname is reachable.

Local endpoints and TCP¶

All optional fields below default to None, except address_family="auto" and no_delay=False.

mptcp and congestion_control require TCP; no_delay and mss accept TCP or SCTP. A configured algorithm or device must also exist on the executing host. Strings are validated before crossing the native boundary; this does not establish reachability, permissions, or kernel support.

Termination, intervals and pacing¶

These optional fields default to None.

Exactly one of duration, bytes, and blocks selects termination. Native count termination is not an exact final-byte guarantee, nor a duration estimate. Count-based and unlimited runs have unknown active-time/payload estimates; finite estimate caps reject unknown totals. Finite trial plans reject duration=0. Count-based trials require uncapped estimate budgets, while sweeps retain their finite active-time requirement.

Protocol, payload and host settings¶

Boolean fields default to False; other fields default to None, except the empty tuple default for sctp_bind_addresses.

UDP-specific fields require UDP; SCTP association fields require SCTP. dont_fragment rejects IPv6 and changes automatic family selection to IPv4. payload_file and repeating_payload cannot be combined. Host-specific options still require native build, operating-system and peer support. Choosing a CPU or file happens inside the worker but refers to resources on the executing host.

Connection lifetime and authentication¶

These fields default to None, except use_pkcs1_padding=False.

Pass the password separately to Client(config, password=...) or use IPERF3_PASSWORD. Passwords are absent from configuration snapshots and artifacts. Username and key path remain request metadata; key contents are not retained. Native authentication requires an appropriate libiperf/OpenSSL build. The tested 3.19.1/OpenSSL 3 build rejects valid credentials due to a native authentication limitation; authenticated operation is qualified with libiperf 3.21.

These native timers do not replace Client.run(timeout=...). The execution timeout selects the isolated worker, includes startup, and terminates/reaps that process before raising TimeoutError; it does not claim that C finalizers ran. The watchdog stops the worker independently of a blocked Python callback, but returning control to the caller still waits for that callback to return.

Protocol defaults¶

ClientConfig.rate retains the native per-stream bitrate meaning. Aggregate targets and explicit unit strings use the separate RateIntent and parse_rate() APIs; estimate_plan() checks sequential admission budgets. See rate intent and capabilities. These estimates do not impose a hard deadline on a blocking native call.

Server configuration¶

Import ServerConfig from iperf3_lib or iperf3_lib.server_config and pass it as Server(config=ServerConfig(...)). The server detaches that configuration, then validates and snapshots it again at admission. All server calls use an isolated Python/libiperf worker.

Server(port=5201, bind_host=None) and its positional form remain available. Do not combine config with explicitly supplied port or bind_host, even when the values match. .port and .bind_host remain validated mutable aliases for config.port and config.bind_address.

Strings must be nonempty and NUL-free. Integer options reject booleans and numeric coercion. When keepalive idle is nonzero, it must exceed interval times count. An active nonzero bitrate limit requires periodic statistics.

The server guide describes returned results, callbacks, serving sessions and shutdown. A native idle policy, a maximum client duration, and a whole-session worker timeout are different controls.