# udpstp

> udpstp is a Rust implementation of UDPSTP, the UDP Speed Test Protocol (RFC 9946). It measures the Maximum IP-Layer Capacity of a network path (RFC 9097): a Client and a Server exchange Load PDUs and Status PDUs over UDP, and the Server raises or lowers the sending rate until it finds the highest rate the path delivers.

Source revision for version 0.1.2. Install the latest published release from https://udpstp.com/getting-started.html or build this revision from source (https://github.com/pederbe/udpstp). 348 of its 420 RFC Requirements are proven by tests; the conformance pages list each one. It interoperates with OB-UDPST, the Broadband Forum's C implementation. Terms are used as the glossary defines them. Created by Peder Bergan (https://pederbe.dev). Every page below is Markdown; llms-full.txt holds them all in one file.

## Docs

- [Getting started](https://udpstp.com/getting-started.md): udpstp measures how much traffic a network path can carry, in Mbps. Put a Client and a Server at the two ends of the path, share a key, and run your first Test.

## Guides

- [Overview](https://udpstp.com/guides/index.md): Start with Getting started for your first authenticated Test, then use these guides for the task at hand. Each guide gives the steps, and links to the…
- [Installing udpstp](https://udpstp.com/guides/installing-udpstp.md): Install udpstp on both Test hosts. Choose your platform below, then follow Getting started to share a key and run a Test.
- [Running a Test](https://udpstp.com/guides/running-a-test.md): For Client users: Operators, measurement platforms, and anyone who runs udpstp client against a UDPSTP Server. Understanding the results explains what the…
- [Hosting a Server](https://udpstp.com/guides/hosting-a-server.md): For Server administrators: the steps to set up, open, limit and run udpstp server. Server configuration lists every setting, Server log every event, and the…
- [udpstp on Windows](https://udpstp.com/guides/windows.md): The Windows steps for both roles: a private key file, the firewall, a trial Server in a window, and the Windows service. Use it alongside Running a Test and…
- [Operator features](https://udpstp.com/guides/operator-features.md): For Operators measuring within their own networks, and for the Server administrators who give them Operator Keys.
- [Building from source](https://udpstp.com/guides/building-udpstp.md): Build udpstp from source to develop it, try changes on main, or use a platform without a release binary. To install a published release, see Installing udpstp.

## Explanations

- [Understanding the results](https://udpstp.com/understanding-results.md): What udpstp measures, what each line of its results means, and why a Test can fall short of a path's real capacity. Running a Test has the steps.
- [Security model](https://udpstp.com/security.md): This document describes what udpstp protects, from whom, and how. It is written for Server administrators and Operators deciding whether to deploy udpstp, and…

## Reference

- [Stable interfaces](https://udpstp.com/reference/interfaces.md): What you can build on from udpstp 0.1.0, and how it changes. The command line, the Server's settings and its JSON log settle during 0.x and become stable at…
- [Command line](https://udpstp.com/reference/cli.md): Every option of udpstp client and udpstp server, generated from the binary's own --help output when the site was built. udpstp client --help and udpstp server…
- [Server configuration](https://udpstp.com/reference/configuration.md): The Server reads its settings from built-in defaults, then a TOML file (udpstp server --config FILE), then the command line, each replacing the one before…
- [Server log](https://udpstp.com/reference/server-log.md): The Server logs one line per event: what it admitted, refused and measured. This page lists every event, field and reason. Hosting a Server shows how to set…
- [JSON results](https://udpstp.com/reference/json-output.md): udpstp client --format json prints the Test's results as JSON compatible with OB-UDPST v9.1.0's client output: the same keys, in the same order, with numbers…
- [Exit statuses](https://udpstp.com/reference/exit-statuses.md): udpstp client exits with the ErrorStatus that OB-UDPST reports, except that a Test that completed with only warnings exits 0. In JSON results the same number…
- [Key files](https://udpstp.com/reference/key-files.md): Both the Client and the Server read Shared Keys from a key file, never from the command line. A file whose name ends in .toml is a TOML Key Table. Any other…
- [Platform differences](https://udpstp.com/reference/platforms.md): udpstp runs on Linux, macOS and Windows. A few features depend on what the operating system offers. Installing udpstp lists the release binaries.
- [Glossary](https://udpstp.com/glossary.md): Press Ctrl+F (Command+F on macOS) to find a term on this page.

## Conformance

- [Conformance](https://udpstp.com/conformance/index.md): Every normative statement of RFC 9946, and of the RFC 9097 sections it uses, is a Requirement with a stable ID: 420 in all. A Requirement counts as met when a…
- [RFC 9097 §2: Scope, Goals, and Applicability](https://udpstp.com/conformance/rfc9097-02.md): The 6 Requirements of RFC 9097 §2, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9097 §4: General Parameters and Definitions](https://udpstp.com/conformance/rfc9097-04.md): The 9 Requirements of RFC 9097 §4, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9097 §5: IP-Layer Capacity Singleton Metric Definitions](https://udpstp.com/conformance/rfc9097-05.md): The 17 Requirements of RFC 9097 §5, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9097 §6: Maximum IP-Layer Capacity Metric Definitions (Statistics)](https://udpstp.com/conformance/rfc9097-06.md): The 18 Requirements of RFC 9097 §6, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9097 §7: IP-Layer Sender Bit Rate Singleton Metric Definitions](https://udpstp.com/conformance/rfc9097-07.md): The 10 Requirements of RFC 9097 §7, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9097 §8: Method of Measurement](https://udpstp.com/conformance/rfc9097-08.md): The 49 Requirements of RFC 9097 §8, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9097 §9: Reporting Formats](https://udpstp.com/conformance/rfc9097-09.md): The 15 Requirements of RFC 9097 §9, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9097 §10: Security Considerations](https://udpstp.com/conformance/rfc9097-10.md): The 7 Requirements of RFC 9097 §10, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9946 §2: Conventions and Terminology](https://udpstp.com/conformance/rfc9946-02.md): The 1 Requirements of RFC 9946 §2, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9946 §3: Scope, Goals, and Applicability](https://udpstp.com/conformance/rfc9946-03.md): The 1 Requirements of RFC 9946 §3, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9946 §4: Protocol Overview](https://udpstp.com/conformance/rfc9946-04.md): The 15 Requirements of RFC 9946 §4, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9946 §5: Requirements, Security Operations, and Optional Checksum](https://udpstp.com/conformance/rfc9946-05.md): The 73 Requirements of RFC 9946 §5, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9946 §6: Test Setup Request and Response](https://udpstp.com/conformance/rfc9946-06.md): The 60 Requirements of RFC 9946 §6, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9946 §7: Test Activation Request and Response](https://udpstp.com/conformance/rfc9946-07.md): The 44 Requirements of RFC 9946 §7, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9946 §8: Test Load Stream Transmission and Measurement Status Feedback Messages](https://udpstp.com/conformance/rfc9946-08.md): The 57 Requirements of RFC 9946 §8, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9946 §9: Stopping a Test](https://udpstp.com/conformance/rfc9946-09.md): The 12 Requirements of RFC 9946 §9, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9946 §10: Operational Considerations for the Measurement Method](https://udpstp.com/conformance/rfc9946-10.md): The 5 Requirements of RFC 9946 §10, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9946 §11: Security Considerations](https://udpstp.com/conformance/rfc9946-11.md): The 8 Requirements of RFC 9946 §11, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [RFC 9946 §12: IANA Considerations](https://udpstp.com/conformance/rfc9946-12.md): The 13 Requirements of RFC 9946 §12, each quoted from the RFC with its state and the tests that prove it. Conformance explains the states.
- [Deviations](https://udpstp.com/conformance/deviations.md): A Deviation is a recorded departure from a Requirement, with its reason. udpstp has 17. Each says whether it applies by default, which setting controls it, and…
- [Interpretations](https://udpstp.com/conformance/interpretations.md): An Interpretation is a recorded reading of a Requirement that is ambiguous, silent on a case or in conflict with another, or a choice the RFC leaves to the…
- [OB-UDPST Differences](https://udpstp.com/conformance/obudpst-differences.md): An OB-UDPST Difference is behaviour in which udpstp and OB-UDPST differ while udpstp conforms to the RFC. 31 records are OB-UDPST Differences only; with the…
- [How the records work](https://udpstp.com/conformance/format.md): cargo xtask req checks these files, prints coverage per section and each record's proving tests, and writes both to summary.md. It also writes…

## Project

- [Reporting a vulnerability](https://udpstp.com/security-policy.md): Please report vulnerabilities privately through GitHub's private vulnerability reporting, never in a public issue.
- [Architecture](https://udpstp.com/architecture.md): This document describes how udpstp is built: the parts of the system, the crates, the line between protocol logic and I/O, and how a Test Connection moves…
- [Technology](https://udpstp.com/technology.md): udpstp uses Rust for the protocol, runtime and command-line application. The architecture guide maps the crates. GLOSSARY.md defines their domain terms.
- [Decisions](https://udpstp.com/decisions/index.md): The Architecture Decision Records: decisions that are hard to reverse, why they were made, and the status of each.
- [ADR 0001: KDF fixed-input layout follows RFC 9946 Appendix A](https://udpstp.com/decisions/0001-kdf-fixed-input-layout-from-appendix-a.md): RFC 9946 §5.4.1 names the KDF inputs (counter-mode NIST SP 800-108, HMAC-SHA-256, r = 32, Label "UDPSTP", Context = decimal authUnixTime, 512 output bits) but…
- [ADR 0002: Stop traffic after 1 s of silence, tear down the Test Connection at 3 s](https://udpstp.com/decisions/0002-stop-traffic-at-1s-tear-down-at-3s.md): RFC 9946 contradicts itself on timeouts: §5.1 items 7–9 require the Load PDU and Status PDU timeouts to stop the test within at most 1 s of silence, while §6.1…
- [ADR 0003: Tokio runs the Control Phase; nothing precise runs on Tokio timers](https://udpstp.com/decisions/0003-tokio-control-plane-precise-data-phase-engine.md): The Control Phase (listening on the Standard Port, Setup and Activation exchanges, idle ephemeral sockets, second-scale watchdogs) is many mostly-idle I/O…
- [ADR 0004: Sending Rate Structure sizes are IPv4-based; IPv6 senders subtract 20 bytes](https://udpstp.com/decisions/0004-ipv4-based-sizes-in-sending-rate-structure.md): RFC 9946 has two SHALLs that collide on IPv6. §8.1 says the Client SHALL use the transmission parameters the Server sends, unchanged, and §6.1 caps IP packet…
- [ADR 0005: Congestion uses a back-to-back Errored Interval counter and a latched Congestion Confirmed state](https://udpstp.com/decisions/0005-latched-congestion-confirmed-state.md): RFC 9946 §5.1 requires Congestion to be inferred from Errored Intervals "in all of the consecutive intervals", while the Y.1540 Amd2 / TR-471 flowcharts (and…
- [ADR 0006: Transport errors are classified on both receive and send, not suppressed](https://udpstp.com/decisions/0006-classify-transport-errors-on-receive-and-send.md): ICMP-driven errors reach UDP sockets on every OS, and on Linux they reach the send path too: once a Test Connection's socket is connected (after the first…
- [ADR 0007: The Server learns each Setup Request's arrival address through nix, or quinn-udp on Windows](https://udpstp.com/decisions/0007-arrival-address-via-nix-and-quinn-udp-on-windows-listener.md): The Setup Response must leave from the local address the Setup Request arrived on, from the Standard Port (RFC 9946 §6.2.2: a reply from the new Ephemeral Port…
- [ADR 0008: The Data Phase Engine: a pool of Engine Threads on a Linux Server, one per Test Connection elsewhere, with bounded catch-up](https://udpstp.com/decisions/0008-data-phase-engine-per-core-epoll-with-bounded-catch-up.md): The Data Phase prototype compared two engine models:
- [ADR 0009: authUnixTime is checked within ±5 s inclusive modulo 2^32, the first Setup Request is signed with the Client key, and digests cover the PDU as received](https://udpstp.com/decisions/0009-authunixtime-window-and-setup-signing-interpretations.md): RFC 9946 leaves several details of mode 1 open. We resolve them as follows.
- [ADR 0010: Key Table rows follow RFC 7210 with an HMAC-SHA-256 AlgID, lifetimes checked on our clock, and an Operator extension](https://udpstp.com/decisions/0010-key-table-rows-lifetimes-and-extensions.md): RFC 9946 §5.4 requires a Key Table with RFC 7210's AdminKeyName, LocalKeyName, KDF, AlgID, Key and send/accept lifetimes, but leaves how they are used to the…
- [ADR 0011: Over-rate policing judges against the highest rate assigned in the last second](https://udpstp.com/decisions/0011-over-rate-policing-uses-the-highest-rate-assigned-in-the-last-second.md): ADR 0008 has the Server police an Upstream Load Sender: after 3 Trial Intervals in a row above 1.5 times its assigned rate, the Server stops the Test…
- [ADR 0012: Catch-up is bounded by a time budget](https://udpstp.com/decisions/0012-catch-up-by-time-budget.md): Bounding catch-up to one Sending Rate Structure interval makes the allowed lateness depend on the selected row. Rows of 100 Mbps and up send a Burst every 100…
- [ADR 0013: udpstp's stable interfaces from 0.1.0](https://udpstp.com/decisions/0013-stable-interfaces-from-0-1-0.md): Measurement platforms and Operators script against udpstp: they parse its JSON results and the Server's JSON log, branch on its exit status, generate its…
- [ADR 0014: The Server runs as a Windows service of its own, under a virtual account, logging to daily files](https://udpstp.com/decisions/0014-the-server-as-a-windows-service.md): A Server meant to run unattended on Windows must be a Windows service: the Service Control Manager starts a service at boot, restarts it after a failure and…
- [ADR 0015: Windows Shared Key files use a bounded private-file policy and a native inspection adapter](https://udpstp.com/decisions/0015-windows-shared-key-private-file-policy.md): Authenticated Clients and Server administrators need accidental permission grants caught when a Shared Key file is loaded. Unix already refuses untrusted…
- [Contributing](https://udpstp.com/contributing.md): Bug reports, interoperability reports, questions and documentation improvements are welcome. Before starting a substantial code change, open or comment on an…
- [Citing udpstp](https://udpstp.com/citation.md): If you use udpstp in research or a publication, please cite it. The repository's CITATION.cff holds the citation, which GitHub also offers as APA and BibTeX:
- [Changelog](https://udpstp.com/changelog.md): User-facing changes in udpstp, including capabilities, installation and compatibility.
- [About](https://udpstp.com/about.md): udpstp measures network-path capacity, loss and delay. Use it to check access lines and circuits, compare paths, or collect JSON results for your measurement…