stamp-suite

stamp-suite measures round-trip time, loss, one-way delay and residual bit errors using STAMP (RFC 8762 and RFC 8972). One binary sends test packets and reports results, or reflects them with --is-reflector.

New to STAMP? Read the protocol overview first.

Quick start

stamp-suite -h shows everyday options and examples. Use stamp-suite --help or man stamp-suite for the complete option reference.

Start a reflector. It listens on UDP port 862, which on Linux needs root or CAP_NET_BIND_SERVICE:

sudo stamp-suite --is-reflector

From another host, send 100 test packets 100 ms apart and print each result:

stamp-suite --remote-addr 192.0.2.20 --count 100 --send-delay 100ms -R

Without root, run the reflector on a high port and point the sender at it:

stamp-suite --is-reflector --local-port 8620
stamp-suite --remote-addr 192.0.2.20 --remote-port 8620

The sender prints a summary when it finishes or when you press Ctrl-C. A few more examples:

# Measure two reflectors at once; each report carries a target label
stamp-suite --remote-addr 192.0.2.20,198.51.100.7 --count 0 --duration 60

# 4000 packets per second, Poisson-spaced, JSON lines on stdout
stamp-suite --remote-addr 192.0.2.20 --send-delay 250us --send-schedule poisson \
  --count 0 --duration 600 --output-format json > results.jsonl

For repeated runs, use a TOML file and override individual values on the CLI. The sender and reflector examples work together on loopback port 8620:

# Run these in separate terminals from the checkout
stamp-suite --config examples/reflector.toml
stamp-suite --config examples/sender.toml --count 20

Installed DEB/RPM packages keep these files in /usr/share/doc/stamp-suite/examples/; binary archives include an examples/ directory. See configuration files for service settings, session provisioning and policies.

The reflector starts in open mode and answers anyone who can reach it. On an untrusted network, restrict access and turn on authenticated mode.

What it supports

• Round-trip time, loss, and forward and reverse one-way delay. One-way delay needs synchronized clocks; see Timestamps and clocks.
• Open and authenticated (HMAC) modes, stateless and stateful reflection, and RFC 8972 TLVs.
• RFC 9503 return-path control, RFC 9534 Micro-session IDs, and RFC 10052 reflected test packet control.
• Draft extensions for reflected IP headers, CoS/ECN response and residual bit error rate. Their experimental codepoints need agreement with the peer.
• Text, JSON lines and CSV output. Optional Prometheus metrics, SNMP AgentX sub-agent and reflector control API.

The conformance matrices list what is supported for each RFC and draft, and what is not.

Installation

Release packages

Each GitHub release has DEB and RPM packages for Linux x86_64 and aarch64, built with all Cargo features. They install /usr/bin/stamp-suite, the man page, the SNMP MIB, a systemd unit and the stamp service account.

sudo apt install ./stamp-suite_*_amd64.deb    # Debian, Ubuntu
sudo dnf install ./stamp-suite-*.x86_64.rpm   # Fedora, RHEL
sudo systemctl enable --now stamp-suite

The packaged service runs a reflector in open mode. Configure authentication before exposing it to an untrusted network; see security.

The release workflow builds plain binary tarballs for these Linux targets and for macOS on Apple silicon and Intel, plus a Windows x64 ZIP, source and cargo vendor tarballs.

From source

Rust 1.87 or newer is required. Debian trixie source builds need a newer compiler than the stock Rust 1.85 package. Prebuilt packages need no compiler.

cargo install stamp-suite                       # from crates.io
cargo build --release --features metrics,control,hwtstamp   # from a checkout

Building on Windows needs the Npcap SDK; running needs Npcap. The Windows release includes metrics and the control API; SNMP and kernel timestamps are Unix-only. Windows builds reserve 4 MiB for the main thread stack.

Nix, Gentoo and OpenWrt

nix build
nix run . -- --is-reflector

The Gentoo overlay maps Cargo features to USE flags and installs systemd and OpenRC services. dist/openwrt/ holds an OpenWrt recipe template and procd init script. Use the release asset stamp-suite-VERSION-openwrt.mk as its Makefile; it pins the checksum of that release’s source archive. See release verification for building the recipe from local release inputs.

Platforms and Cargo features

Platform	Receiver backend	Requirements
Linux	nix UDP socket	No raw-socket privilege; ports below 1024 need CAP_NET_BIND_SERVICE
macOS	nix UDP socket	No raw-socket privilege
Windows	pnet capture	Npcap

The backend is chosen at build time. Both backends read the received TTL or Hop Limit. On Linux the nix backend reflects IPv6 extension headers; reflecting fixed IP headers needs the pnet backend. Header disclosure requires explicit sender-IP permission using --reflect-ipv6-ext-header-from or --reflect-fixed-header-from. See header reflection.

No Cargo feature is on by default.

Cargo feature	Effect
ttl-pnet	Uses the pnet capture backend on Linux and macOS. On Linux it needs CAP_NET_RAW or root.
ttl-nix	Matters only together with ttl-pnet: it keeps the nix backend, as --all-features does. Linux and macOS use nix without it.
metrics	Adds --metrics, a Prometheus endpoint at http://127.0.0.1:9090/metrics by default.
control	Adds --control, the reflector's HTTP API for keys, sessions, limits, drain and shutdown, with optional HTTPS.
snmp	Adds --snmp, a read-only AgentX sub-agent (Unix only) for mibs/STAMP-SUITE-MIB.mib.
hwtstamp	Uses kernel timestamps (Linux receive and transmit, macOS receive) and, with --hwtstamp on, Linux NIC hardware timestamps.

--metrics, --control and --snmp fail at startup when the binary was built without the feature.

Documentation

Document	Contents
Protocol overview	STAMP concepts, the extensions implemented here, glossary
Project review, 2026-10-03	Conformance findings, test assessment and file-by-file optimization notes
Usage	Configuration file, sender, reflector, timestamps, networking, observability
Security	Threat model, HMAC keys and rotation, service hardening
Control API	Reflector HTTP API endpoints
Measurements	What each reported value means and its limits
Statistics	Quantile precision and retention
Architecture	Modules, receiver backends, packet processing, TLV reference
Conformance	Per-clause evidence for each RFC and draft
Benchmarks	Throughput and CPU measurements
Release verification	Platform and integration checks run before a release
Contributing	Building, testing, linting and submitting changes
Vulnerability reporting	How to report a security problem
Changelog	Changes in each release

The man page (man stamp-suite) lists every option. stamp-suite --help prints the same list.

Versioning

The 1.x compatibility promise covers CLI behavior, the TOML configuration schema and default wire behavior. The Rust library API is internal and may change in any release. Minor releases may renumber experimental codepoints or raise the minimum Rust version; CHANGELOG.md records each such change.

Contributing

See CONTRIBUTING.md. Open an issue before starting a large change.

Authors and license

Maintained by Piotr Olszewski, with contributors. Licensed under the MIT license. Binary distributions include generated dependency copyright notices and license texts in THIRD_PARTY_NOTICES.txt. See release verification.