Skip to main content
emisar

iperf3 network throughput

v0.1.1

Active network throughput measurement with iperf3 — TCP bandwidth and UDP jitter / packet loss — between two nodes in the fleet. Run the one-shot server on one runner, then probe it with the client from another. Use to answer "what is the real bandwidth (or loss) between these two hosts?"

4 allowed by default
Pack ID
iperf3
Vendor
emisar
OS
linux
Actions
4
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
iperf3

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host 
sudo emisar pack install iperf3 --hash sha256:7797e9b78d987a5dd3876fb63515a2ee4592789309ec17efa96a0c2522133bad

Setup

Needs no host-side credentials — just iperf3 on PATH and a network path between the two runners. Start iperf3.server on one node, then run iperf3.client / iperf3.udp on another node pointed at it. The server is one-shot: it serves a single test and exits, so nothing is left listening.

Notes

  • Run iperf3.server on the target first (it listens for up to idle_timeout seconds); one server handles both TCP and UDP clients. Dispatch it async (wait=false), then run the client within that window.
  • If no server is listening, the client's control connection is refused and the test fails fast.
  • Throughput tests generate sustained traffic at up to line rate for the test duration — keep duration short and cap it with bitrate on shared or production paths.
  • Every iperf3 action is medium-risk (policy-gated): the server opens a transient inbound port and the client/udp probes push sustained, link-saturating traffic. iperf3 changes no host state — it only moves test traffic — but that network blast radius is why the whole pack is gated.

Verify it works

Runs iperf3.version, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host 
sudo emisar pack verify iperf3

Install and configure a pack walks through the whole sequence on a host.

Actions 4 total

View on GitHub
  • iperf3.client exec medium Medium — changes state, easily reversible

    iperf3 TCP throughput test

    Measure TCP throughput to a target host running an iperf3 server (`iperf3 -s`). Reports bits/sec, retransmits, and per-stream detail as JSON. Use to answer "what is the real bandwidth between these two hosts?" — e.g. diagnosing slow replication, backups, or a suspect link. Set reverse=true to measure the download direction (server → runner). The target MUST already be running an iperf3 server; the test generates sustained traffic for `duration` seconds and can saturate a shared link, so cap it with `bitrate` and keep `duration` short on production paths.

    View source on GitHub
  • iperf3.server exec medium Medium — changes state, easily reversible

    iperf3 one-shot server

    Run a one-shot iperf3 server: listen on a port, accept a single throughput test from one client, print the server-side result as JSON, and exit. Pair it with iperf3.client / iperf3.udp on another node — start the server here, then run the client there within the listen window. One server handles both TCP and UDP clients. It self-terminates after idle_timeout seconds if no client connects (and is bounded by the action timeout), so it never leaves a lingering daemon or open port. Optionally restrict the listener to a single interface with `bind`.

    View source on GitHub
  • iperf3.udp exec medium Medium — changes state, easily reversible

    iperf3 UDP jitter + loss test

    Measure UDP throughput, jitter, and packet loss to a target host running an iperf3 server (`iperf3 -s`). Sends a UDP stream at the target `bitrate` and reports jitter (ms) and lost-packet percentage as JSON. Use to check a path for loss or jitter (VoIP, video, real-time links) or to probe how much a link drops at a given rate. Set reverse=true to test the download direction (server → runner). The target MUST already be running an iperf3 server; generates sustained UDP traffic for `duration` seconds.

    View source on GitHub
  • iperf3.version exec medium Medium — changes state, easily reversible

    iperf3 version + build info

    Show the installed iperf3 version and build info (cJSON / OpenSSL). Read-only local check with no network — use it to confirm the runner actually has iperf3 before dispatching a throughput test.

    View source on GitHub
← Back to registry
Pack reference  Publish your own