Getting started

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.

Install udpstp

Install udpstp on both hosts using the installation guide.

Choose two hosts

Run the Server at the far end of the path you want to measure, and the Client where you want to test from. Both hosts need UDP connectivity. Testing on one machine checks the setup but doesn’t measure a network path.

Choose a MaxHops value slightly above the number of routers between the hosts; the examples below use 12.

Share a key

Tests are authenticated by default. Generate a random Shared Key with openssl rand -hex 32, or use the Windows instructions. Save the following as keys.toml on both hosts, replacing the placeholder with that same key:

[[key]]
admin_key_name = "first-test"
key_id = 1
key_hex = "replace-with-64-hexadecimal-digits"

Keep the file private. On Linux and macOS:

chmod 600 keys.toml

On Windows, set the key file’s permissions before continuing. Keys stay in the file, never on the command line.

Start the Server

Allow inbound UDP ports 24601 and 49152–65535 at the Server. Open the firewall covers other setups. On Windows, follow these steps before starting it.

As an ordinary account on the Server host:

udpstp server --key-file keys.toml --max-hops 12

Run your first Test

On the Client host, replace server.example.net with your Server’s name or address:

udpstp client --key-file keys.toml --max-hops 12 server.example.net

This runs a 10-second Downstream Test: the Server sends the traffic. Add --direction upstream to measure the other direction. The result shows the Maximum IP-Layer Capacity in Mbps and any warnings. Understanding the results explains what they mean.

On Windows, the Client normally needs no inbound firewall rule. A Server needs its own rule, added by an administrator.

Keep exploring

• Running a Test: options, JSON output and results.
• Hosting a Server: configuration and unattended operation.
• Share feedback: include your OS, udpstp --version, command and warnings, keeping your key private.

Guides

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 explanations and reference pages for the details.

To understand the results, read Understanding the results. The security model explains the defaults, and Stable interfaces says what scripts can rely on.

Installing udpstp

Install udpstp on both Test hosts. Choose your platform below, then follow Getting started to share a key and run a Test.

Installation methods

Linux

The installer selects a matching binary and places it in ~/.local/bin.

curl -fsSL https://udpstp.com/install.sh | sh

Run it again to update. It leaves your shell configuration unchanged. If ~/.local/bin is outside your PATH, add it using your shell’s configuration.

macOS

brew install pederbe/tap/udpstp

Use brew upgrade udpstp for updates and brew uninstall udpstp to remove it.

Windows

In PowerShell

irm https://udpstp.com/install.ps1 | iex

The installer uses your account’s LocalAppData\Programs\udpstp folder and adds it to PATH. You can use udpstp in the current PowerShell window immediately. Sign out and back in to refresh PATH for other applications. The Windows guide covers key-file permissions, firewall rules and running the Server as a service.

WinGet catalog approval is pending. The PowerShell installer and portable download are available now.

Signed Linux packages

The apt and dnf repositories provide normal package-manager updates and the Server’s systemd unit. The service stays disabled until you configure it and requires systemd 247 or later. Hosting a Server covers configuration and startup.

Debian and Ubuntu

Add the repository once, then install udpstp

curl -fsSL https://packages.udpstp.com/udpstp.gpg | sudo tee "/usr/share/keyrings/udpstp.gpg" >/dev/null
echo "deb [signed-by=/usr/share/keyrings/udpstp.gpg] https://packages.udpstp.com/apt stable main" | sudo tee /etc/apt/sources.list.d/udpstp.list
sudo apt update
sudo apt install udpstp

Updates arrive with apt upgrade. Remove the package with sudo apt remove udpstp.

Fedora, RHEL and similar distributions

sudo curl -fsSLo /etc/yum.repos.d/udpstp.repo https://packages.udpstp.com/udpstp.repo
sudo dnf install udpstp

Updates arrive with dnf upgrade. Remove the package with sudo dnf remove udpstp.

Portable downloads

The release page provides archives for the supported targets. Extract an archive and run its udpstp executable. Platform differences explains the available features.

Cargo

With Rust installed, build a release from source

cargo install --locked udpstp

With cargo-binstall installed, fetch a matching prebuilt release

cargo binstall udpstp

Building from source covers compiler and platform prerequisites.

AUR and Scoop recipes remain available as sources for later catalog submissions.

Running a Test

For Client users: Operators, measurement platforms, and anyone who runs udpstp client against a UDPSTP Server. Understanding the results explains what the results mean. udpstp client --help lists every option.

Get a key file

Tests are authenticated, so you need the same Shared Key as the Server. Ask the Server’s administrator for the key and its keyId.

1. Save them in a key file. A name ending in .toml is a TOML Key Table:

   [[key]]
   admin_key_name = "customers-2026"
   key_id = 1
   key_hex = "5b0c0e8d6f7a41c2b9d3e4f5061728394a5b6c7d8e9fa0b1c2d3e4f506172839"
   

   Give the key as key_hex (hexadecimal) or key_text (its UTF-8 bytes), not both. Any other file name is read as an OB-UDPST udpst.keys file, with one <keyId>,<key> line per key.

2. Make the file private. On Linux and macOS:

   chmod 600 keys.toml
   

   On Windows, follow Key file permissions. udpstp refuses a key file others can read, with exit status 51.

If the file holds several keys valid now, choose one with --key-id. Key files describes the format in full.

Run a Test

Run a 10-second Downstream Test, in which the Server sends the load:

udpstp client --key-file keys.toml server.example.net

Give the Server as a host name or address, with a port if it isn’t the Standard Port, 24601: server.example.net:24601, 192.0.2.10 or [2001:db8::10]:24601.

Run an Upstream Test, in which the Client sends the load:

udpstp client --key-file keys.toml --direction upstream server.example.net

Choose the Authentication Mode

The Client never falls back from mode 2 to mode 1 by itself, so an attacker can’t downgrade a Test. When a Server seems not to support mode 2, the Client says so:

udpstp: SERVER probably doesn't support mode 2: it rejected it, unverified; use --auth-mode 1 (the Client never falls back by itself)

Use --unauthenticated only on networks where every host is trusted. It protects nothing, and the Server must allow it too.

Common options

--jumbo and --traditional-mtu must match the Server’s settings, or it refuses the Test.

Read the results

The Client prints its progress, then the results:

Sending the Setup Request to 192.0.2.10:24601
Setup accepted, Ephemeral Port 56843
Test activated (Downstream)
The Server ended the Test

The headline is the Maximum IP-Layer Capacity near the end of the results:

  Maximum IP-Layer Capacity 1809.98 Mbps in Sub-Interval 8 (Loss Ratio 0.000000, …

Any warnings follow it under Warnings. A Test that completed with warnings still exits with status 0, so read them: each one says what limited the result. Fix common problems says what to do about each, and Understanding the results explains every line.

When the Server changes a parameter you asked for, a line says so before the Test starts, and the Test runs with the Server’s value:

The Server set testIntTime to 60 (asked for 120)

To end the Test instead, add --refuse-coercion testIntTime.

Save JSON results

udpstp client --key-file keys.toml --format json server.example.net > result.json

The JSON follows OB-UDPST’s schema, so tools written for OB-UDPST keep working. Progress and warnings go to standard error, so standard output holds only the JSON. A last "udpstp" object adds what OB-UDPST’s schema lacks. Leave it out with --json-extension=false for tools that reject unknown keys.

In udpstp’s JSON, AtMax and ModalResult are the Maximum IP-Layer Capacity, which meets the Performance Criterion, not OB-UDPST’s highest Sub-Interval. JSON results lists every field.

To keep your own address out of shared results, add --address-privacy truncate or --address-privacy pseudonymize --address-privacy-key-file FILE.

Run a Multi-Connection Test

One Test Connection may not fill a fast path. Run several in the same direction, and the Client sums their results:

udpstp client --key-file keys.toml --test-connections 4 server.example.net

• --test-connections N runs 1 to 255 Test Connections. OB-UDPST Servers accept at most 24, and so does a udpstp Server by default.
• Several SERVERs share the Test Connections in turn. They must all be IPv4 or all IPv6.
• --min-test-connections N sets how many must start for the Test to go on. By default all of them must.
• --max-bandwidth is for the whole Test, shared equally between its Test Connections.

If the Server answers from another address

The Client accepts responses only from the address it sent to. If a multi-homed Server answers from another one, ask its administrator for that address and allow it:

udpstp client --key-file keys.toml --allow-server-address server.example.net=192.0.2.20 server.example.net

The SERVER before = must match the one you test against exactly, port included. Repeat the option for more addresses. Unauthenticated Tests can’t use it.

Stop a Test

Press Ctrl-C. The Client tells the Server to stop and prints the results measured so far. A second Ctrl-C ends the Client at once. Exit statuses says how an interrupted Test exits.

Fix common problems

No answer from the Server

udpstp: no answer from 192.0.2.10:24601 within 3 s

A Server doesn’t answer a request that fails authentication, so a wrong key, a wrong keyId and a blocked port all look the same. Check, in order:

1. the SERVER address and port;
2. firewalls between you and the Server;
3. the key and keyId;
4. that both clocks are within 5 s of true time.

If it still fails, ask the Server’s administrator to turn on Troubleshooting Mode for a while. The Client then shows the reason:

udpstp: an unverified Setup Response said: authentication failed; check the key and keyId

If you use --checksum and the Client reports that a response failed its header checksum, try without --checksum.

The Server refused the Test

Other exit statuses

Exit statuses lists them all.

Warnings

What the warnings mean explains each one.

The OS held the socket buffers below the size asked for

At high rates, small socket buffers drop datagrams on the host, which looks like loss on the path. udpstp asks for 2 MiB and warns when the OS grants less:

udpstp: warning: the OS holds socket buffers below the 2097152 bytes asked for (receive …, send …); at high rates datagrams may be dropped locally, so raise the net.core.rmem_max and net.core.wmem_max sysctls

On Linux, raise the limits, then check the “This host” line of the next Test:

sudo sysctl -w net.core.rmem_max=4194304 net.core.wmem_max=4194304

On macOS and FreeBSD the limit is kern.ipc.maxsockbuf.

Hosting a Server

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 security model explains the defaults. On Windows, follow udpstp on Windows alongside this guide.

The required setup gets a Server running. A Server that Clients outside your own network can reach should also take the recommended steps. Each optional step says when you need it.

Required setup

Every Server needs these four steps, in this order. Install udpstp first, as in Installing udpstp.

Add keys

The Server authenticates Clients with its Key Table. It reads the table once at startup, so restart the Server after you change it.

1. Generate a random Shared Key of at least 32 bytes:

   openssl rand -hex 32
   

   On Windows, use PowerShell.

2. Write a TOML Key Table with one [[key]] row per key:

   # Consumers: one key per population of Clients.
   [[key]]
   admin_key_name = "customers-2026"
   key_id = 1
   key_hex = "5b0c0e8d6f7a41c2b9d3e4f5061728394a5b6c7d8e9fa0b1c2d3e4f506172839"
   accept_lifetime_end = "20270101000000Z"
   send_lifetime_end = "20270101000000Z"
   tests_per_quota_period = 12
   
   # Next year's key, added in advance so no restart is needed.
   [[key]]
   admin_key_name = "customers-2027"
   key_id = 3
   key_hex = "0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0"
   send_lifetime_start = "20261231000000Z"
   accept_lifetime_start = "20261231000000Z"
   
   # The NOC's Operator Key.
   [[key]]
   admin_key_name = "noc"
   key_id = 200
   key_hex = "c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4"
   operator = true
   max_test_interval = 3600
   

   Don’t use these example keys. Key files describes every field.

3. Make the file private. On Linux and macOS it must be mode 0600 or stricter, owned by the account running udpstp or by root, in a folder only its owner can write:

   chmod 600 keys.toml
   

   On Windows, follow Key file permissions.

4. Give each Client population its key and keyId over a secure channel.

Use a separate key for each population of Clients, and separate keys for Operators. To retire a key on schedule, set its accept_lifetime_end and send_lifetime_end. To revoke it at once, remove its row and restart the Server, which also ends the Tests running then.

Open the firewall

What to open depends on the firewall:

• A stateful firewall on the Server’s host or in a cloud security group needs only the Standard Port open inbound.
• A stateless filter, such as a router ACL, needs the Standard Port and the whole ephemeral_ports range.
• A Server behind NAT needs the Standard Port and the whole range forwarded to it, with the port numbers unchanged.
• At high packet rates, you may prefer to exempt Test traffic from connection tracking (nftables notrack) and allow the range as for a stateless filter.
• Windows Defender Firewall needs the whole range. See udpstp on Windows.

To keep a firewall rule small, narrow the range. It must hold at least max_test_connections plus the Unactivated Test Connection share, 384 ports with the defaults:

udpstp server --key-file keys.toml --ephemeral-ports 50000-50383 --max-hops 12

To listen on specific addresses instead of all of them, set listen (or repeat --listen ADDRESS).

Set MaxHops

RFC 9946 says the operator MUST set MaxHops, the TTL or hop limit of Test traffic, so that load can’t stray beyond the intended path. Until you set max_hops, the Server uses 64 and warns at every start:

udpstp: warning: max_hops (--max-hops) is not set, so test traffic has a TTL or hop limit of 64; RFC 9946 §10 says the operator MUST set it from the expected path length

Set it a little above the number of hops to your farthest Clients, which traceroute shows. Clients set their own with --max-hops.

Keep dont_fragment on (the default), so a packet larger than the Path MTU is lost rather than fragmented. Turn it off only to measure a path with fragmentation.

Start the Server

Run the Server with your key file and MaxHops:

udpstp server --key-file /etc/udpstp/keys.toml --max-hops 12

The Server listens on UDP 24601, the Standard Port, on every IPv4 and IPv6 address, and runs in the foreground. It needs no root privileges or capabilities.

Without a key file the Server can admit no Test, and warns at startup:

udpstp: warning: no key file and Unauthenticated Mode is off, so the Server can admit no Test; give one with --key-file, or allow unauthenticated Tests

Recommended for a public Server

For a Server that Clients outside your own network can reach.

Limit what Clients can use

A Server open to the internet should cap the load it agrees to carry. The defaults already allow one Test at a time per Source (an IPv4 address or an IPv6 /64) and budget Setup Requests.

1. Cap the admitted rate. Set admitted_rate_cap, in Mbps for each direction, together with require_max_bandwidth. Without it, Tests that state no maxBandwidth don’t count against the cap, and the Server warns:

   udpstp: warning: admitted_rate_cap is set but require_max_bandwidth is off: Tests that state no maxBandwidth are admitted without counting
   

2. Set Quotas if you want to limit how often each Source or key tests. Quotas are off by default and refill evenly over the quota_period (3600 s by default):

   udpstp server --key-file keys.toml --max-hops 12 --source-tests-per-quota-period 24
   

   Set a key’s own Quotas with tests_per_quota_period and bytes_per_quota_period in its row. Operator Keys are exempt. Use is counted in memory, so a restart forgets it.

3. Give each population of Clients its own key, and keys only to Clients you trust. The Server shares its capacity fairly between keys under a flood, but it can’t tell one key’s Clients apart.

Keep the other limits at their defaults unless you have a reason to change them. Server configuration lists each one, and the security model explains how they hold up under a flood. A Client refused by a limit sees CONNFAIL, CAPEXC or NOMAXBW and exits with status 113, 110 or 109.

Protect Client addresses

The log shows each Client’s address in full by default, for abuse handling. Client addresses are personal data in many jurisdictions. Set address_privacy to show less:

pseudonymize needs a key in address_privacy_key_file: hexadecimal digits for 16 bytes or more. A Client keeps the same pseudonym for as long as you keep the key:

openssl rand -hex 32 > /etc/udpstp/pseudonym.key
udpstp server --key-file keys.toml --max-hops 12 --address-privacy pseudonymize --address-privacy-key-file /etc/udpstp/pseudonym.key

Run it as a service

Whatever runs the Server, give it:

• a dedicated, unprivileged account that alone can read the key file;
• core dumps disabled, for example with ulimit -c 0, since a dump can hold the Key Table;
• a log system that rotates its standard output;
• a clock synchronised with NTP, since clocks more than 5 s apart make every authenticated Test fail.

With systemd

The supplied unit requires systemd 247 or later for credential loading.

contrib/systemd/udpstp-server.service is a hardened unit. It runs the Server as a user systemd creates when it starts, with no capabilities and a read-only view of the system. It loads the Key Table as a credential and makes a mode-0400 copy in its private runtime directory. The source in /etc/udpstp stays root’s, and the runtime copy is removed when the unit stops. The apt and dnf packages install it for you.

sudo install -m 755 target/release/udpstp /usr/local/bin/udpstp
sudo install -d -m 755 /etc/udpstp
sudo install -m 600 keys.toml /etc/udpstp/keys.toml
sudo install -m 644 server.toml /etc/udpstp/server.toml
sudo install -m 644 contrib/systemd/udpstp-server.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now udpstp-server
journalctl -u udpstp-server -f

server.toml is your configuration file. Leave key_file out of it, since the unit passes the key file itself. To bind a port below 1024, add AmbientCapabilities=CAP_NET_BIND_SERVICE and CapabilityBoundingSet=CAP_NET_BIND_SERVICE.

In a container

Each release publishes the image ghcr.io/pederbe/udpstp:<version>, which runs the Server as a non-root user (uid 65532) with no shell. Pin a version and upgrade on purpose. To build the image yourself:

podman build -f contrib/container/Containerfile -t udpstp .

Run it with the host’s network (--network host). A container network puts NAT and a bridge in front of the Server, so results would describe the container’s plumbing rather than the path. Pass the Key Table as a secret owned by uid 65532:

podman secret create udpstp-keys keys.toml
podman run -d --name udpstp --network host \
    --secret udpstp-keys,target=keys.toml,uid=65532,mode=0400 \
    ghcr.io/pederbe/udpstp:<version> --max-hops 16

Arguments after the image name are added to udpstp server’s and override the image’s configuration file, /etc/udpstp/server.toml. Or mount your own file there. With Docker, pass the key file as a Compose secret, or bind-mount a file owned by uid 65532 with mode 0400. podman stop and docker stop stop the Server cleanly within 2 s.

On Windows

Run an unattended Server as the Windows service udpstp-server. See Run the Server as a service.

Optional steps

Each step says when you need it. Skip the rest.

Write a configuration file

When: you have more than a few settings, or want them kept in one file.

Every setting has a command-line flag and a TOML key of the same name: --max-hops is max_hops. Flags replace the file’s values, and the file replaces the defaults.

1. Print the effective configuration to start a file:

   udpstp server --print-config > /etc/udpstp/server.toml
   

   Or write only what differs from the defaults:

   listen = ["192.0.2.10", "2001:db8::10"]
   key_file = "/etc/udpstp/keys.toml"
   ephemeral_ports = "50000-50383"
   max_hops = 12
   admitted_rate_cap = 10000
   require_max_bandwidth = true
   source_tests_per_quota_period = 24
   log_format = "json"
   address_privacy = "truncate"
   

2. Use absolute paths. A relative key_file is taken from the directory the Server starts in, not the file’s.

3. Check the file, keys included:

   udpstp server --config /etc/udpstp/server.toml --print-config
   

4. Start the Server with it:

   udpstp server --config /etc/udpstp/server.toml
   

An unknown key or an invalid value stops the Server with exit status 50 and names the setting:

udpstp: configuration error: ephemeral_ports: "50000-50099" has 100 ports, fewer than max_test_connections (256) plus the Unactivated Test Connection share (128)

Keep jumbo, traditional_mtu and server_mtu at their defaults to serve OB-UDPST Clients as well as udpstp ones. A Client whose --jumbo or --traditional-mtu differs is refused with BADJS or BADTMTU.

Raise the socket buffers

When: the Server warns that the OS holds socket buffers below the size asked for.

At high rates, small socket buffers drop datagrams on the host, which looks like loss on the path. The Server asks for socket_buffer_size, 2 MiB by default, and warns at startup when the OS grants less:

udpstp: warning: the OS holds socket buffers below the 2097152 bytes asked for (receive …, send …); at high rates datagrams may be dropped locally, so raise the net.core.rmem_max and net.core.wmem_max sysctls

On Linux, raise the limits to at least socket_buffer_size, and make the change permanent in a file under /etc/sysctl.d/:

sudo sysctl -w net.core.rmem_max=4194304 net.core.wmem_max=4194304

On macOS and FreeBSD the limit is kern.ipc.maxsockbuf.

Give it enough CPUs

When: the Server carries high rates or many Tests at once.

On Linux the Server runs one Engine Thread for each CPU it may use, each serving many Test Connections. Give it whole CPUs, and confine it with the service’s CPU affinity, such as systemd’s CPUAffinity= or taskset. A container’s fractional CPU limit is rounded down.

For high-rate Multi-Connection Tests, give the Server at least as many CPUs as such a Test has Test Connections.

A Server that falls behind says so in its TestSummary log lines: skipped_bursts when it couldn’t send on time, and receive_buffer_overflows for its Receive Buffer Overflows.

Debug a failing Client

When: a Client gets no answer and you suspect its key.

By default a Setup Request that fails authentication gets no answer, so a Client with the wrong key sees only a timeout. To find out why, turn on Troubleshooting Mode for a while:

udpstp server --key-file keys.toml --max-hops 12 --troubleshooting

The Client then reports the reason:

udpstp: an unverified Setup Response said: authentication failed; check the key and keyId

Turn it off when you’re done. While it is on, anyone can learn whether the Server has keys, and spoofed requests get replies.

Allow Tests without a key

When: on a lab network where every host is trusted, for Clients without a key.

Only on a network where every host is trusted, such as a lab, set allow_unauthenticated to accept Tests without a key, as default OB-UDPST installations do. It protects nothing: anyone who can reach the Server can start a Test. The Server still accepts authenticated Tests.

Read the log

When: you want to follow Tests, or feed the log to another system.

The Server writes one line per event to standard output, human-readable by default. Set log_format = "json" for one JSON object per line:

2026-09-26T14:46:26.621011Z  INFO Test Connection admitted event="TestConnectionAdmitted" test_connection_id=1 client="127.0.0.1:51801" mc_ident=60798
2026-09-26T14:46:37.129734Z  INFO Test ended: Completed event="TestSummary" client=127.0.0.1:51801 mc_ident=60798 test_connections=1 direction="Downstream" test_interval=10 … result="Completed"

Filter on the event name and its fields, not on the message. Under a service manager, leave the log on standard output and let it rotate the log. Otherwise set log_file to write a new file each day, kept for 14 days, in a folder of its own. Server log lists every event, field and reason.

udpstp on Windows

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 Hosting a Server. Platform differences lists what Windows can’t do yet.

Generate a Shared Key

PowerShell can generate a 32-byte key without OpenSSL:

$bytes = New-Object byte[] 32
$rng = [Security.Cryptography.RandomNumberGenerator]::Create()
$rng.GetBytes($bytes)
$rng.Dispose()
-join ($bytes | ForEach-Object { $_.ToString('x2') })

Put the output in key_hex, and copy the key file to the other host securely.

Key file permissions

Both roles refuse a key file that other accounts can read or change, with exit status 51 and a message naming the reason. Only the running account, SYSTEM and Administrators may have access.

For a Client, or a Server you run in a window:

1. Put the key file in a folder of its own in your profile, holding only key files. Never use a folder created directly under C:\, where every signed-in account can change what’s inside.
2. In Windows PowerShell 5.1, as the account that will run udpstp, go to that folder and run the following. For an OB-UDPST file, replace keys.toml with its name.

$ErrorActionPreference = 'Stop'
$keys = (Resolve-Path -LiteralPath 'keys.toml').Path
$folder = Split-Path -Path $keys -Parent
$me = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
$trusted = "(A;;FA;;;$me)(A;;FA;;;SY)(A;;FA;;;BA)"
$sections = [Security.AccessControl.AccessControlSections]::Owner -bor [Security.AccessControl.AccessControlSections]::Access
$directory = New-Object Security.AccessControl.DirectorySecurity
$directory.SetSecurityDescriptorSddlForm("O:${me}D:P(A;OICI;FA;;;$me)(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)", $sections)
[IO.Directory]::SetAccessControl($folder, $directory)
$file = New-Object Security.AccessControl.FileSecurity
$file.SetSecurityDescriptorSddlForm("O:${me}D:P$trusted", $sections)
[IO.File]::SetAccessControl($keys, $file)
# Examine the actual file, not only its containing folder.
Get-Acl -LiteralPath $keys | Format-List Owner, AreAccessRulesProtected, AccessToString
icacls $keys

3. Check the output. The file should be owned by your account, have inheritance protected, and list only SYSTEM, Administrators and your account, each with (F).

4. Check that udpstp accepts it, with no key file error:

   udpstp server --key-file keys.toml --print-config
   

The script replaces the folder’s and the file’s permissions completely, removing any other account’s access. If other accounts need the folder, keep a copy elsewhere first. To add a key file later, copy it into the folder rather than moving it, since a moved file keeps its old permissions, and run the script again for it.

For an unattended Server, the service installer sets up its own protected folder instead.

Run a Client

The Client starts every exchange itself, so it normally needs no inbound firewall rule. A Server run from the same udpstp.exe still needs its own rule.

Try a Server in a window

For a trial, before the Server first starts:

1. Install the program where only administrators can change it. As administrator, copy udpstp.exe into C:\Program Files\udpstp. The firewall rule names this path and lets in whatever program is there.

2. Add the firewall rule, as administrator, before udpstp.exe first runs from that path. Allow your port and the whole ephemeral_ports range, here the defaults:

   $udpstp = "$env:ProgramW6432\udpstp\udpstp.exe"   # the udpstp.exe that runs the Server
   New-NetFirewallRule -DisplayName "udpstp Server" -Group "udpstp" `
       -Direction Inbound -Action Allow -Program $udpstp `
       -Protocol UDP -LocalPort '24601','49152-65535' -Profile Any
   

   For a Server that should answer only its own LAN, add -RemoteAddress LocalSubnet. To remove the rule later, run Remove-NetFirewallRule -Group udpstp.

3. Protect the key file as above, for your own account.

4. Start the Server from a window that isn’t elevated. Never use “Run as administrator”, which would give a network-facing process administrator rights:

   & "$env:ProgramW6432\udpstp\udpstp.exe" server --key-file keys.toml --max-hops 12
   

The log appears in the window. Ctrl+C stops the Server, and so does closing the window or signing out. Check that a Client on another host can run a Test, since a loopback Test doesn’t prove inbound access.

Avoid reserved ports

Windows can reserve ranges of ports, which the Server then can’t use. The Server skips them without a warning, so a range that overlaps them holds fewer Test Connections than it seems, and Clients get CONNFAIL. If you narrow ephemeral_ports, list the reserved ranges first and pick a range outside them:

netsh int ipv4 show excludedportrange protocol=udp
netsh int ipv6 show excludedportrange protocol=udp

If someone cancelled a firewall dialog

Without a rule for its path, Windows may ask whether to allow udpstp.exe when the Server starts. Allow, answered by an administrator, adds an Allow rule. Cancel adds Block rules, which override any Allow rule for that path, and Windows won’t ask again.

To recover, remove only the dialog’s Block rules for that path, as administrator, with $udpstp set as above:

Get-NetFirewallApplicationFilter | Where-Object Program -eq $udpstp |
    Get-NetFirewallRule | Where-Object { $_.Name -like '*Query User*' -and $_.Action -eq 'Block' } |
    Remove-NetFirewallRule

Then confirm that the remaining rules name the program and your UDP ports:

Get-NetFirewallApplicationFilter | Where-Object Program -eq $udpstp |
    Get-NetFirewallRule | Format-Table Name, Enabled, Direction, Action, Profile
Get-NetFirewallApplicationFilter | Where-Object Program -eq $udpstp |
    Get-NetFirewallRule | Get-NetFirewallPortFilter | Format-Table Protocol, LocalPort

This keeps rules an administrator created, and doesn’t override an organisation’s firewall policy.

Run the Server as a service

An unattended Server runs as the Windows service udpstp-server, under its own virtual account.

1. As administrator, copy udpstp.exe to C:\Program Files\udpstp\udpstp.exe. The service runs whatever program is at that path, so it must be where only administrators can change it.

2. Put your Key Table in C:\ProgramData\udpstp\keys.toml.

3. From an elevated PowerShell, run the install script from the source’s contrib\windows folder:

   powershell -ExecutionPolicy Bypass -File .\udpstp-server.ps1 -Install
   

The script:

• locks C:\ProgramData\udpstp to Administrators and SYSTEM, with read access for the service and write access to its logs folder;
• writes a starting configuration, C:\ProgramData\udpstp\server.toml, if there is none;
• checks the configuration, so a mistake shows up here rather than as a service that won’t start;
• creates the service, running as NT SERVICE\udpstp-server with no privileges and no credential to set or expire;
• adds the firewall rule udpstp-server for your port and ephemeral_ports;
• starts the service once to check its keys, and only then sets it to start at boot and restart after a failure.

If a step fails, the script leaves the service stopped and disabled and reports why. Fix the problem and run -Install again.

To change the configuration, edit server.toml and run -Install again. Write paths in single quotes, such as 'C:\ProgramData\udpstp\keys.toml', since a backslash inside double quotes starts an escape. Save the file as UTF-8, not as the UTF-16 that Windows PowerShell 5.1’s > writes.

To upgrade, stop the service with Stop-Service udpstp-server, replace udpstp.exe, and start it again. The firewall rule stays valid because the path doesn’t change.

To uninstall, run the script with -Uninstall. It keeps C:\ProgramData\udpstp unless you add -RemoveData.

The log is in C:\ProgramData\udpstp\logs\server.<date>.log, a new file each day, with the last 14 kept. If the service won’t start, its log says why, and sc.exe query udpstp-server shows its exit status as SERVICE_EXIT_CODE: 50 for a configuration error, 51 for a key file error, 75 when it couldn’t start.

If the service fails with error 1069, a group policy has removed “Log on as a service” from NT SERVICE\ALL SERVICES. Grant it to NT SERVICE\udpstp-server.

Where PowerShell runs in Constrained Language mode, the script stops. Make the same changes by hand, following the list above.

With Fast Startup on, which client editions of Windows enable, “Shut down” hibernates the service instead of stopping it. Restart Windows to stop it.

Installation and firewall rules

Firewall rules name the program’s full path. The install script keeps udpstp.exe at the same path across upgrades, so its rules keep working. If you move the program, add a rule for the new path.

Scoop and winget run udpstp through a shim or a versioned folder. A rule for the shim doesn’t cover the program it runs, and a versioned path changes with each upgrade. For a Server, use the service above.

Operator features

For Operators measuring within their own networks, and for the Server administrators who give them Operator Keys.

Operator Keys

An Operator Key is a Shared Key that the Server’s Key Table marks as belonging to an Operator. The Server decides: a Test gets an Operator’s allowances only when its Setup Request verified with a row marked operator = true, whatever the Client claims.

On the Server, in a TOML Key Table (Key files):

[[key]]
admin_key_name = "noc"
key_id = 200
key_hex = "c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4"
operator = true
max_test_interval = 3600

max_test_interval is optional: without it, an Operator Key’s Tests are limited to 60 s like everyone else’s. An OB-UDPST udpst.keys file can’t mark Operator Keys.

On the Client, the key file needs only the key; operator there changes nothing:

[[key]]
admin_key_name = "noc"
key_id = 200
key_hex = "c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4"

Give Operator Keys their own keyIds, and never share them with Consumers.

What an Operator Key allows

The last row matters only to Clients that set slowAdjThresh or trialInt, which the udpstp Client doesn’t.

An Operator Key is not exempt from authentication, tests_per_source (one Test at a time per Source by default), the Test Connection limits, the Admitted Rate Cap itself, require_max_bandwidth, or the Setup Request budgets.

Fixed-Rate Tests

A Fixed-Rate Test holds one Sending Rate Table row for its whole Test Interval instead of searching. Use it to check that a path carries a known rate, for example a provisioned service rate.

udpstp client --key-file noc.toml --fixed-rate 100 server.example.net

Rows 1 to 1000 offer that many Mbps at the IP layer; rows 1001 to 1152 offer the rates above 1 Gbps. Row 0 offers about 0.1 Mbps. The results’ header names the Test type:

Results
  Downstream Fixed-Rate Test with 127.0.0.1:24701, started 2026-09-26T14:50:11Z (T0)

A Test with an ordinary key is refused:

udpstp: the Server rejected the Activation Request; only an Operator Key may run a Fixed-Rate Test (RFC 9946 §4.1), so check the key, or the Server's log

with exit status 152; the Server logs reason="FixedRateNeedsOperatorKey". --fixed-rate and --start-row can’t be combined.

Check the IP-Layer Sender Bit Rate. A Fixed-Rate Test sends only as fast as the Load Sender can. Compare the B column, the Sender Bit Rate, with the row’s rate. When it is below the row’s rate, the host, not the path, set the result, and the Server’s log shows BurstsSkipped.

Long Test Intervals

An Operator Key with max_test_interval allows Tests longer than 60 s, up to that many seconds:

udpstp client --key-file noc.toml --test-interval 900 --delay-var rtt server.example.net

Above 60 s the Server judges by round-trip delay variation instead of one-way delay variation, which clock drift would distort over a long Test. Ask for it with --delay-var rtt; otherwise the Server coerces it and the Client says so:

The Server set useOwDelVar to 0 (asked for 1)

A Test Interval beyond the key’s maximum is coerced to it. Add --refuse-coercion testIntTime to have the Client end the Test instead (exit status 201).

MaxHops

MaxHops, the TTL or IPv6 hop limit of test traffic, keeps a Test’s load from straying beyond the path you mean to measure (RFC 9946 §10). Each end sets its own: the Server with max_hops, which RFC 9946 says the operator MUST set, and the Client with --max-hops (64 by default).

udpstp client --key-file noc.toml --max-hops 12 server.example.net

Set it a little above the number of hops on the path. Too small, and the load dies on the way: the Client reports “ICMP time-exceeded errors: –max-hops is too small for the path” instead of a low capacity, and the Server logs it.

DSCP

To measure a specific traffic class, mark the Test’s traffic with its DSCP:

udpstp client --key-file noc.toml --dscp 46 server.example.net

The Server allows a DSCP from its operator_allowed_dscp set for an Operator Key, and from allowed_dscp for anyone else. A DSCP outside the set is coerced to 0. The results’ parameters line says which DSCP was agreed, such as DSCP 46 agreed.

A Server administrator narrows the Operator set with, for example:

udpstp server --key-file keys.toml --max-hops 12 --operator-allowed-dscp 0,10,18,26,34,46

The ECN bits are always Not-ECT. Windows doesn’t let udpstp mark traffic (Platform differences).

Multi-Connection Tests at high rates

One Test Connection may not fill a multi-gigabit path. Spread the Test over several Test Connections, and over several Servers if one host can’t send enough:

udpstp client --key-file noc.toml --test-connections 8 --max-bandwidth 10000 server-a.example.net server-b.example.net

Running a Test explains the options, and Understanding the results how they are summed.

Building udpstp

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.

You need Git and Rust installed through rustup. The repository’s rust-toolchain.toml selects the toolchain; Cargo uses the checked-in dependency versions with --locked.

git clone https://github.com/pederbe/udpstp
cd udpstp
cargo build --locked --release -p udpstp

The binary is target/release/udpstp, or target\release\udpstp.exe on Windows. Run it by that path, or install it into Cargo’s binary directory so the guides’ udpstp commands work:

cargo install --locked --path crates/udpstp
udpstp --version

If Cargo says its binary directory isn’t on your PATH, add that directory using your shell’s settings. Then follow Getting started on both hosts.

For development checks and contributions, see CONTRIBUTING.md.

Understanding the results

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.

What a Test measures

A Test sends load across the path for its Test Interval, 10 s by default, split into Sub-Intervals of 1 s. In a Search Test, the Server’s Load Rate Adjustment Algorithm raises the sending rate until the path shows loss or growing delay, then holds it around the limit.

Each Sub-Interval has an IP-Layer Capacity: the bits that arrived, IP and UDP headers included, over its length. The Maximum IP-Layer Capacity is the highest IP-Layer Capacity of the Sub-Intervals that meet the Performance Criterion, which caps the share of Load PDUs a Sub-Interval may lose (1% by default). It is the headline result, as RFC 9097 defines it.

The Highest IP-Layer Capacity is the highest of all Sub-Intervals, whatever they lost. OB-UDPST reports it as its maximum. udpstp shows it beside the Maximum whenever they differ.

The text results

This Downstream Test ran over loopback, so the two hosts, not a network, set its rates:

Test outcome: completed
Endpoints
  Test Connection 0: Client unknown; Server 127.0.0.1:24701
Results
  Downstream Search Test with 127.0.0.1:24701, started 2026-09-26T21:51:34Z (T0)
  Test Interval (I) 10 s in 10 Sub-Intervals (dt) of 1000 ms; Trial Interval
    (FT) and st 50 ms; 1 Test Connection (F); MaxHops 64; DSCP 0 agreed
  Performance Criterion: loss at most 1% of the Load PDUs sent, or one; Tmax up
    to 1000 ms (a late Load PDU counts within the Sub-Interval its gap was seen
    in)

  Sub-Interval results
  SI = Sub-Interval; C = IP-Layer Capacity; DV = delay variation (min/avg/max);
    RTTV = RTT variation (min-max, avg); - = no measurement.
  B = IP-Layer Sender Bit Rate.
  SI  C (Mbps)  Loss Ratio
   1    103.97    0.000000
   2    303.93    0.000000
   3    504.06    0.000000
   4    648.99    0.000000
   5    801.02    0.000000
   6   1450.50    0.000000
   7   1689.22    0.002149
   8   1809.98    0.000000
   9   1867.22    0.014783
  10   1860.05    0.015516

  SI  Lost  Reordered  Duplicates
   1     0          0           0
   2     0          0           0
   3     0          0           0
   4     0          0           0
   5     0          0           0
   6     0          0           0
   7   307          0           0
   8     0          0           0
   9  2340          0           0
  10  2443          0           0

  SI  DV (ms)  RTTV (ms)
   1    0/1/3     0-1, 0
   2    0/1/2     0-2, 1
   3    0/1/2     0-2, 1
   4    0/1/7     1-7, 2
   5    0/1/8     1-3, 1
   6   0/2/11     1-6, 2
   7   0/4/11     1-8, 4
   8    0/3/9     1-8, 3
   9   0/4/14     1-8, 4
  10   0/5/12     1-8, 5

  SI  B (Mbps)*
   1      93.75
   2     293.58
   3     493.68
   4     646.35
   5     789.84
   6    1432.82
   7    1665.09
   8    1810.14
   9    1893.99
  10    1893.41

  * The IP-Layer Sender Bit Rate estimated here, not measured by the Load
    Sender: the Load PDUs the Server sent in each st of its own clock, from
    their lpduSeqNo span, a lost one as big as those around it

  Summary
  F = Test Connections; SI = Sub-Interval; Max = Maximum IP-Layer Capacity; - =
    no valid result.
   Phase  F  SI  Max (Mbps)  Loss Ratio
  Search  1   8     1809.98    0.000000
  RTT minimum (ms)  RTT maximum (ms)
                 0                 8
  Maximum Sub-Interval result received at an unknown time
  Maximum IP-Layer Capacity 1809.98 Mbps in Sub-Interval 8 (Loss Ratio 0.000000,
    RTT variation 1-8 ms above a minimum of 0 ms, estimated IP-Layer Sender Bit
    Rate 1810.14 Mbps); Highest IP-Layer Capacity 1867.22 Mbps in Sub-Interval 9
    (Loss Ratio 0.014783)
  RTT minimum 0 ms
  Minimum one-way delay 0 ms (clockDeltaMin; valid only if the clocks are
    synchronized)

  This host: DF clear, socket buffers receive 2097152 and send 2097152 bytes;
    portable Data Phase Engine, no fast paths
Test completed

Line by line:

• Test outcome: completed, completed with warnings or qualified results, partially completed, failed, aborted or interrupted. A Multi-Connection Test also gives each Test Connection’s own outcome.
• Endpoints: each Test Connection’s Server and, where the socket knows it, the Client’s address. A socket bound to every address can’t name the Client and says unknown. --address-privacy applies here too.
• Header: the direction, whether the algorithm set the rate (a Search Test) or an Operator fixed it (a Fixed-Rate Test), the Server, and the start time T0 in UTC.
• Parameters, in RFC 9097’s notation: the Test Interval I, its Sub-Intervals of length dt, the Trial Interval FT, st (the interval the IP-Layer Sender Bit Rate is taken over), and F, the number of Test Connections. MaxHops is this end’s own setting. The DSCP is the one the Server agreed to.
• Performance Criterion: the share of Load PDUs a Sub-Interval may lose and still count, set with --max-loss-ratio. One lost Load PDU always passes. A Sub-Interval in which nothing arrived never does. Tmax is how late a Load PDU may arrive and still count as received.
• The tables, one row per Sub-Interval (SI). The terminal’s width decides whether they fit in one table or several:
  • C: the IP-Layer Capacity.
  • Loss Ratio and Lost: the Load PDUs lost, as a share of those sent and as a count. Reordered and Duplicates count the other Sequence Errors. Duplicates count as received.
  • DV: the one-way delay variation’s minimum, average and maximum.
  • RTTV: the round-trip time variation, lowest to highest, and its average, above the RTT minimum.
  • B: the IP-Layer Sender Bit Rate, what the Load Sender actually sent. In a Downstream Test the Client can only estimate the Server’s rate, and the footnote says so. In an Upstream Test it is measured on this end.
• Maximum IP-Layer Capacity: the headline result, with its Sub-Interval’s Loss Ratio, RTT variation and Sender Bit Rate. Sub-Intervals 9 and 10 above were faster but lost more than 1%, so they don’t count, and the line ends with the Highest IP-Layer Capacity. With --first-mode-sub-intervals there is one such line per Capacity Mode.
• Maximum Sub-Interval result received: when this Client learned the Maximum’s own Sub-Interval result, or unknown.
• RTT minimum and Minimum one-way delay. The one-way figure compares the two ends’ clocks, so it means something only when they are synchronised.
• Warnings, when there are any (below).
• This host: whether the Don’t Fragment bit (DF) was set, the socket buffers the OS granted, and which Data Phase Engine ran with which fast paths. On Linux this names batched sending and receiving, UDP GSO and kernel timestamps. This example ran on Windows, which has none. Platform differences lists them.

In a terminal, headings are cyan, a clean result green, warnings and partial results yellow, and failures red. --color never keeps the output plain.

Was the network or a host the limit?

A search that rises past the path’s limit meets loss or growing delay there, so its Trial Intervals turn errored:

• Below the 1 Gbps row the search climbs fast, and three Errored Intervals come back to back at its first overshoot. It confirms Congestion.
• Above that row it climbs one row at a time. Through a shallow queue it cycles around the limit, with Errored Intervals often too few back to back to confirm Congestion. It met the limit when they recur among its last Trial Intervals.

The Client counts its own Trial Intervals. When no Test Connection’s search found the limit either way, it warns that the result may understate the path, and says why (below).

In a Fixed-Rate Test, which doesn’t search, look for yourself. If the Sender Bit Rate sits close to the Capacity in every Sub-Interval and the Loss Ratio stays near 0, the Load Sender may be the bottleneck rather than the path. A Server that falls behind logs BurstsSkipped. A Client that falls behind lists Skipped Bursts in its warnings.

What the warnings mean

A completed Test’s warnings appear under Warnings in the text results and in udpstp.Warnings in the JSON, each with a Code to match on rather than its wording (JSON results). The Test still exits 0. In the JSON, ErrorStatus carries the most severe one.

No Sub-Interval met the Performance Criterion. There is no valid Maximum IP-Layer Capacity (JSON ErrorStatus 49): the path lost more than --max-loss-ratio all along. A bottleneck with a shallow buffer does this. The search keeps stepping a row or two above its rate and back, losing a few percent there, as OB-UDPST’s does too. The Highest IP-Layer Capacity is then the path’s.

A Sub-Interval ran faster than the Maximum, or the last one much slower (JSON SubIntervalsAfterMaximumMissed). In a Search Test, every Sub-Interval after the Maximum’s lost too much to count, and either one of them ran more than 5% faster than the Maximum (--faster-sub-interval-margin), or the last one ran under 60% of it. Common causes:

• A drop-tail bottleneck. After its first overshoot, the search cycles a row or two around the bottleneck’s rate, losing a few percent in each Sub-Interval. The Maximum then falls to a Sub-Interval of the climb, as low as half the path’s rate. This is most common from the 1 Gbps row up, where rows are 100 Mbps apart, and over long round trips.
• A queue that keeps dropping after it overflowed, as CAKE can when a few Test Connections carry a fast link’s load. The rest of the Test then runs well below the link’s rate. With enough Test Connections that each carries under 1 Gbit/s, CAKE stops the loss within a few seconds and the Test reads the link’s rate.
• A policer or shaper that let a burst through at first. The Maximum is then its sustained rate, which is right.
• A path that slowed during the Test, or, Downstream, a Server that fell behind.

An Upstream Test in which this host left more than 1% of its Load PDUs unsent warns of its Skipped or Withheld Bursts instead.

Skipped Bursts: this host couldn’t send on schedule, so the result is limited by the sender. Withheld Bursts: the OS couldn’t take the datagrams fast enough.

The Server sent below its Fixed-Rate row. In a Downstream Fixed-Rate Test, the Server sent less than its row, as this Client estimated it. It may have skipped or withheld Bursts, so the Server limited the result. A Search Test’s Server doesn’t tell the Client its sending rate, so it gets the next warning instead.

The search never confirmed Congestion. No Test Connection’s search reached the path’s limit, as this Client counted their Trial Intervals, so the result may understate the path (JSON CongestionNeverConfirmed). The rest of the line names the cause (below).

Datagrams too large for the path with DF set. A hop’s MTU is below the Test’s IP packets, so the Test didn’t measure the path’s capacity. Rates up to 1 Gbps use IP packets of 1250 bytes, or 1500 with --traditional-mtu. Faster Jumbo rows use up to 9000. This is reported on Linux.

ICMP time-exceeded errors. The path is longer than MaxHops, so the load expired on the way.

Status PDUs never arrived, or the peer had missed Status PDUs. Status PDUs were lost. In a Downstream Test the Server lowers the rate when that happens.

Status PDUs failed authentication (mode 2). Status PDUs arrived that didn’t verify, so something on the path changed or injected them.

Nothing was received for 1 s, so this end stopped sending. The Watchdog ended the Test after 3 s of silence, without the STOP exchange. The results cover what was measured.

Load PDUs without a delay sample: the wall clock stepped. The clock was adjusted during the Test.

When the search never confirmed Congestion

In a Search Test, this Client classifies each Trial Interval itself, from the Status PDUs it sends in a Downstream Test and receives in an Upstream one, with the thresholds the Server accepted. A search found the path’s limit when it confirmed Congestion, or met the limit at its end: of its last 64 Trial Intervals, from the first Errored Interval among them on, at least 4 were Errored Intervals and at least 1 in 4, counting Hold Intervals of both kinds.

When no Test Connection’s search found the limit either way, the warning names the first cause that fits:

• The maxBandwidth. The search stopped where a udpstp Server stops it, at the highest row at or below the maxBandwidth stated, or its share of it in a Multi-Connection Test. Above 1 Gbps the rows are 100 Mbps apart up to 7.2 Gbps and 720 Mbps apart beyond, so with --max-bandwidth 10000 the search stops at 9360 Mbps. An OB-UDPST Server keeps to the maxBandwidth only in a build with rate limiting, run with -B.
• The top of the Sending Rate Table, judged from the Load PDUs sent at the peak. The Server’s MTU decides their size: the table tops out at 12 Gbps with the default 1500 bytes, and at up to 72 Gbps with 9000-byte Jumbo packets.
• Delay variation, when more than half the Trial Intervals were Hold Intervals with a delay sample, between lowThresh and upperThresh. A Hold Interval in which no Load PDU arrived in order shows no delay variation and isn’t counted here.
• Still rising, when the last Sub-Interval’s IP-Layer Sender Bit Rate is above every earlier one’s by more than Fast Mode adds with half its Trial Intervals clean, 100 Mbps at the defaults. A Load Sender held to a packet rate steps up once too, as its Load PDUs grow past the 1 Gbps row, so from about 500 Mbps a short Test can read as still rising where a longer one would name the Load Sender.
• A Load Sender that stopped rising, the Server’s or this host’s, though few of the last 64 Trial Intervals were Errored Intervals.

Some paths and Servers make this warning more likely:

• A managed queue can hold the search in Hold Intervals. fq_codel, with a Load Sender only just above the bottleneck, can hold a standing queue whose drops stay under seqErrThresh. The search’s last Trial Intervals are then Hold Intervals with no Errored Interval among them, until CoDel drops faster. A Test that ends before then names the Load Sender, or delay variation, though the path limited it.
• The Client classifies by each Trial Interval’s largest delay variation, the delay range the RFCs judge, as a udpstp Server does by default. An OB-UDPST Server classifies by the average, which is lower, so against one, delay variation can be named for a search it didn’t hold.
• This Client’s count can differ from the Server’s. It counts the one or two Trial Intervals it reports after the Server’s STOP1, and Status PDUs lost on the way back, which the Server never classifies. It can’t see the Server’s Lost Status Backoffs, which count as Errored Intervals there. Algorithm C’s Fast-Mode Retry restarts the Server’s run of Errored Intervals but not this Client’s. So the warning can come although the Server’s search confirmed Congestion.
• An OB-UDPST Server counts more loosely. A Clean or Hold Interval doesn’t reset its count of Errored Intervals, where this Client, like a udpstp Server, needs them back to back (ADR 0005). Against an OB-UDPST Server, the warning can come although its search confirmed Congestion.

Multi-Connection results

A Multi-Connection Test prints the summed results first, then each Test Connection’s own Maximum IP-Layer Capacity. The summed table has an Active column: how many Test Connections received in that Sub-Interval. A Test Connection that didn’t complete says how it ended, and standard error says why, naming it.

A Downstream Test’s Test Connections are summed on one time grid. An Upstream Test’s are each measured by their own Load Receiver, at the Server, and summed by Sub-Interval number, so the sum is approximate, and a warning gives the largest offset between their Sub-Intervals.

The “This host” line covers all Test Connections: the smallest socket buffers the OS granted any of them, and the fast paths every one that completed used.

Security model

This document describes what udpstp protects, from whom, and how. It is written for Server administrators and Operators deciding whether to deploy udpstp, and for security reviewers. SECURITY.md says how to report a vulnerability.

Each defence below names the file, and the function, that implements it. The glossary defines terms such as Test Connection, Shared Key and Silent Rejection.

Summary

• A Client selects authorized Server destinations locally before receiving responses. By default only its selected Server endpoint is accepted; authenticated Tests may use explicit per-Server alternate IP addresses through --allow-server-address SERVER=IP. Response authentication and Null Requests cannot add destination addresses. The sans-IO core enforces this before Activation and the Data Phase (crates/udpstp-core/src/client.rs, setup_source_authorized), retaining the selected Standard Port and IPv6 scope.
• A Test starts only after the Client proves it holds a Shared Key that the Server knows. By default the Server answers nothing to a request that fails verification (Silent Rejection).
• Only Clients authenticated with an Operator Key may run Fixed-Rate Tests.
• A Test marks its traffic only with a DSCP the Server allows: 0 (best effort) unless the administrator adds more (allowed_dscp), so a Consumer can’t put a Test’s load into a priority class, and for Operator Keys any but network control, CS6 and CS7 (operator_allowed_dscp). A Client refuses a DSCP it didn’t ask for other than 0 (crates/udpstp-core/src/parameters.rs, clamp and unrunnable).
• Keys come only from key files. Unix refuses unsafe ownership or group/other reading and writing. Windows refuses supported-policy mismatches and unverified permissions before reading keys, with distinct key file errors (Key handling). Keys never appear on the command line, in errors or in output, and they are wiped from memory when no longer needed.
• UDPSTP authenticates. It does not encrypt. Anyone on the path can read Test parameters and results.
• The Server enforces Admission limits (Test Connection caps, the Admitted Rate Cap, one Test per Source), drops replays inside the time window and budgets unverified Setup Requests globally and authentic ones per Source. A key holder can still sign requests from other addresses, spending those Sources’ budgets, so share keys only with Clients you trust. See Hardening.

Assets

Actors and trust boundaries

• Consumer: a Client user without an Operator Key: an ordinary Shared Key, or none where the Server allows Unauthenticated Mode. Trusted to run Tests, not trusted with Fixed-Rate Tests or unlimited resources.
• Operator: holds an Operator Key, and is trusted with Fixed-Rate Tests and longer Tests.
• Server administrator: controls the Server host, its key file and its configuration. Fully trusted.
• Off-path attacker: can send datagrams with any source address but cannot see the traffic between Client and Server.
• On-path attacker: can observe, drop, delay, modify, replay and inject datagrams between Client and Server.
• Local user: an unprivileged account on the Client or Server host.

The boundaries are the network (everything arriving on a socket is untrusted until verified), the key files (readable only by the account running udpstp, which udpstp checks on every platform, see Key handling), and the logs, which can contain attacker-controlled data such as source addresses.

Assumptions: the hosts themselves are not compromised, Shared Keys are distributed over a secure channel outside UDPSTP, and both ends’ wall clocks are within 5 seconds of true time.

Threats and defences

Load PDU timestamp gaps are bounded. A Load Receiver’s sender estimate closes at most the negotiated Test Interval’s number of st plus one per Load PDU, then skips any remaining empty intervals in one step (crates/udpstp-core/src/data_phase.rs, SentEstimate::add). A Consumer can negotiate at most 60 s with st of at least 5 ms, so at most 12,001 closures are needed, independent of the wire timestamp gap. Operator Keys may permit longer Test Intervals and correspondingly larger reporting limits. This bounds the core callback’s interval processing without changing the Engine Thread model (ADR 0008) or send catch-up budget (ADR 0012); it is not a measured latency guarantee.

RFC references are to RFC 9946 unless stated otherwise. Code paths are relative to the repository root.

Admission under load

The Server bounds what a flood can cost it, and shares its capacity between keys. The settings below are in Server configuration.

Forged Setup Requests. A request with an unknown keyId costs almost nothing to drop. One with a known keyId spends the global budget for unverified Setup Requests, unverified_setups_per_second, before its KDF run and HMAC. At the default of 20000 a second, this checking takes at most about 6% of one core on a 2017 laptop CPU, or 14% with the CPU held at its base clock. Beyond the budget, requests are dropped silently, and a forged flood crowds out Clients’ Setup Requests until it stops. Lower the budget on a slower host.

A key holder’s flood. Authentic Setup Requests reach Admission, which costs far more. Each Key Table row has its own budget, key_setup_burst and key_setups_per_second (1000 a second by default), and Unauthenticated Mode counts as one row. Requests beyond it are dropped after their HMAC, so one key can’t make the Server fall behind, though floods on many keys together still can.

Unactivated Test Connections have a share of their own, max_unactivated_test_connections, by default half of max_test_connections and at least test_connections_per_test. When the share is full, the Server closes the oldest Unactivated Test Connection of the key holding the most. So a flood on one key evicts its own, and other keys’ Clients keep their place until they activate. This is a fair share, not a guarantee:

• A key’s flood keeps out that key’s own Clients whose round trip is longer than the time the flood takes to fill the share. At the key’s default budget, that is Clients about 128 ms or more away.
• A flood split over several keys takes a share from every key that holds more than its part.
• Raising the share, for example to 256, needs more keys to displace another key’s Test, at the cost of more sockets and memory, and at least 512 Ephemeral Ports with the default cap.

To spot a flood, watch key_id on TestConnectionAdmitted and unactivated_test_connections_evicted in Statistics. Remove or expire a key that floods, then restart the Server.

Places for activated Tests. A Test’s first activation reserves places in max_test_connections for all its Test Connections. If they no longer fit, the whole Test is refused, so no Test starts with only part of its Test Connections. Activated Tests can fill the cap, but a Setup flood that never activates can’t.

The Admitted Rate Cap counts the maxBandwidth each Test states, in each direction, from its first activation to its end, whatever it sends. Set require_max_bandwidth with it, so that every Test counts. One Test without an Operator Key may state at most max_test_share of the cap, half by default.

Key handling

Formats. A key file whose name ends in .toml is a TOML Key Table. Any other file is read as an OB-UDPST udpst.keys file (crates/udpstp/src/keyfile.rs).

• TOML Key Table: one [[key]] row per Shared Key, with RFC 7210’s fields.
  • admin_key_name (unique) and key_id (the keyId, 0-255).
  • Optional kdf and alg_id. Both must be HMAC-SHA-256 if present.
  • Exactly one of key_text (used as its UTF-8 bytes) or key_hex.
  • Optional send and accept lifetimes in YYYYMMDDHHMMSSZ form.
  • Optional operator and max_test_interval, an extension to RFC 7210 (ADR 0010).
  • Unknown fields, empty keys and malformed values are errors.
• OB-UDPST files: <keyId>,<key> lines, with keys of up to 64 bytes. These files have no lifetimes, so their rows are always valid.

The Shared Key is used as raw bytes and never cut at a zero byte (ADR 0001). udpstp sets no minimum key length. Use at least 32 random bytes, for example key_hex from openssl rand -hex 32.

Permission check. On Unix, the file must be a regular file with no group or other permission bits for reading or writing (mode 0600 or stricter), owned by the user running udpstp or by root. On every platform it must be at most 1 MiB. Otherwise udpstp exits with a key file error. Running udpstp setuid is not supported. The directory holding the file isn’t checked: keep it writable only by its owner.

Windows applies ADR 0015 to every Shared Key file loaded by either role, in either format (Conformance Record key-file-private). It trusts only the running process account, SYSTEM and built-in Administrators, comparing binary SIDs without group expansion. Files that meet the supported local-NTFS policy proceed quietly. Dangerous grants to outsiders, untrusted ownership and absent/null DACLs are policy mismatches; unsupported storage, rights, flags or ACE types, malformed descriptors and inspection failures are unverified. Unsupported data takes precedence over a mismatch. Both are refused before content is read, with exit status 51 and distinct diagnostics naming the file, reason and remediation, without claiming effective exposure. Client errors use stderr with no JSON result; Server errors reach stderr and any configured startup log as StartupError. Read and parse errors retain their existing handling. Ordinary --print-config validates keys too. Its --settings-only modifier previews settings without opening keys, logs or listeners and establishes no key readiness.

Native inspection and content reading use the same handle with read-only sharing. The adapter owns its initialized, aligned descriptor buffers and temporary token handle, bounds descriptor size to 128 KiB and ACE count to 1,024, and returns owned data. Only udpstp-key-permissions/src/native.rs permits own unsafe; descriptor decoding, application policy, protocol core and network runtime forbid it. Ordinary content writers and replacement opens conflict with the reader, but ACL changes remain possible. The assessment does not determine universal effective access, freeze permissions, protect writable containing storage, handle impersonation or cover remote/non-NTFS storage. Runtime PowerShell and unmaintained ACL wrappers remain rejected.

Use the manual reconstruction for a dedicated profile folder, or the service installer for unattended hosting. The procedure removes pre-existing explicit grants and examines the actual file, not only its parent. Copy files into protected storage rather than moving them with their old permissions, then reconstruct their ACLs. Never keep them under a folder created directly under C:\, where ordinary accounts can modify the containing storage.

Zeroization. SharedKey and DerivedKeys wipe their bytes when freed, and so do the KDF’s intermediate blocks and the buffer the key file is read into (zeroize, and the hmac crate’s zeroize feature). That buffer is sized once and never reallocated, and a file that grows while it is read is refused. Limits:

• Copies made inside the TOML parser are beyond udpstp’s reach.
• Keys are not locked in memory, so they can reach swap.
• A core dump taken while the process runs can contain the Key Table.

Disable core dumps for the service.

Operator Keys. A Server Key Table row marked operator = true is an Operator Key. Privileges come from the row that verified the Setup Request, not from anything the Client claims. An Operator Key may carry its own max_test_interval for Tests longer than 60 s. Give Operator Keys their own keyIds, and never share them with Consumers.

Lifetimes and rollover (ADR 0010, crates/udpstp-core/src/keys.rs):

• The Server accepts a keyId only through a row whose accept lifetime includes the Server’s clock. The Client sends with the valid row that has the newest send lifetime start. If several rows are equally new, the Client refuses to guess, and --key-id must pick one.
• Two rows may share a keyId only if neither their send nor their accept lifetimes overlap. The Key Table is refused at start-up otherwise.
• A Test Connection keeps its Derived Keys when its row expires mid-Test.
• For a smooth rotation, give the new key a new keyId whose lifetimes overlap the old one’s, then retire the old keyId.
• The key file is read once at start-up. Adding rows in advance, with future lifetimes, avoids restarts.

Authentication Modes and Unauthenticated Mode

Mode 1 authenticates the Control Phase: the Setup and Activation exchanges in both directions, and the Null Request.

• It proves that the peer holds the Shared Key, protects every Control Phase field from modification, and rejects replays older than ±5 s.
• It does not authenticate Load PDUs or Status PDUs, so an on-path attacker can forge Data Phase traffic.
• It does not cover IP addresses or ports.
• It detects a replay inside the window only on the Server that saw the request, with its replay cache.
• All Consumers who share one Shared Key look the same to the Server.

Mode 2 adds authentication of every Status PDU, in both Test directions. It protects the rate decisions and the STOP signal carried in Status PDUs. Load PDUs are never authenticated, by design of the RFC. The Status PDU’s sender signs it with its own Derived Key, the Client’s in a Downstream Test and the Server’s in an Upstream one; the receiver checks authMode, keyId, the digest and the time window, and ignores one that fails, so its Watchdog ends the Test if they keep failing (crates/udpstp-core/src/data_phase.rs). The Client uses mode 2 by default and never falls back to mode 1 on its own, so an attacker can’t downgrade a Test; mode 1 is chosen with --auth-mode 1, or for one Server with --mode-1-server. A Server that rejects mode 2 with an AUTHINV it can’t sign, as OB-UDPST does, is reported as probably not supporting it (Event::AuthMode2Unsupported). Two limits remain. A replayed Status PDU, stale but authentic, still counts as heard, so an on-path attacker who drops the genuine ones can keep the Load Sender sending blind for a few seconds more before its Watchdog ends the Test. And a Status PDU names no Test Connection, so two Test Connections whose Derived Keys match (the same key and the same Setup second, as in a Multi-Connection Test) accept each other’s Status PDUs: an on-path attacker can move one’s into the other. Both follow from RFC 9946’s design.

Unauthenticated Mode is OB-UDPST’s authMode 0. RFC 9946 does not define it: IANA lists the value as “Not used”. udpstp offers it only so that it can interoperate with default OB-UDPST installations, and only when both ends opt in: udpstp client --unauthenticated, and allow_unauthenticated = true (or --allow-unauthenticated) on the Server. A Server that allows it still accepts mode 1. Unauthenticated Mode protects nothing. Anyone who can send a datagram to the Server can start a Test, parameters and results can be forged, and there is no replay protection. Its requests spend no per-Source budget, and every coded rejection goes to the claimed source address, so a spoofed request makes the Server answer a victim, bounded only by the global budget for unverified Setup Requests. Beyond that and the Test Connection caps, Unauthenticated Mode has no defence. Enable it only on networks where every host is trusted.

Silent Rejection and Troubleshooting Mode. By default, authentication failures get no reply, so a prober learns nothing. Troubleshooting Mode (troubleshooting = true, or --troubleshooting) answers them with an unsigned Setup Response carrying AUTHREQ, AUTHNC, AUTHINV, AUTHFAIL or AUTHTIME, for debugging. AUTHTIME, whose digest is valid, is signed. It is off by default, and while it is on the Server warns at startup and every minute (Event::TroubleshootingModeOn). It answers at most 10 failures a second. An unknown keyId and a wrong digest both get AUTHFAIL, but anyone can learn whether keys are configured (AUTHNC) and unauthenticated Tests allowed (AUTHREQ), and a spoofed request gets its reply, so turn it off after debugging. Activation Requests that fail verification stay silent even then: a Test Connection whose Setup was authentic rarely fails there.

Out of scope

• Confidentiality. UDPSTP does not encrypt. An observer on the path sees addresses, keyIds, Test parameters, Status PDU contents and so the results. Use a VPN or a private network if this matters.
• Key distribution and identity. How Shared Keys reach Clients is outside RFC 9946 (§5.4), and outside udpstp. A keyId identifies a key, not a person.
• An on-path attacker who drops or delays traffic. Such an attacker can always prevent a Test or lower its result. A capacity measurement reports what the path delivers, including the attacker’s interference.
• Volumetric floods at the Server’s link. Traffic that saturates the link before it reaches the host needs upstream filtering.
• Compromised hosts. An attacker with root, or with the service account, can read keys and change results.
• A key’s holders against each other. All Clients sharing a Shared Key look the same to the Server, and so does everyone where Unauthenticated Mode is on. A key holder’s flood can keep that key’s own distant Clients from starting Tests, and a flood split over several keys takes a share from every key. No defence finer than the key is possible. Admission under load explains the limits.
• Consent of the measured path. RFC 9946 §11 requires cooperating hosts. udpstp enforces this through key possession, and Server administrators decide who receives keys. Quotas of Tests and load bytes are optional.

Hardening for Server administrators

1. Keep authentication on. Leave allow_unauthenticated off (the default) on any Server that is reachable from networks you don’t control.
2. Limit who can reach the Server. Allow-list Client networks in your firewall where you can. Give each population of Clients its own key, and keys only to Clients you trust. Admission under load explains what the Server’s own limits hold back.
3. Protect the key file. On Linux and macOS, keep it owned by the service account with mode 0600. On Windows, udpstp refuses a file that other accounts can access; set it up as udpstp on Windows shows. Use random keys of at least 32 bytes, a separate key per population of Clients, and separate Operator Keys. Use lifetimes to plan rotations.
4. Open only what is needed. A stateful firewall needs only the Standard Port (24601) open inbound: the Null Request the Server sends from each new Ephemeral Port lets that Test Connection’s traffic back in (tested with nftables). A stateless filter, a NAT and Windows Defender Firewall need the Ephemeral Port range too, 49152-65535 by default. Narrow it with ephemeral_ports so that the rule stays small. Open the firewall has the details.
5. Run unprivileged. The Standard Port is above 1024, so the Server needs no root privileges or capabilities. Run it under a dedicated account with core dumps disabled (for example ulimit -c 0).
6. Synchronise clocks. Run NTP or similar. Clocks more than 5 s apart make every authenticated Test fail.
7. Handle the logs. The Server logs its events to standard output, human-readable or as JSON (log_format), including discarded requests and full Client addresses; startup warnings go to standard error. Events an attacker can cause are limited to ten of a kind and a hundred in all every 10 s, the rest counted. Every statistics_interval (60 s by default) a Statistics event gives the counters since start: Tests and Test Connections admitted, those active, refusals and drops by reason, authentication failures, rate-limited Setup Requests and stale Status PDUs; each Test ends with a TestSummary of its Client address, keyId, direction, parameters, bytes and result, limited like the events above when none of its Test Connections was activated. Send the output to a log system that rotates it, and treat it as personal data. address_privacy shows Client addresses in full (the default, for abuse handling), pseudonymized (anon- and 8 bytes of HMAC-SHA-256 over the IP address, keyed with the hex key in address_privacy_key_file, so one Client keeps one pseudonym while the key is kept) or truncated to the IPv4 /24 or IPv6 /48.
8. Use the hardened unit or the container image. contrib/systemd/udpstp-server.service runs the Server as a user systemd creates when it starts, with no capabilities, a read-only view of the system, UDP and the journal’s socket only, a system call filter and core dumps off, and passes it the Key Table as a credential; scripts/systemd-check.sh checks it with systemd-analyze verify and security. contrib/container/Containerfile builds an image with no shell that runs the Server as uid 65532. Run it as a service has the details.

Verify a release’s build provenance

Release checksums detect a download that differs from the published hash. Build attestations add a separate, signed check of where it was built. The install scripts don’t perform this check.

Use the GitHub CLI 2.97.0 or later, signed in with gh auth login. Download the archive yourself, since the install scripts delete theirs. For Linux on x86_64:

tag=v0.1.0
archive=udpstp-$tag-x86_64-unknown-linux-gnu.tar.gz
gh release download "$tag" --repo pederbe/udpstp --pattern "$archive"
gh attestation verify "$archive" --repo pederbe/udpstp \
  --signer-workflow pederbe/udpstp/.github/workflows/release.yml \
  --source-ref "refs/tags/$tag"

For Windows, in PowerShell:

$tag = 'v0.1.0'
$archive = "udpstp-$tag-x86_64-pc-windows-msvc.zip"
gh release download $tag --repo pederbe/udpstp --pattern $archive
gh attestation verify $archive --repo pederbe/udpstp --signer-workflow pederbe/udpstp/.github/workflows/release.yml --source-ref "refs/tags/$tag"

Use your release’s tag and archive name, and continue only if verification succeeds. This checks the signed provenance against the repository, the Release workflow and the source tag. It doesn’t prove the code is safe or stop a tag from moving. GitHub’s attestation guide explains the guarantees.

Stable interfaces

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 1.0. The decision and its reasons are ADR 0013; every change is in the changelog.

What is stable

Stable from 1.0

Until then, a 0.x minor release may rename or remove one of these, with no deprecation period. The changelog lists each change under Changed or Removed, so read it before upgrading a script or a configuration file.

What is not

Human output adapts to the width of the terminal it is written to. Redirected output and a terminal whose width is unknown use 80 columns. Help, diagnostics and progress wrap with continuation indentation; results use a full table when it fits and grouped tables otherwise, with repeated Sub-Interval numbers and a nearby legend. An identifier wider than the terminal stays intact on a continuation line so it remains copyable. The human Server log marks continuation lines with |; each event still starts with its own timestamp and level. JSON and configuration output are unaffected by this layout.

• Human-readable text: the text results, progress lines, the wording of warnings and errors, --help, and the human log’s messages and layout. Parse the JSON results and the JSON log instead.
• Free text inside the JSON: ErrorMessage, ErrorMessage2, a warning’s Message, the log’s message and error fields. Use ErrorStatus, a warning’s Code, the log’s event and reason.
• The format of udpstp --version.
• UDPSTP_FAULTS and UDPSTP_BLESS, which exist for udpstp’s own tests.
• UDPSTP_KERNEL_TX_TIMESTAMPS, an experimental setting for precision tests: set to 1 on Linux, a Load Sender asks the kernel to timestamp what it sends, and the Client’s JSON results add udpstp.KernelSendTimestamps (Samples, LagP50Us, LagP99Us, LagMaxUs: how much later than lpduTime the kernel sent them). Set to kernel-count, it asks for the same timestamps matched by the kernel’s own count of the messages on every kernel, as before Linux 6.13, rather than by numbers the messages carry, so a result can be checked on that send path. The variable, its values and the block may change or go in any release.
• UDPSTP_ENGINE_CATCH_UP_US, an experimental setting for measurements: the Data Phase Engine’s catch-up budget in µs (ADR 0012), in place of 1 ms (2 ms on Windows). It may change or go in any release.
• UDPSTP_ENGINE_THREADS and UDPSTP_ENGINE_GROUPING_US, experimental settings for measurements of a Linux Server, whose Data Phase Engine runs on a pool of Engine Threads: the most Engine Threads the pool starts, in place of the CPUs the process may use; and the pool’s wake-up grouping window in µs, 0 (none) by default, since no measurement has yet shown a window worth making the default (ADR 0008). They may change or go in any release.
• UDPSTP_ENGINE_HOLD_OFF_US, an experimental setting for measurements: on Linux it sets the Data Phase Engine’s receive hold-off in µs, 0 for none, in place of the one derived from the receive buffer, and a Load Receiver takes it after every turn that read datagrams (a Load Sender, when flooded), where it takes the derived one only when more than one datagram is due within it. It may change or go in any release.
• The library crates (udpstp-wire, udpstp-core, udpstp-runtime, udpstp-key-permissions): they follow Cargo’s semver rules only, and aren’t a supported interface in 0.x.

Terminal color

--color auto|always|never is global: it can precede or follow client or server. The default, auto, checks stdout and stderr independently and styles only a terminal that supports color. A nonempty NO_COLOR or TERM=dumb disables automatic styling; an empty NO_COLOR does not. always and never override these environment defaults. CLICOLOR, CLICOLOR_FORCE and CI do not override this policy. never removes bold, dimming, colors and decorative status symbols. Redirected automatic output keeps the plain presentation.

The same policy covers help, parser errors, startup diagnostics, Client progress and text results, and human Server console logs. always keeps styling when human output is redirected. JSON results, JSON logs, printed TOML configuration and daily log files stay plain in every mode, including Windows service files. Startup diagnostics copied to a log file stay plain there while their stderr copies follow stderr’s policy.

Colors use RGB foregrounds on the terminal’s default background: purple #bd93f9, blue #5cb8ff, green #5af78e, amber #f39c12, red #ff5c57 and gray #70788c. Terminals with fewer colors may approximate them. Client results show one aligned Sub-Interval table when it fits, or two metric groups with repeated Sub-Interval numbers. Very narrow groups become labelled values. Final metrics show each Capacity Mode’s maximum once, followed by supporting measurements, warnings and the aggregate Test outcome. Labels remain understandable without color; a high rate alone is no reason for green. Symbols supplement the outcome text. Styling preserves copyable values and table alignment, with wrapping adapted to the displayed symbol width.

How a stable interface changes

These rules cover the interfaces stable from 0.1.0, and from 1.0 the command line, settings and JSON log too.

• Additions come in a minor release: new options, settings, JSON keys, log events and fields, enumerated values, exit statuses and Key Table columns. Your tools should ignore what they don’t know: an unknown key, field, event or value, and treat an unknown non-zero exit status as a failure.
• A renamed or removed input (an option, a setting, a value, a Key Table column) is still accepted for one minor release, with a warning on stderr naming its replacement. A name deprecated in 0.3.0 works through 0.3.x and may go in 0.4.0.
• A renamed or removed output (a log event, field or value, a JSON key or value) is written under both names for one minor release, then only under the new one.
• A default changes in a minor release, announced in the changelog of the minor release before. A security fix may change one at once; the changelog says so.

Each is in the changelog, under Added, Deprecated, Changed or Removed. Read it before upgrading across a minor release.

Exit statuses

A Client’s exit status is its ErrorStatus, the one OB-UDPST reports, except that a Test that completed with only warnings exits 0. udpstp’s own statuses use values OB-UDPST leaves unused. New statuses may be added; an assigned one never changes meaning.

Running a Test says what to do about each.

stdout and stderr

Windows Shared Key files must meet ADR 0015’s supported local-NTFS policy. Mismatches and unverified permissions are distinct key file errors (51), refused before content reading, with actionable reasons that do not claim effective exposure. Client errors leave stdout empty; Server errors also reach a configured daily log as StartupError. Ordinary --print-config validates keys. Its --settings-only modifier previews settings and establishes no key readiness; it requires --print-config and conflicts with --windows-service. See Key handling.

Key files

A TOML Key Table that is valid today keeps its meaning in every later version: columns are added, never removed or read differently. It may start with format = 1, which a file without it is too.

The reverse doesn’t hold: a file with a column this version doesn’t know, or a higher format, is refused rather than read in part, since the column it would skip may be a restriction such as a lifetime or a Quota. Upgrade every Server and Client that reads a Key Table before you add a new column to it. Key files lists the columns.

OB-UDPST udpst.keys files are read as OB-UDPST reads them. The pseudonym key file is hexadecimal digits, 16 bytes or more, with whitespace around them and nothing else.

Address pseudonyms

With address_privacy = "pseudonymize" (the Server) or --address-privacy pseudonymize (the Client), an address shows as anon- and the lowercase hexadecimal of the first 8 bytes of HMAC-SHA-256 over the IP address’s bytes, keyed with the pseudonym key: 4 bytes for IPv4, including an IPv4-mapped IPv6 address, and 16 for IPv6. The port is left out. truncate shows the IPv4 /24 or IPv6 /48.

Container images

Each published release provides ghcr.io/pederbe/udpstp:<version>, such as :0.1.0, which never changes. :latest follows releases that are not marked as pre-releases, including one that ends a deprecation period. Pin :<version> and upgrade on purpose.

Command line

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 --help print the same.

$ udpstp --help
Measure IP-Layer Capacity with UDPSTP (RFC 9946): run a Test as the Client, or
serve Tests as the Server

Usage: udpstp [OPTIONS] <COMMAND>

Commands:
  client  Run a Test against one or more Servers
  server  Serve Tests: answer Clients' Setup and Activation Requests and run
          their Test Connections
  help    Print this message or the help of the given subcommand(s)

Options:
      --color <COLOR>  Terminal styling: auto for capable terminals, always for
                       redirected human output too, or never for plain text
                       [default: auto] [possible values: auto, always, never]
  -h, --help           Print help
  -V, --version        Print version

udpstp client

Runs a Test. Running a Test shows the options in use.

Usage: udpstp client [OPTIONS] <SERVER>...

udpstp server

Serves Tests. Every option also has a setting in the configuration file (Server configuration); an option given on the command line replaces the file’s value. Hosting a Server shows them in use.

Usage: udpstp server [OPTIONS]

Server configuration

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. This page is generated from the settings’ own documentation and from udpstp server --print-config, which prints the effective settings as TOML and exits.

Defaults

With no file and no options, --print-config prints:

listen = []
port = 24601
allow_unauthenticated = false
checksum = false
jumbo = true
traditional_mtu = false
server_mtu = 1500
ephemeral_ports = "49152-65535"
delay_var_statistic = "maximum"
tests_per_source = 1
max_test_connections = 256
test_connections_per_test = 24
max_test_share = 50
require_max_bandwidth = false
troubleshooting = false
unverified_setups_per_second = 20000
source_setup_burst = 48
source_setups_per_second = 5
key_setup_burst = 1000
key_setups_per_second = 1000
allowed_dscp = [0]
max_start_row = 100
quota_period = 3600
socket_buffer_size = 2097152
dont_fragment = true
log_format = "human"
address_privacy = "full"
statistics_interval = 60

A setting shown as “none” is absent by default and printed only when set.

Settings

Hosting a Server explains the settings in use, and Command line lists the option for each.

Server log

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 the log up.

Event names, field keys and the values below settle during 0.x and become stable from 1.0, as Stable interfaces explains. New ones may appear, so ignore those you don’t know.

Format

The log is human-readable by default:

2026-09-26T14:46:25.579954Z  INFO listening on 0.0.0.0:24700 event="Listening" address=0.0.0.0:24700
2026-09-26T14:46:26.621011Z  INFO Test Connection admitted event="TestConnectionAdmitted" test_connection_id=1 client="127.0.0.1:51801" mc_ident=60798
2026-09-26T14:46:26.621208Z  INFO Test Connection activated event="TestConnectionActivated" test_connection_id=1 direction="Downstream"
2026-09-26T14:46:37.129642Z  INFO the Test Connection's Data Phase completed event="DataPhaseEnded" test_connection_id=1 reason="Completed" fast_paths="sendmmsg,UdpGso,recvmmsg,KernelRxTimestamps,epoll"
2026-09-26T14:46:37.129734Z  INFO Test ended: Completed event="TestSummary" client=127.0.0.1:51801 mc_ident=60798 test_connections=1 direction="Downstream" test_interval=10 … bytes_sent=1144801422 bytes_received=1110936104 ip_layer_sender_bit_rate=933913704 result="Completed"

With log_format = "json", each line is one JSON object:

{"timestamp":"2026-09-26T14:51:10.061951Z","level":"INFO","message":"Setup Request refused","event":"SetupRequestRejected","client":"anon-63d4269f2e4b0c0d","reason":"MaxBandwidthRequired"}

Every event has an event name and its data in fields. A field means one thing wherever it appears, and is left out when an event has nothing for it. The message is for people and may change, so filter on event and the fields.

In a terminal, the human log colours its level labels: INFO cyan, WARN yellow and ERROR red. --color auto|always|never controls this, as Terminal color describes. JSON logs and log files are always plain.

Where it goes

The log goes to standard output, and startup warnings and errors to standard error. With log_file set, the Server writes a new file each day named from it, so /var/log/udpstp/server.log gives server.2026-10-01.log (the date in UTC). It keeps the last 14, and copies its startup errors and warnings into them as StartupError and StartupWarning.

Give log_file a folder of its own: the Server deletes the oldest file whose name starts and ends as the log’s does, whatever wrote it. A Windows service always logs to files. Elsewhere, leave the log to the service manager: logrotate’s renames would fight the Server’s own files, and SIGHUP stops the Server rather than reopening them.

Events an attacker can cause are rate-limited, ten of a kind every 10 s, so a flood can’t fill the disk. The rest are counted in a Suppressed event.

Fields

Events

Starting and stopping

Setup and Activation

The Data Phase

Problems and counts

DataPhaseEngines

executor is pool on Linux, where Engine Threads each serve many Test Connections, or per_test_connection on Windows and macOS, where each Test Connection has an Engine Thread of its own.

For pool, engine_threads is the most it starts: one for each CPU the process may use, with a fractional cgroup CPU quota rounded down, so a container limited to 1.9 CPUs gets 1. error is a warning when the CPUs the process may use couldn’t be found.

grouping_us is the pool’s wake-up grouping window, 0 by default and for per_test_connection. The experimental variables UDPSTP_ENGINE_THREADS and UDPSTP_ENGINE_GROUPING_US override engine_threads and grouping_us.

DataPhaseEnded

reason says how the Data Phase ended (below). error names the failure when the Data Phase Engine failed.

fast_paths lists, comma-separated, the fast paths the engine sent Load PDUs, read datagrams and waited with. It is empty except on Linux, where it can hold:

• sendmmsg and UdpGso when the Server sent Load PDUs (not in an Upstream Test);
• recvmmsg and KernelRxTimestamps;
• epoll when one of the Server’s Engine Threads served the Test Connection.

With the experimental UDPSTP_KERNEL_TX_TIMESTAMPS=1 on Linux 6.13 and later, each message goes with a sendmsg call of its own, so UdpGso appears without sendmmsg, unless the kernel refuses the timestamps. A Load Sender’s event then adds send_lag_samples, send_lag_p50_us, send_lag_p99_us and send_lag_max_us: how much later than its lpduTime the kernel sent the Load PDUs it stamped. burst_lateness_p99_us, also experimental, is how late a Load Sender wrote its Send Plans, 99th percentile.

receive_buffer_overflows, on Linux, counts datagrams the OS discarded at the socket before the Server read them. In an Upstream Test the Client counts them as lost.

TestSummary

A TestSummary has:

• client, mc_ident, key_id (in an authenticated mode) and test_connections;
• bytes_sent and bytes_received, the UDP payload bytes of the Load PDUs the Server sent and received;
• ip_layer_sender_bit_rate, in bit/s, when the Server was the Load Sender;
• what the Server didn’t send as Load Sender, over all its Test Connections: skipped_bursts, skipped_datagrams and skipped_bytes when it fell behind, and withheld_bursts, withheld_datagrams and withheld_bytes when the send buffer was full;
• receive_buffer_overflows, on Linux, summed over its Test Connections;
• result: Completed; ServerStopping for a Test cut short when the Server stopped; how the first Test Connection that didn’t complete ended (a DataPhaseEnded reason, ActivationWatchdogExpired, UnactivatedTestConnectionEvicted, or ActivationRequestRejected with its reason); or NotActivated.

A Test that was activated adds its direction and parameters: test_interval (s), sub_interval and trial_interval (ms), low_thresh and upper_thresh (ms), seq_err_thresh, slow_adj_thresh, high_speed_delta, ignore_ooo_dup, one_way_delay_variation and random_payload (booleans), rate_adj_algo (B or C), dscp, sr_index_conf and sr_index_is_start.

Statistics

Statistics counts since the Server started: tests, test_connections, active_test_connections, authentication_failures (requests, and Status PDUs in mode 2), rate_limited (Setup Requests over a budget), stale_status_pdus, setup_requests_ignored and unactivated_test_connections_evicted.

It has a report number. One StatisticsRefusals line with the same report follows for each kind of refusal counted so far, with kind (the event that logged it), its reason and count. The counts overlap: a request refused for its authentication counts in authentication_failures and in its StatisticsRefusals, and one over a budget in rate_limited too.

Reasons

• For DataPhaseEnded, how it ended: Completed, Unconfirmed (the Client didn’t confirm the STOP), StoppedByClient, Watchdog, OverRate (the Client sent above 1.5 times its rate), Stopped (the Server stopped it) or DataPhaseEngineFailed.
• For a Setup Request: TestsPerSource, TestConnectionsPerTest, TestConnections, MaxBandwidthRequired, CapacityExceeded, SocketUnavailable, QuotaExceeded, SourceBudgetExhausted, BadVersion, JumboMismatch, TraditionalMtuMismatch, Malformed, MulticastOrBroadcast, ChecksumFailed, Replayed, ReplayCacheFull, UnverifiedBudgetExhausted, or a Multi-Connection field’s fault: MultiConnectionIdentZero, MultiConnectionIndexNotBelowCount, MultiConnectionIndexInUse, MultiConnectionCountDiffers, MultiConnectionAuthModeDiffers, MultiConnectionKeyIdDiffers.
• For an Activation Request: InvalidCommand, MixedDirection, UnacceptableParameter, FixedRateNeedsOperatorKey, TestsPerSource, TestConnections, MaxBandwidthDirection, CapacityExceeded, QuotaExceeded, AuthModeMismatch, KeyIdMismatch, MulticastOrBroadcast, ChecksumFailed, Replayed, ReplayCacheFull, NotFromClient, Malformed.
• For an authentication failure, whether Troubleshooting Mode answered it or not: AuthenticationRequired, AuthenticationNotConfigured, AuthenticationModeInvalid, AuthenticationUnknownKeyId, AuthenticationKeyOutsideLifetime, AuthenticationDigestFailed, AuthenticationTimeOutOfWindow.

JSON results

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 and times printed the way OB-UDPST prints them, so tools written for OB-UDPST’s formatted JSON (-f jsonf) keep working. Progress goes to stderr, so stdout holds only the JSON.

From 0.1.0 the key names, types and enumerated values are a stable interface, the extension’s included; the free text in ErrorMessage, ErrorMessage2 and a warning’s Message is not.

What is the same

• Top-level keys: IPLayerMaxConnections, IPLayerMaxIncrementalResult, IPLayerCapSupported, then Input and Output once the Test was activated, then ErrorStatus, ErrorMessage and ErrorMessage2.
• Output: BOMTime to TimestampResolutionUsed, then IncrementalResult, Summary, ModalSummary, AtMax, ModalResult, ECNBleachingDetected, then EOMTime and Status.
• Printed forms: delays in seconds from whole milliseconds (0.011), Mbps and percentages with 2 decimals, ratios with 9, zero as 0.0, times as UTC with microseconds (2026-09-25T14:13:20.712759Z), and OB-UDPST’s tab-indented layout.
• A Test that never activated has only the top-level IPLayer* keys and the error fields; one that didn’t complete (ErrorStatus 200 and up) has only Output’s header and trailer.

Tests compare the key paths, their order and each value’s printed form with OB-UDPST’s vendored examples 01, 06, 11 and 12 (testdata/obudpst-9.1.0/json_examples).

Fields udpstp never measures

They carry OB-UDPST’s own value for the feature being off:

ClientIPAddress is "" today: the Client’s socket is bound to a wildcard address, which says nothing about the one used. When it holds an address, it follows --address-privacy (below).

Where udpstp differs

Each is an OB-UDPST Difference with its own Conformance Record.

• AtMax and ModalResult are the Maximum IP-Layer Capacity, which meets the Performance Criterion. OB-UDPST’s maximum, the Highest IP-Layer Capacity, is in the extension. A Capacity Mode with no maximum has no AtMax (or ModalResult), never zeros, and the Test gets ErrorStatus 49.
• ErrorStatus is the most severe status, where OB-UDPST keeps the last one written: 200 for a Test that didn’t complete, with its cause in ErrorMessage2; for a completed Test the most severe warning: 49 no valid maximum, 4 nothing received for 1 s, 5 the peer stopped receiving, 3 the peer missed Status PDUs, 2 Status PDUs missing here, 6 invalid PDUs. The exit status of a completed Test is 0 all the same.
• An interrupted Test (Ctrl-C, a signal to stop, or a failed write to standard output while the Test ran) has ErrorStatus 204 and the results so far, its Test Connections having sent their STOP; OB-UDPST stops without one and exits 255.
• A Test that didn’t complete keeps its measured Sub-Intervals in udpstp.SubIntervals, with the same fields and units as Output.IncrementalResult, and its minimum RTT in udpstp.MinRTT. Output still has only its header and trailer. These partial results require the extension, which is on by default.
• SoftwareVersion is "udpstp <version>"; ControlProtocolVersion is 20.
• Delay fields of a Sub-Interval without samples are 0, as OB-UDPST writes, and the extension lists those Sub-Intervals; Summary is computed from real samples only.
• A Sub-Interval never measured is left out of IncrementalResult and listed in the extension; Interval is its subIntSeqNo.
• IPLayerCapacity is over the nominal Sub-Interval (RFC 9097 §5.3); OB-UDPST divides by the measured one.
• A name that doesn’t resolve, or a Client that can’t start, prints no JSON; OB-UDPST prints JSON with 255.

The extension

One last object, "udpstp", holds results OB-UDPST’s schema lacks; --json-extension=false leaves it out for tools that reject unknown keys:

Not yet

• Downstream output follows OB-UDPST’s code, where only Role changes; every OB-UDPST example is an Upstream Test, so a Downstream Test’s full structure hasn’t been compared with OB-UDPST’s.
• OB-UDPST’s brief (jsonb) and summary-only (-s) forms.

ClientIPAddress follows --address-privacy: the address in full (the default), anon- and a keyed hash of it (pseudonymize, with --address-privacy-key-file), or its IPv4 /24 or IPv6 /48 (truncate).

Exit statuses

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 is ErrorStatus, warnings included. Generated from the documentation of crates/udpstp/src/exit.rs.

A Multi-Connection Test reports as OB-UDPST does: once any Test Connection completed, success with the most severe warning of all; if none did, the first Test Connection’s error, by mcIndex, or 200 when none had one of its own (ERROR_CONN_MIN, which keeps an earlier error).

Our own codes sit in OB-UDPST’s connection-error range (200 plus an offset), which uses only 200, away from the ranges that add an IANA registered cmdResponse. Codes above 128 read like a shell’s “killed by signal” status; that comes with matching OB-UDPST. OB-UDPST keeps the last warning and lets a warning replace an error; we keep the most severe.

Conformance Records: exit-zero-with-warnings, exit-own-error-statuses, exit-most-severe-warning, client-interrupt.

Key files

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 file is read as an OB-UDPST udpst.keys file.

TOML Key Tables

A TOML Key Table has one [[key]] row per Shared Key:

[[key]]
admin_key_name = "customers-2026"
key_id = 1
key_hex = "5b0c0e8d6f7a41c2b9d3e4f5061728394a5b6c7d8e9fa0b1c2d3e4f506172839"
accept_lifetime_end = "20270101000000Z"
send_lifetime_end = "20270101000000Z"
tests_per_quota_period = 12

Unknown fields, empty keys and malformed values are errors. udpstp sets no minimum key length, but use at least 32 random bytes.

A file may start with format = 1, the format described here, which is also what a file without it has. A valid file keeps its meaning in later versions of udpstp: they may add columns, but never change what one means. A column this version doesn’t know, or a higher format, is refused rather than half read, so a file written for a newer udpstp fails to load instead of losing a restriction (Stable interfaces).

OB-UDPST key files

An OB-UDPST file has one <keyId>,<key> line per key, with keys of up to 64 bytes:

1,a-long-random-secret-for-consumers

Its rows have no lifetimes, Operator Keys or Quotas, so they are always valid.

Lifetimes and rotation

• The Server accepts a keyId only through a row whose accept lifetime includes the Server’s clock.
• The Client sends with the valid row whose send lifetime started most recently. If several rows tie, the Client refuses to guess, and --key-id must pick one.
• Two rows may share a keyId only if neither their send nor their accept lifetimes overlap. Otherwise the Key Table is refused at startup.
• A Test Connection keeps its keys when its row expires during a Test.
• The Server reads the file once at startup. Add rows in advance, with future lifetimes, to rotate keys without a restart. Give the new key a new keyId whose lifetimes overlap the old one’s, then retire the old keyId.

Permissions

A key file must be private, or udpstp refuses it with exit status 51 before reading any key.

• Linux and macOS: a regular file of mode 0600 or stricter, owned by the account running udpstp or by root.
• Windows: a local NTFS file that only the running account, SYSTEM and Administrators can access. udpstp on Windows shows how to set this up.

On every platform the file must be at most 1 MiB. Keep it in a folder only its owner can write.

Recorded choices

• lifetimes are written YYYYMMDDHHMMSSZ (key-lifetime-format).
• key_text is an extension, and key_hex accepts either case (key-text-extension).
• the KDF and AlgID columns are HMAC-SHA-256, and the Operator marker and max_test_interval extend RFC 7210 (key-table-alg-id, key-table-operator-extension).
• OB-UDPST files are read like OB-UDPST reads them, with two exceptions (obudpst-key-file-reading).
• a key file group or others can read or write is refused on Unix, and Windows policy mismatches or unverified permissions are refused (ADR 0015; conformance: key-file-private).
• on Unix a key file must be owned by the user running udpstp or root (key-file-owner).
• a key file over 1 MiB is refused (key-file-size-limit).

Platform differences

udpstp runs on Linux, macOS and Windows. A few features depend on what the operating system offers. Installing udpstp lists the release binaries.

Not yet measured

The Server’s pool of Engine Threads has been measured carrying 150 Test Connections of 4 Mbit/s each on one CPU core. These haven’t been measured yet:

• 1,000,000 Load PDUs a second on one Server, or 10 Gbit/s in all;
• Test Connections of 500 Mbit/s or more each sharing an Engine Thread. Give a Server that carries high-rate Multi-Connection Tests at least as many CPUs as such a Test has Test Connections.

Glossary

Press Ctrl+F (Command+F on macOS) to find a term on this page.

The terms udpstp uses, in its code, output, docs and issues, from the repository’s GLOSSARY.md. Each term has its own anchor, so it can be linked. Avoid lists words udpstp doesn’t use for it.

Roles

Client

The endpoint that starts every Test by sending a Setup Request to the Server’s Standard Port.

Avoid: Initiator, controller

Server

The endpoint that listens on the Standard Port, admits Test Connections, and runs the Load Rate Adjustment Algorithm in both directions of a Test.

Avoid: Responder, reflector

Load Sender / Load Receiver

The end of a Test Connection that sends Load PDUs, and the end that receives them and sends Status PDUs back. The Test’s direction decides which the Client plays.

Avoid: Src/Dst (RFC 9097 wording), sender/receiver unqualified

Client user

Whoever runs a Client and chooses its Test.

Avoid: User (unqualified)

Server administrator

Whoever runs a Server and its Key Table, and so decides which Shared Keys it accepts and which are Operator Keys (RFC 9946 §6.2.1’s server administrator).

Avoid: operator (lowercase)

Operator

A network operator measuring within its own domain, the only party RFC 9946 §4.1 lets run Fixed-Rate Tests. A Server knows one only by an Operator Key.

Avoid: Admin, privileged user

Consumer

Anyone measuring their own access (RFC 9946 §3); to a Server, any Client without an Operator Key, an unauthenticated one included.

Avoid: Subscriber (unqualified)

Tests

Upstream Test

A Test where the Client sends Load PDUs and the Server sends Status PDUs.

Avoid: Upload test, uplink test

Downstream Test

A Test where the Server sends Load PDUs and the Client sends Status PDUs.

Avoid: Download test, downlink test

Test

One measurement a Client runs in one direction: one or more Test Connections, to one or more Servers, sharing one mcIdent. A Server sees as the Test only the Test Connections that reach it from one Client address with that mcIdent.

Avoid: Speed test (unqualified), run, session

mcIdent

The non-zero pseudorandom identifier every Setup Request of one Test carries, which associates its Test Connections (RFC 9946 §6.1). Beside it, mcIndex numbers the Test Connections from 0 and mcCount says how many the Client attempts.

Avoid: Test ID, session ID

Test Connection

One Client–Server exchange of a Test, numbered by mcIndex, from its Setup Request to its end; once admitted it has its own Ephemeral Port.

Avoid: Session, flow, connection unqualified

Multi-Connection Test

A Test with more than one Test Connection, told apart by mcIndex. All its Test Connections share the Test’s direction, and the Client aggregates their results.

Avoid: Multi-flow test, parallel test

Minimum Test Connections

The fewest of a Test’s Test Connections that must be set up and keep running for the Test to go on; all of them unless the Client user sets fewer.

Avoid: Min connections, quorum

Multi-Connection Coordinator

The part of the Client that runs a Test’s Test Connections as one Test: the client process’s job in RFC 9946 §4.

Avoid: Test manager, connection pool

Search Test

A Test whose sending rate the Load Rate Adjustment Algorithm sets, starting at the default row or a requested one.

Avoid: Adaptive test

Fixed-Rate Test

A Test whose Test Connections each hold one Sending Rate Table row for the whole Test Interval instead of running the Load Rate Adjustment Algorithm.

Avoid: Static test, constant-rate test

The Server and its limits

Standard Port

The Server UDP port where Setup Requests arrive: 24601, RFC 9946’s assigned port, unless the Server is set to another.

Avoid: Control port (RFC 9946’s name for it), listen port

Ephemeral Port

The Server UDP port allocated to one Test Connection and returned as testPort in the Setup Response; all later PDUs of the Test Connection use it.

Avoid: Test port, data port

Source

Where the Server counts Tests from: the Client’s IPv4 address, or the /64 its IPv6 address is in. It stands in for the RFC’s “path”, which the Server can’t see.

Avoid: Client address (for this grouping), path (for this grouping)

maxBandwidth

The rate, in Mbps, a Setup Request says its Test Connection expects to send or receive in its direction (RFC 9946 §6.1). The Server admits it against the Admitted Rate Cap and never searches above it.

Avoid: Bandwidth (unqualified), requested capacity

Admitted Rate Cap

The most maxBandwidth the Server admits at once in one direction, summed over the Test Connections of its activated Tests.

Avoid: Bandwidth cap, capacity limit

Unactivated Test Connection

A Test Connection the Server has admitted but whose Activation Request it hasn’t yet accepted.

Avoid: Pending connection, half-open connection

Admission

The Server’s acceptance of a Setup Request within its limits, which gives the Test Connection an Ephemeral Port and a place among the Test Connections the Server serves until it ends.

Setup Request budget

The Server’s limit on how fast it takes Setup Requests: one global budget for those not yet verified, and one per Source for authentic ones.

Quota

A Server’s limit on how many Tests, and how many load bytes, one Source or one Key Table row may run per Quota Period.

Avoid: Rate limit (that is a Setup Request budget), cap (that limits what the Server admits, not what a Source uses over time)

Quota Period

The period a Quota is counted over; a Quota refills evenly over it rather than all at once when it ends.

Packets on the path

DF

The IPv4 Don’t Fragment bit, set on test traffic so it is lost rather than fragmented on a path with a smaller MTU (RFC 9946 §5); on IPv6, where routers never fragment, the sender doesn’t fragment either.

Avoid: No-fragment flag

DSCP

The Diffserv code point test traffic is marked with, which the Client asks for in dscpEcn and the Server allows or coerces to 0 (RFC 9946 §7.1). ECN, the rest of that octet, is always Not-ECT.

Avoid: TOS (for the DSCP alone), priority, packet class

MaxHops

The IPv4 TTL and IPv6 hop limit test traffic is sent with, set at each end from the expected path length so the traffic can’t stray far beyond the intended path (RFC 9946 §10).

Avoid: TTL (for the setting), hop count

Path MTU

The largest IP packet every link between the Client and the Server carries (RFC 9097 §6.5’s PMTU); with DF set, a larger one is lost.

Avoid: MTU (unqualified; see Server MTU)

Server MTU

The largest IP packet the Server is configured to send. Rows of its Sending Rate Table above 1 Gbps keep their rates with more, smaller packets when their own would be larger.

Avoid: Packet size limit, frame size

Jumbo / Traditional MTU

The two Setup Request modifiers that choose the Sending Rate Table’s packet sizes (RFC 9946 §6.1). Rates up to 1 Gbps use IP packets of at most 1250 bytes, or 1500 with Traditional MTU; Jumbo, set by default, lets faster rates use larger packets, up to 9000 bytes.

Phases and messages

Control Phase

The Setup exchange and the Activation exchange that precede measurement.

Avoid: Handshake, negotiation

Data Phase

The exchange of Load PDUs and Status PDUs, ending with the STOP exchange or with an early end such as when the Watchdog expires.

Avoid: Test phase, measurement phase

PDU

A single UDPSTP message carried in one UDP datagram, identified by its pduId.

Avoid: Packet, frame (message is an accepted synonym in the RFC)

Control PDU

A PDU of the Control Phase: a Test Setup, Null or Test Activation PDU.

Message Verification Procedure

The checks every received Control PDU and Status PDU must pass, in order, before it is acted on: size, checksum when used, authMode, authDigest, then authUnixTime (RFC 9946 §6.2). A PDU failing one is invalid.

Setup exchange

The Setup Request, the Setup Response and, from the Ephemeral Port, the Null Request.

Setup Request / Setup Response

The Test Setup PDU (0xACE1) sent by the Client, and the same PDU returned by the Server with its Command Response and the Ephemeral Port.

Null Request

The Null PDU (0xDEAD) the Server sends from the new Ephemeral Port to open its own firewall pinhole; it gets no reply.

Activation exchange

The Activation Request and the Activation Response.

Activation Request / Activation Response

The Test Activation PDU (0xACE2) carrying the Test parameters, and the Server’s accepted, coerced, or rejected version of it.

Command Response

The cmdResponse code in a Setup Response or Activation Response: ACKOK, or a code naming why the request was rejected.

Avoid: Error code, status code

Silent Rejection

Refusing a request by sending nothing back (RFC 9946 §5.3.1). A request only ignored, such as a duplicate already answered, is not one.

Avoid: Drop (unqualified)

Coercion

The Server’s change of one Activation Request parameter to a value it accepts, returned in the Activation Response with ACKOK.

Avoid: Override, adjustment (of a parameter)

Load PDU

The PDU (0xBEEF) that carries the measurement load, with a sequence-numbered header followed by filler payload.

Avoid: Data packet, test packet

Status PDU

The PDU (0xFEED) the Load Receiver sends every Trial Interval, carrying reception statistics and, when the Server sends it, the next sending parameters.

Avoid: Feedback message, status feedback message, report

Stale Status PDU

A Status PDU whose spduSeqNo is 0 or no greater than that of the last one processed: a duplicated, reordered or replayed one.

STOP exchange

The graceful end of a Test Connection: the Server marks its outgoing PDUs TEST_ACT_STOP2 and the Client confirms by marking its own.

Avoid: STOP2 exchange, stop handshake, teardown

Timers

Load PDU timeout / Status PDU timeout

The Load Receiver’s timer, reset by every Load PDU received, and the Load Sender’s, reset by every Status PDU received, whose expiry stops that end sending (RFC 9946 §5.1). The Test Connection ends later, at the Watchdog.

Watchdog

The timer at each end of a Test Connection, reset by every valid PDU received while that end still sends, whose expiry ends the Test Connection without the STOP exchange (ADR 0002).

Avoid: Keepalive, idle timer, test termination timeout (RFC 9946 §6.1’s name for it)

Test initiation timer

The Client’s timer, started with its Setup Request, that ends a Control Phase which hasn’t reached the Data Phase within 3 s (RFC 9946 §6.1 lets it reuse the “test termination timeout”), or sooner if the Client user says so.

Activation Watchdog

The Server’s timer, started with a Setup Response, that closes the Test Connection if no valid Activation Request arrives within 3 s.

Rate control

Load Rate Adjustment Algorithm

The Server-side logic that picks the next Sending Rate Table row from measured impairments. The registered ones are algorithm B (ITU-T Y.1540 Amd2) and algorithm C (BBF TR-471).

Avoid: Congestion control, CCA, search algorithm

Sending Rate Table

The Server’s ordered table of rows, numbered from 0, each holding the transmission parameters for one offered sending rate.

Avoid: Rate table, rate ladder

Sending rate

The rate of the Sending Rate Table row a Load Sender is set to send at (RFC 9946 §8.1; RFC 9097’s “offered load”).

Avoid: Offered load

Sending Rate Structure

The transmission parameters of one Sending Rate Table row as carried on the wire (srStruct: two interval/payload/burst sets plus an add-on).

Avoid: Rate row (on the wire)

Sequence Error

A Load PDU the Load Receiver counts, from the lpduSeqNo it sees, as lost, out of order or duplicated (RFC 9946 §8.2’s seqErrLoss, seqErrOoo and seqErrDup). With ignoreOooDup set, as by default, only the lost ones count against seqErrThresh (RFC 9946 §7.1).

Avoid: Sequence anomaly

Clean Interval

A Trial Interval whose counted Sequence Errors are at or below the threshold and whose delay variation is below the lower threshold. A Trial Interval with no delay variation sample is never clean.

Errored Interval

A Trial Interval whose counted Sequence Errors exceed the threshold or whose delay variation exceeds the upper threshold.

Avoid: Impaired interval, congested interval

Hold Interval

A Trial Interval that is neither clean nor errored, on which the algorithm makes no change.

Avoid: Neither, no-change interval

Congestion

What the algorithm infers when a configured number of back-to-back Errored Intervals occur; inferring it sets Congestion Confirmed.

Avoid: Overload, impairment (an impairment is a single-interval observation)

Congestion Confirmed

The latched state entered when Congestion is inferred. Algorithm B stays in it, and so in Single-Step Mode, for the rest of the Test Connection; algorithm C clears it only by a Fast-Mode Retry.

Avoid: Congested state, congestion flag

Fast Mode

The state of a Load Rate Adjustment Algorithm, below the 1 Gbps row and before Congestion Confirmed, in which the rate rises by more than one row at a time.

Avoid: Ramp-up, slow start, high-speed mode (the RFC’s name, kept only in the highSpeedDelta field)

Single-Step Mode

The state in which every rate change is exactly one Sending Rate Table row up or down.

Avoid: Slow mode, fine-tuning

Fast-Mode Retry

Algorithm C’s re-entry into Fast Mode after enough single-step moves, clearing Congestion Confirmed.

Avoid: Retry (unqualified; clashes with retransmission)

Lost Status Backoff

A Load Sender’s lowering of its sending rate in a Search Test, as for an Errored Interval, each time no Status PDU has arrived for RFC 9097 §8.1’s Lost Status Backoff timeout, which grows by one Trial Interval with each backoff.

Avoid: Feedback timeout backoff

Over-rate policing

The Server’s ending of a Test Connection whose Load Sender keeps sending well above the sending rates the Server assigned it (ADR 0008, ADR 0011).

Measurement intervals and results

Test Interval

The whole measurement duration (testIntTime, seconds) after which the Server starts the STOP exchange.

Avoid: Test duration, run time

Sub-Interval

A fixed slice of the Test Interval (subIntPeriod, ms, a whole number of Trial Intervals) over which statistics are saved and reported in sisSav, and over which each IP-Layer Capacity is measured.

IP-Layer Capacity

The IP-layer bit rate received in one Sub-Interval, IP and UDP headers included, over its nominal length (RFC 9097 §5.3, C(T,dt,PM)).

Avoid: Sub-Interval throughput, rate (unqualified)

Trial Interval

The period between consecutive Status PDUs (trialInt, ms); the unit the algorithm decides on.

Avoid: Feedback interval, status interval

Loss Ratio

The share of the Load PDUs sent in a Sub-Interval that were lost (RFC 9097 §5.4’s ratio of lost packets, which §9 reports at the maximum).

Avoid: Packet loss rate, drop rate

Tmax

The longest a Load PDU may take to arrive and still count as received rather than lost (RFC 9097 §4).

Avoid: Loss timeout, waiting time

Performance Criterion

The loss target a Sub-Interval must meet for its IP-Layer Capacity to count towards the Maximum IP-Layer Capacity (RFC 9097 §6.3’s PM criterion): at most a set Loss Ratio of the Load PDUs sent in it, or one lost Load PDU per Test Connection. One in which none were received meets none.

Avoid: PM threshold, quality filter

Maximum IP-Layer Capacity

The highest IP-Layer Capacity of the Sub-Intervals that meet the Performance Criterion, within one Capacity Mode (RFC 9097 §6.3). The Test’s headline result; a Test where none meets it has none.

Avoid: Throughput, bandwidth (except in maxBandwidth), speed, goodput

Highest IP-Layer Capacity

The highest IP-Layer Capacity of any Sub-Interval, whether or not it meets the Performance Criterion: what OB-UDPST reports as its maximum.

Avoid: Peak rate, raw maximum

Capacity Mode

One of the consecutive stretches of Sub-Intervals, split where the Client user says, that each get their own Maximum IP-Layer Capacity, for a path whose capacity changes on a schedule such as a “turbo mode” (RFC 9097 §6.6).

Avoid: Mode (unqualified), phase, first mode (TR-471’s name, kept only in –first-mode-sub-intervals and FirstModeSplitIgnored)

IP-Layer Sender Bit Rate

The IP-layer bit rate the Load Sender actually sent, over each st and each Sub-Interval’s worth of them (RFC 9097 §7’s B(S,st)); a Load Receiver can only estimate it, from the Load PDUs that arrive.

Avoid: Send rate (unqualified), Sender IP-Layer Bit Rate

st

The length of the intervals, counted from the Load Sender’s first send, over which the IP-Layer Sender Bit Rate is taken (RFC 9097 §7.2); udpstp’s is one Trial Interval, offset from the Load Receiver’s Trial Intervals by the one-way delay.

Security

Authentication Mode

How much of a Test Connection is authenticated (authMode): mode 1 authenticates the Control Phase and mode 2 also authenticates Status PDUs. RFC 9946 defines only these two, written mode 1 and mode 2.

Avoid: Auth level, security mode

Unauthenticated Mode

OB-UDPST’s authMode 0, which authenticates nothing and which RFC 9946 does not define; udpstp enables it only when both ends opt in, to interoperate with OB-UDPST.

Avoid: Mode 0, open mode

Key Table

The table of Shared Keys a Client or Server authenticates with, one row per key with RFC 7210’s fields, send and accept lifetimes among them (RFC 9946 §5.4).

Avoid: Key store, keyring

Shared Key

A long-lived secret in the Key Table, selected by keyId, that is only ever used as input to the KDF.

Avoid: Password, secret unqualified

Operator Key

A Shared Key that the Server’s Key Table marks as an Operator’s: only its Tests may be Fixed-Rate Tests, and they are spared some limits the Server sets for Consumers.

Avoid: Admin key, privileged key

Derived Keys

The Client Authentication Key and Server Authentication Key, derived once per Test Connection from the Shared Key and the first Setup Request’s authUnixTime.

Avoid: Session keys

Troubleshooting Mode

A Server setting that answers authentication failures with a Command Response instead of a Silent Rejection, for debugging Client setups.

Avoid: Debug mode, verbose mode

Conformance

Requirement

One normative statement of RFC 9946, or of RFC 9097 as RFC 9946 uses it, with a stable ID. It counts as met when a test proves it, unless it is recorded otherwise.

Deviation

A recorded departure from a Requirement, with its reason: a non-conformance, an interop accommodation, a platform gap or an unmet SHOULD.

Avoid: Deviation for a difference from OB-UDPST that conforms to the RFC (an OB-UDPST Difference)

Interpretation

A recorded reading of a Requirement that is ambiguous, silent on a case, or collides with another one, or a choice the RFC leaves to the implementation; udpstp still conforms.

OB-UDPST

The Broadband Forum’s open-source C implementation of UDPSTP, and udpstp’s interop peer.

OB-UDPST Difference

Behaviour in which udpstp and OB-UDPST differ while udpstp conforms to the RFC.

Avoid: Deviation (from OB-UDPST)

Conformance Record

The record of one Deviation, Interpretation or OB-UDPST Difference: what udpstp does, why, and the tests that prove it.

Avoid: Registry entry, deviations registry

Load schedule

Transmitter

One of a Load Sender’s two independent Burst schedules (RFC 9946 §7.1’s dual independent transmitters), each sending one Burst per interval as one interval/payload/burst set of its transmission parameters says.

Avoid: Timer, channel, stream

Burst

The Load PDUs one Transmitter sends back to back at one scheduled time: burstSize datagrams, plus the Add-on on Transmitter 2.

Avoid: Batch, train

Add-on

The single extra Load PDU of udpAddon2 bytes at the end of each Transmitter 2 Burst.

Send Plan

The datagrams due at one scheduled time: the Deferred Datagrams still waiting, then one new Burst unless it is withheld.

Avoid: Burst plan

Deferred Datagram

A Load PDU of a Send Plan that the host could not send. It leads the next Send Plan with its original sequence number and a fresh lpduTime.

Avoid: Retransmission, retry

Catch-up budget

How late a missed Burst may be and still be sent when the Load Sender catches up (ADR 0012).

Avoid: Catch-up window, grace period

Late Burst

A Burst sent after its scheduled time but less late than the catch-up budget, or the most recent Burst due.

Burst lateness

How long after a Burst’s scheduled time the Load Sender writes its Send Plan, and so stamps its lpduTime; the time from lpduTime to the datagram’s departure is the send lag.

Avoid: Burst delay

Skipped Burst

A Burst not sent because it was at least the catch-up budget late when its turn came and wasn’t the most recent Burst due; its Load PDUs take no lpduSeqNo and are missing from the IP-Layer Sender Bit Rate.

Avoid: Dropped burst, lost burst (loss is what a Load Receiver counts from lpduSeqNo gaps)

Withheld Burst

A Burst not sent because at least as many Deferred Datagrams as it holds are still waiting; counted like a Skipped Burst.

Host

Receive Buffer Overflow

A datagram the host’s OS discarded at a Test Connection’s socket before the Data Phase Engine read it, mostly for a full receive buffer; a Load Receiver counts it as lost though the path didn’t lose it.

Avoid: Dropped datagram, socket drop, RcvbufErrors (the kernel’s host-wide counter)

Test Time Base

The steady clock every Data Phase time is taken from, which changes to the wall clock never move; lpduTime and spduTime are this clock plus a wall-clock offset fixed when the Test Connection activates.

Avoid: System time, wall time (for Data Phase timing)

Data Phase Engine

The part of an endpoint that sends each Test Connection’s Send Plans at their scheduled times and receives its Load PDUs and Status PDUs.

Avoid: Runtime (unqualified)

Engine Thread

A thread that runs the Data Phase Engine for one or more Test Connections.

Avoid: Engine worker, per-core thread

Conformance

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 test that runs on Linux proves it, unless it is recorded otherwise. These pages are generated by cargo xtask req’s checks when the site is built.

348 of 420 Requirements are proven by tests. Of the rest, 24 are Deviations, each recorded with its reason, 33 are operational (they concern how udpstp is deployed or used rather than its code), and 15 don’t apply to udpstp.

Coverage by section

Conformance Records

Where udpstp departs from a Requirement, reads an ambiguous one, or differs from OB-UDPST, a Conformance Record says what it does, why, and which tests prove it.

How the records work describes the files these pages come from.

States

• Tested: a test that runs on Linux, in CI and before every push, proves it.
• Tested nightly: only tests in the nightly workflow prove it.
• Pending: no test proves it yet.
• Deviation: udpstp departs from it, as a Deviation records.
• Interpretation: udpstp meets it as an Interpretation reads it.
• Operational: it concerns deployment or use, not udpstp’s code.
• Not applicable: it doesn’t apply to udpstp.

RFC 9097 §2: Scope, Goals, and Applicability

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.

RFC9097-2-1

Operational

It is RECOMMENDED to discontinue non-measurement traffic that shares a subscriber’s dedicated resources while testing: measurements may not be accurate, and throughput of competing elastic traffic may be greatly reduced.

Note: Advice to the user running a Test.

RFC9097-2-2

Operational

It MUST only be used in the application of diagnostic and operations measurements as described in this memo.

Note: “It” is the Load Rate Adjustment Algorithm; RFC 9946 section 5.1 item 2 says the same.

RFC9097-2-3

Operational

It MUST only be used in circumstances consistent with Section 10 (“Security Considerations”).

Note: RFC 9946 section 5.1 item 11 says the same.

RFC9097-2-4

Tested

If a network operator is certain of the IP-Layer Capacity to be validated, then testing MAY start with a fixed-rate test at the IP-Layer Capacity and avoid activating the load adjustment algorithm.

Note: Fixed-Rate Test, Operator Key only; RFC 9946 section 5.1 item 10.

Proving tests:

• crates/udpstp/tests/interop.rs::unauthenticated_and_fixed_rate_tests_interoperate
• crates/udpstp/tests/loopback.rs::fixed_rate_tests_complete_over_loopback

RFC9097-2-5

Tested

However, the stimulus for a diagnostic test (such as a subscriber request) strongly implies that there is no certainty, and the load adjustment algorithm is RECOMMENDED.

Note: A Search Test is the default.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::the_default_search_starts_at_row_0
• crates/udpstp-core/tests/parameter_ranges.rs::the_client_asks_for_the_defaults

RFC9097-2-6

Tested

Finally, the measurement system’s load rate adjustment algorithm SHALL NOT be provided with the exact capacity value to be validated a priori.

Note: A Search Test starts at the default row or a requested srIndexConf row, never at a known capacity.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::the_default_search_starts_at_row_0
• crates/udpstp-core/tests/start_row_cap.rs::a_capped_search_still_climbs_past_the_cap

RFC 9097 §4: General Parameters and Definitions

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.

RFC9097-4-1

Not applicable

This section lists the REQUIRED input factors to specify a Sender or Receiver metric.

Note: An introduction to the section’s Requirements, each recorded with its own ID; nothing to do beyond them.

RFC9097-4-L1

Tested

The nominal duration of a measurement interval at the Destination (default 10 sec).

Note: I, the Test Interval (testIntTime).

Proving tests:

• crates/udpstp-core/tests/parameter_ranges.rs::the_client_asks_for_the_defaults

RFC9097-4-L2

Tested

The nominal duration of m equal sub-intervals in I at the Destination (default 1 sec).

Note: dt, the Sub-Interval (subIntPeriod).

Proving tests:

• crates/udpstp-core/tests/parameter_ranges.rs::the_client_asks_for_the_defaults

RFC9097-4-L3

Tested

The results are evaluated throughout the test to determine how to adjust the current offered load rate at the Sender (default 50 msec).

Note: FT, the Trial Interval (trialInt).

Proving tests:

• crates/udpstp-core/tests/parameter_ranges.rs::the_client_asks_for_the_defaults

RFC9097-4-L4

Tested

A maximum waiting time for test packets to arrive at the Destination, set sufficiently long to disambiguate packets with long delays from packets that are discarded (lost), such that the distribution of one-way delay is not truncated.

Note: Tmax.

Conformance Records: tmax-within-the-sub-interval.

Proving tests:

• crates/udpstp-core/tests/sequence_errors.rs::a_load_pdu_later_than_its_sub_interval_stays_lost

RFC9097-4-L5

Tested

The number of different flows synthesized by the method (default one flow).

Note: F; more than one is a Multi-Connection Test.

Proving tests:

• crates/udpstp/tests/loopback.rs::a_client_completes_the_control_phase_over_ipv4_loopback

RFC9097-4-2

Not applicable

Note: The IPv6 flow label SHOULD be included in the flow definition when routers have complied with the guidelines provided in [RFC6438].

Note: About the flow definition: udpstp sets no IPv6 flow label, and the OS’s is constant for a socket, so a Test Connection is one flow with or without it.

RFC9097-4-3

Tested

If there is payload compression in the path and tests intend to characterize a possible advantage due to compression, then payload content SHOULD be supplied by a pseudorandom sequence generator, by using part of a compressed file, or by other means.

Note: Random payload (CHTA_RAND_PAYLOAD, --random-payload).

Proving tests:

• crates/udpstp-core/tests/downstream_load.rs::payload_content_is_random_when_asked_for

RFC9097-4-4

Tested

At least one fundamental metric and target performance threshold MUST be supplied (such as one-way IP packet loss [RFC7680] equal to zero).

Note: PM: the Performance Criterion.

Proving tests:

• crates/udpstp/src/results.rs::a_completed_test
• crates/udpstp-core/src/results.rs::the_maximum_meets_the_criterion_and_the_highest_need_not

RFC 9097 §5: IP-Layer Capacity Singleton Metric Definitions

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.

RFC9097-5.2-1

Not applicable

This section lists the REQUIRED input factors to specify the metric, beyond those listed in Section 4.

Note: The section adds no Parameters.

RFC9097-5.3-1

Not applicable

This section defines the REQUIRED aspects of the measurable IP-Layer Capacity Metric (unless otherwise indicated) for measurements between specified Source and Destination hosts:

Note: An introduction to the section’s Requirements, each recorded with its own ID; nothing to do beyond them.

RFC9097-5.3-L1

Deviation

Define the IP-Layer Capacity, C(T,dt,PM), to be the number of IP- Layer bits (including header and data fields) in packets that can be transmitted from the Src host and correctly received by the Dst host during one contiguous sub-interval, dt in length.

Note: IP-Layer Capacity; a definition, but the one the Sub-Interval results compute.

Recorded in approximate-upstream-aggregation.

Conformance Records: duplicates-count-as-received, multi-connection-common-grid.

Proving tests:

• crates/udpstp/tests/netns.rs::a_fixed_rate_test_above_the_bottleneck_delivers_its_rate
• crates/udpstp-core/tests/bottleneck.rs::a_fixed_rate_over_the_bottleneck_measures_its_capacity_and_loss
• crates/udpstp-core/tests/bottleneck.rs::a_fixed_rate_under_the_bottleneck_arrives_whole
• crates/udpstp-core/tests/sub_interval_results.rs::a_downstream_client_reports_each_sub_interval_it_received
• crates/udpstp-core/tests/sub_interval_results.rs::over_ipv6_the_headers_are_48_bytes

RFC9097-5.3-2

Tested

Anticipating a Sample of Singletons, the number of sub-intervals with duration dt MUST be set to a natural number m, so that T+I = T + m*dt with dtn+1 - dtn = dt for 1 <= n <= m.

Note: testIntTime / subIntPeriod Sub-Intervals.

Conformance Records: sub-interval-whole-trial-intervals.

Proving tests:

• crates/udpstp-core/tests/sub_interval_results.rs::the_sub_interval_becomes_a_whole_number_of_trial_intervals

RFC9097-5.3-3

Tested

Parameter PM represents other performance metrics (see Section 5.4 below); their measurement results SHALL be collected during measurement of IP-Layer Capacity and associated with the corresponding dtn for further evaluation and reporting.

Note: Per-Sub-Interval statistics (sisSav).

Proving tests:

• crates/udpstp-core/tests/sub_interval_results.rs::each_sub_interval_carries_the_rtt_and_one_way_delay_minimums

RFC9097-5.3-4

Tested

Users SHALL specify the Parameter Tmax as required by each metric’s reference definition.

Note: Tmax.

Conformance Records: tmax-within-the-sub-interval.

Proving tests:

• crates/udpstp-core/tests/sequence_errors.rs::a_load_pdu_later_than_its_sub_interval_stays_lost

RFC9097-5.3-5

Tested

PM represents other performance metrics (see Section 5.4 below); their measurement results SHALL be collected during measurement of IP-Layer Capacity and associated with the corresponding dtn for further evaluation and reporting.

Note: Bullet restating RFC9097-5.3-3.

Proving tests:

• crates/udpstp-core/tests/sub_interval_results.rs::each_sub_interval_carries_the_rtt_and_one_way_delay_minimums

RFC9097-5.3-6

Tested

All sub-intervals MUST be of equal duration.

Note: subIntPeriod is a whole number of Trial Intervals.

Conformance Records: sub-interval-whole-trial-intervals.

Proving tests:

• crates/udpstp-core/tests/sub_interval_results.rs::the_sub_interval_becomes_a_whole_number_of_trial_intervals

RFC9097-5.3-7

Operational

The bit rate of the physical interface of the measurement devices MUST be higher than the smallest of the links on the path whose C(T,I,PM) is to be measured (the bottleneck link).

Note: Deployment of the measurement hosts.

RFC9097-5.3-8

Tested

Measurements according to this definition SHALL use the UDP transport layer.

Proving tests:

• crates/udpstp/tests/loopback.rs::a_client_completes_the_control_phase_over_ipv4_loopback

RFC9097-5.3-9

Tested

The measurement SHOULD use a randomized Source port or equivalent technique, and SHOULD send responses from the Source address matching the test packet Destination address.

Note: The Client’s ports are assigned by the OS from its ephemeral range, not udpstp’s Ephemeral Ports (the Server’s); replies leave from the arrival address (ADR 0007).

Proving tests:

• crates/udpstp/tests/loopback.rs::replies_leave_from_the_address_the_setup_request_arrived_on

RFC9097-5.4-1

Tested

The statistics used to summarize RTD[dtn,dtn+1] MAY include the minimum, maximum, median, mean, and the range = (maximum - minimum).

Proving tests:

• crates/udpstp-core/tests/sub_interval_results.rs::each_sub_interval_carries_the_rtt_and_one_way_delay_minimums

RFC9097-5.4-2

Tested

The statistics used to summarize OWL[dtn,dtn+1] MAY include the count of lost packets and the ratio of lost packets.

Note: Loss Ratio.

Proving tests:

• crates/udpstp-core/tests/sub_interval_results.rs::duplicates_and_reordering_are_reported_apart_from_loss

RFC9097-5.4-3

Tested

Other metrics MAY be measured: one-way reordering, duplication, and delay variation.

Proving tests:

• crates/udpstp-core/tests/sub_interval_results.rs::duplicates_and_reordering_are_reported_apart_from_loss

RFC9097-5.6-1

Tested

The IP-Layer Capacity SHOULD be reported with at least single-Megabit resolution, in units of Megabits per second (Mbps) (which, to avoid any confusion, is 1,000,000 bits per second).

Proving tests:

• crates/udpstp/src/results.rs::a_completed_test

RFC9097-5.6-2

Tested

The related One-Way Loss metric and Round-Trip Delay measurements for the same Singleton SHALL be reported, also with meaningful resolution for the values measured.

Proving tests:

• crates/udpstp/src/results.rs::a_completed_test

RFC9097-5.6-3

Tested

Individual Capacity measurements MAY be reported in a manner consistent with the Maximum IP-Layer Capacity; see Section 9.

Proving tests:

• crates/udpstp/src/results.rs::a_completed_test

RFC 9097 §6: Maximum IP-Layer Capacity Metric Definitions (Statistics)

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.

RFC9097-6.2-1

Not applicable

This section lists the REQUIRED input factors to specify the metric, beyond those listed in Section 4.

Note: The section adds no Parameters.

RFC9097-6.3-1

Not applicable

This section defines the REQUIRED aspects of the Maximum IP-Layer Capacity Metric (unless otherwise indicated) for measurements between specified Source and Destination hosts:

Note: An introduction to the section’s Requirements, each recorded with its own ID; nothing to do beyond them.

RFC9097-6.3-L1

Tested

Define the Maximum IP-Layer Capacity, Maximum_C(T,I,PM), to be the maximum number of IP-Layer bits n0[dtn,dtn+1] divided by dt that can be transmitted in packets from the Src host and correctly received by the Dst host, over all dt-length intervals in [T,T+I] and meeting the PM criteria.

Note: Maximum IP-Layer Capacity; a definition, but the one the results compute.

Conformance Records: shallow-queue-search-alternates-at-the-bottleneck, duplicates-count-as-received, empty-sub-interval-meets-no-criterion, json-at-max-is-the-maximum.

Proving tests:

• crates/udpstp/src/results.rs::a_watchdog_ended_test_with_two_capacity_modes
• crates/udpstp/tests/netns.rs::downstream_and_upstream_tests_measure_the_bottleneck
• crates/udpstp-core/src/results.rs::the_maximum_meets_the_criterion_and_the_highest_need_not
• crates/udpstp-core/src/results.rs::a_sub_interval_with_nothing_received_meets_no_criterion
• crates/udpstp-core/src/results.rs::no_sub_interval_meeting_the_criterion_means_no_maximum

RFC9097-6.3-2

Tested

The number of sub-intervals with duration dt MUST be set to a natural number m, so that T+I = T + m*dt with dtn+1 - dtn = dt for 1 <= n <= m.

Note: testIntTime / subIntPeriod Sub-Intervals.

Conformance Records: sub-interval-whole-trial-intervals.

Proving tests:

• crates/udpstp-core/tests/sub_interval_results.rs::the_sub_interval_becomes_a_whole_number_of_trial_intervals

RFC9097-6.3-3

Tested

At least one target performance threshold (PM criterion) MUST be defined.

Note: The Performance Criterion.

Conformance Records: shallow-queue-search-alternates-at-the-bottleneck, loss-allowance-per-test-connection.

Proving tests:

• crates/udpstp-core/src/results.rs::no_sub_interval_meeting_the_criterion_means_no_maximum

RFC9097-6.3-4

Not applicable

If more than one metric and target performance threshold is defined, then the sub-interval with the maximum number of bits transmitted MUST meet all the target performance thresholds.

Note: udpstp defines one Performance Criterion, the Loss Ratio, so there is never more than one threshold to meet.

Conformance Records: shallow-queue-search-alternates-at-the-bottleneck.

RFC9097-6.3-5

Tested

Users SHALL specify the Parameter Tmax as required by each metric’s reference definition.

Note: Tmax.

Conformance Records: tmax-within-the-sub-interval.

Proving tests:

• crates/udpstp-core/tests/sequence_errors.rs::a_load_pdu_later_than_its_sub_interval_stays_lost

RFC9097-6.3-6

Tested

At least one target performance threshold (PM criterion) MUST be defined.

Note: Bullet restating RFC9097-6.3-3.

Proving tests:

• crates/udpstp-core/src/results.rs::the_maximum_meets_the_criterion_and_the_highest_need_not

RFC9097-6.3-7

Tested

All sub-intervals MUST be of equal duration.

Note: subIntPeriod is a whole number of Trial Intervals.

Conformance Records: sub-interval-whole-trial-intervals.

Proving tests:

• crates/udpstp-core/tests/sub_interval_results.rs::the_sub_interval_becomes_a_whole_number_of_trial_intervals

RFC9097-6.3-8

Operational

The bit rate of the physical interface of the measurement systems MUST be higher than the smallest of the links on the path whose Maximum_C(T,I,PM) is to be measured (the bottleneck link).

Note: Deployment of the measurement hosts.

RFC9097-6.3-9

Tested

Measurements according to these definitions SHALL use the UDP transport layer.

Proving tests:

• crates/udpstp/tests/loopback.rs::a_client_completes_the_control_phase_over_ipv4_loopback

RFC9097-6.4-L1

Tested

The interval dtn,dtn+1 where Maximum_C(T,I,PM) occurs is the reporting sub-interval for RTD[dtn,dtn+1] and OWL[dtn,dtn+1] within RTD[T,I] and OWL[T,I].

Note: Loss and RTT are reported for the Sub-Interval of the maximum.

Proving tests:

• crates/udpstp/src/results.rs::a_completed_test

RFC9097-6.4-1

Tested

Other metrics MAY be measured: one-way reordering, duplication, and delay variation.

Proving tests:

• crates/udpstp-core/tests/delay_variation.rs::sub_intervals_collect_the_delay_samples_of_their_trial_intervals
• crates/udpstp-core/tests/sub_interval_results.rs::duplicates_and_reordering_are_reported_apart_from_loss

RFC9097-6.5-1

Operational

If traffic conditioning (e.g., shaping, policing) applies along a path for which Maximum_C(T,I,PM) is to be determined, different values for dt SHOULD be picked and measurements executed during multiple intervals [T,T+I].

Note: The user picks subIntPeriod per Test.

RFC9097-6.5-2

Operational

Each duration dt SHOULD be chosen so that it is an integer multiple of increasing values k times serialization delay of a Path MTU (PMTU) at the physical interface speed where traffic conditioning is expected.

Note: The user picks subIntPeriod per Test.

RFC9097-6.6-1

Tested

The IP-Layer Capacity SHOULD be reported with at least single-Megabit resolution, in units of Megabits per second (Mbps) (which, to avoid any confusion, is 1,000,000 bits per second).

Proving tests:

• crates/udpstp/src/results.rs::a_completed_test

RFC9097-6.6-2

Tested

The related One-Way Loss metric and Round-Trip Delay measurements for the same Singleton SHALL be reported, also with meaningful resolution for the values measured.

Proving tests:

• crates/udpstp/src/results.rs::a_completed_test

RFC9097-6.6-3

Tested

When there are demonstrated and repeatable Capacity modes in the Sample, the Maximum IP-Layer Capacity SHALL be reported for each mode, along with the relative time from the beginning of the stream that the mode was observed to be present.

Note: Capacity Modes.

Proving tests:

• crates/udpstp/src/json.rs::a_bimodal_test_has_obudpst_keys_and_forms
• crates/udpstp/src/results.rs::a_watchdog_ended_test_with_two_capacity_modes
• crates/udpstp-core/src/results.rs::a_split_makes_two_capacity_modes

RFC 9097 §7: IP-Layer Sender Bit Rate Singleton Metric Definitions

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.

RFC9097-7.2-1

Not applicable

This section lists the REQUIRED input factors to specify the metric, beyond those listed in Section 4.

Note: An introduction to the section’s Requirements, each recorded with its own ID; nothing to do beyond them.

RFC9097-7.2-L1

Tested

The nominal duration of N sub-intervals in S (default st = 0.05 seconds).

Note: st, one Trial Interval.

Proving tests:

• crates/udpstp-core/tests/sub_interval_results.rs::an_upstream_client_reports_what_it_sent_per_st

RFC9097-7.2-2

Tested

S SHALL be longer than I, primarily to account for on-demand activation of the path, or any preamble to testing required, and the delay of the path.

Proving tests:

• crates/udpstp-core/tests/stop_exchange.rs::the_test_stops_gracefully_when_the_servers_test_interval_ends

RFC9097-7.2-3

Tested

st SHOULD be much smaller than the sub-interval dt and on the same order as FT; otherwise, the rate measurement will include many rate adjustments and include more time smoothing, possibly smoothing the interval that contains the Maximum IP-Layer Capacity (and therefore losing relevance).

Proving tests:

• crates/udpstp-core/tests/sub_interval_results.rs::an_upstream_client_reports_what_it_sent_per_st

RFC9097-7.3-1

Not applicable

This section defines the REQUIRED aspects of the IP-Layer Sender Bit Rate Metric (unless otherwise indicated) for measurements at the specified Source on packets addressed for the intended Destination host and matching the required Type-P:

Note: An introduction to the section’s Requirements, each recorded with its own ID; nothing to do beyond them.

RFC9097-7.3-2

Tested

Define the IP-Layer Sender Bit Rate, B(S,st), to be the number of IP- Layer bits (including header and data fields) that are transmitted from the Source with address pair Src and Dst during one contiguous sub-interval, st, during the test interval S (where S SHALL be longer than I) and where the fixed-size packet count during that single sub- interval st also provides the number of IP-Layer bits in any interval, [stn,stn+1].

Note: IP-Layer Sender Bit Rate.

Proving tests:

• crates/udpstp-core/tests/sub_interval_results.rs::an_upstream_client_reports_what_it_sent_per_st

RFC9097-7.3-3

Tested

Measurements according to this definition SHALL use the UDP transport layer.

Proving tests:

• crates/udpstp/tests/loopback.rs::a_client_completes_the_control_phase_over_ipv4_loopback

RFC9097-7.3-4

Deviation

Any feedback from the Dst host to the Src host received by the Src host during an interval [stn,stn+1] SHOULD NOT result in an adaptation of the Src host traffic conditioning during this interval (rate adjustment occurs on st interval boundaries).

Recorded in rate-changes-when-a-status-pdu-arrives.

RFC9097-7.4-1

Tested

Both the Sender and Receiver (or Source and Destination) bit rates SHOULD be assessed as part of an IP-Layer Capacity measurement.

Proving tests:

• crates/udpstp/src/results.rs::an_upstream_test
• crates/udpstp/tests/loopback.rs::fixed_rate_tests_complete_over_loopback
• crates/udpstp-core/src/data_phase.rs::sender_estimate_keeps_ordinary_gaps_duplicates_and_out_of_order_load
• crates/udpstp-core/tests/sender_estimate.rs::the_estimate_follows_what_the_server_sent_despite_loss
• crates/udpstp-core/tests/sub_interval_results.rs::an_upstream_client_reports_what_it_sent_per_st

RFC9097-7.5-1

Tested

The IP-Layer Sender Bit Rate SHALL be reported with meaningful resolution, in units of Megabits per second (which, to avoid any confusion, is 1,000,000 bits per second).

Proving tests:

• crates/udpstp/src/results.rs::an_upstream_test

RFC 9097 §8: Method of Measurement

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.

RFC9097-8-1

Tested

It is REQUIRED per the architecture of the method that two cooperating hosts operate in the roles of Src (test packet Sender) and Dst (Receiver) with a measured path and return path between them.

Note: Load Sender and Load Receiver.

Proving tests:

• crates/udpstp/tests/loopback.rs::fixed_rate_tests_complete_over_loopback

RFC9097-8-2

Tested

The duration of a test, Parameter I, MUST be constrained in a production network, since this is an active test method and it will likely cause congestion on the path from the Src host to the Dst host during a test.

Note: testIntTime’s maximum.

Proving tests:

• crates/udpstp-core/tests/test_interval_limits.rs::an_ordinary_key_gets_at_most_60_s

RFC9097-8.1-1

Operational

The algorithm described in this section MUST NOT be used as a general Congestion Control Algorithm (CCA).

Note: RFC 9946 section 5.1 item 1 says the same.

RFC9097-8.1-2

Tested

A table SHALL be pre-built (by the test administrator), defining all the offered load rates that will be supported (R1 through Rn, in ascending order, corresponding to indexed rows in the table).

Note: Sending Rate Table.

Proving tests:

• crates/udpstp-core/src/sending_rate_table.rs::rows_offer_their_rates
• crates/udpstp-core/tests/sending_rate_table.rs::row_n_is_n_mbps_up_to_1_gbps

RFC9097-8.1-3

Deviation

It is RECOMMENDED that rates begin with 0.5 Mbps at index zero, use 1 Mbps at index one, and then continue in 1 Mbps increments to 1 Gbps.

Note: Sending Rate Table.

Recorded in row-zero-below-half-a-megabit.

RFC9097-8.1-4

Deviation

Above 1 Gbps, and up to 10 Gbps, it is RECOMMENDED that 100 Mbps increments be used.

Note: Sending Rate Table.

Recorded in table-steps-above-1-gbps.

RFC9097-8.1-5

Deviation

Above 10 Gbps, increments of 1 Gbps are RECOMMENDED.

Note: Sending Rate Table.

Recorded in table-steps-above-1-gbps.

RFC9097-8.1-L1

Tested

A higher initial IP-Layer Sender Bit Rate might be configured when the test operator is certain that the Maximum IP- Layer Capacity is well above the initial IP-Layer Sender Bit Rate and factors such as test duration and total test traffic play an important role.

Note: A Search Test may start at a requested srIndexConf row.

Proving tests:

• crates/udpstp-core/tests/client_parameters.rs::the_client_asks_for_the_start_row_chosen
• crates/udpstp-core/tests/sending_rate_table.rs::a_requested_starting_row_is_sent

RFC9097-8.1-6

Tested

The sending rate table SHOULD bracket the Maximum Capacity where it will make measurements, including constrained rates less than 500 kbps if applicable.

Note: Sending Rate Table.

Proving tests:

• crates/udpstp-core/src/sending_rate_table.rs::rows_offer_their_rates
• crates/udpstp-core/tests/sending_rate_table.rs::row_zero_sends_fixed_size_datagrams_near_0_1_mbps

RFC9097-8.1-L2

Tested

Each rate is defined as datagrams of size ss, sent as a burst of count cc, each time interval tt (the default for tt is 100 microsec, a likely system tick interval).

Note: Sending Rate Structure: txInterval, udpPayload, burstSize.

Proving tests:

• crates/udpstp-core/tests/plan_executor.rs::the_simulators_executor_meets_the_contract
• crates/udpstp-core/tests/sending_rate_table.rs::every_row_up_to_1_gbps_fits_the_rfc_sizes_and_ob_udpst_client_limits
• crates/udpstp-runtime/src/contract_tests.rs::the_data_phase_engine_meets_the_contract
• crates/udpstp-runtime/src/engine/pool_tests.rs::the_pooled_executor_meets_the_contract

RFC9097-8.1-L3

Tested

While it is advantageous to use datagrams of as large a size as possible, it may be prudent to use a slightly smaller maximum that allows for secondary protocol headers and/or tunneling without resulting in IP-Layer fragmentation.

Note: Server MTU; the 1250-byte default (RFC9946-6.1-8).

Proving tests:

• crates/udpstp-core/src/sending_rate_table.rs::packet_sizes_follow_the_modifiers_and_the_mtu

RFC9097-8.1-L4

Tested

At the beginning of a test, the Sender begins sending at rate R1 and the Receiver starts a feedback timer of duration FT (while awaiting inbound datagrams).

Note: Trial Interval.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::the_default_search_starts_at_row_0
• crates/udpstp-core/tests/status_pdus.rs::status_pdus_follow_the_first_load_pdu_every_trial_interval

RFC9097-8.1-L5

Tested

As datagrams are received, they are checked for sequence number anomalies (loss, out-of-order, duplication, etc.) and the delay range is measured (one-way or round-trip).

Note: Sequence Errors and delay variation (useOwDelVar).

Proving tests:

• crates/udpstp-core/tests/sequence_errors.rs::loss_counts_every_missing_load_pdu
• crates/udpstp-core/tests/sequence_errors.rs::reordered_and_duplicated_load_pdus_are_counted

RFC9097-8.1-L6

Tested

This information is accumulated until the feedback timer FT expires and a status feedback message is sent from the Receiver back to the Sender, to communicate this information.

Note: Status PDU.

Proving tests:

• crates/udpstp-core/tests/status_pdus.rs::status_pdus_follow_the_first_load_pdu_every_trial_interval

RFC9097-8.1-L7

Tested

The accumulated statistics are then reset by the Receiver for the next feedback interval.

Proving tests:

• crates/udpstp-core/tests/status_pdus.rs::each_status_pdu_counts_its_trial_interval

RFC9097-8.1-L8

Tested

As feedback messages are received back at the Sender, they are evaluated to determine how to adjust the current offered load rate (Rx).

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::the_accepted_parameters_drive_the_algorithm

RFC9097-8.1-L9

Tested

If the feedback indicates that no sequence number anomalies were detected AND the delay range was below the lower threshold, the offered load rate is increased.

Note: Clean Interval.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::in_fast_mode_each_clean_interval_adds_high_speed_delta_rows

RFC9097-8.1-L10

Tested

If congestion has not been confirmed up to this point (see below for the method for declaring congestion), the offered load rate is increased by more than one rate setting (e.g., Rx+10).

Note: Fast Mode.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::in_fast_mode_each_clean_interval_adds_high_speed_delta_rows

RFC9097-8.1-L11

Tested

Conversely, if congestion has been previously confirmed, the offered load rate is only increased by one (Rx+1).

Note: Single-Step Mode.

Conformance Records: shallow-queue-search-alternates-at-the-bottleneck.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::congestion_is_confirmed_by_back_to_back_errored_intervals
• crates/udpstp-core/tests/algorithm_b.rs::algorithm_b_never_leaves_single_step_mode

RFC9097-8.1-L12

Tested

However, if a rate threshold above a high sending rate (such as 1 Gbps) is exceeded, the offered load rate is only increased by one (Rx+1) in any congestion state.

Conformance Records: fast-mode-stops-at-the-gigabit-row.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::rows_stay_within_the_table_and_fast_mode_stops_at_1_gbps
• crates/udpstp-core/tests/algorithm_b.rs::above_the_gigabit_row_every_step_is_one_row

RFC9097-8.1-L13

Tested

If the feedback indicates that sequence number anomalies were detected OR the delay range was above the upper threshold, the offered load rate is decreased.

Note: Errored Interval.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::congestion_is_confirmed_by_back_to_back_errored_intervals
• crates/udpstp-core/tests/interval_classification.rs::the_average_rounds_and_clean_is_strictly_below_the_low_threshold
• crates/udpstp-core/tests/interval_classification.rs::seq_err_thresh_is_always_applied

RFC9097-8.1-7

Tested

The RECOMMENDED threshold values are 10 for sequence number gaps and 30 msec for lower and 90 msec for upper delay thresholds, respectively.

Note: seqErrThresh, lowThresh, upperThresh; RFC 9946 section 5.1 item 6.

Proving tests:

• crates/udpstp-core/tests/parameter_ranges.rs::the_client_asks_for_the_defaults

RFC9097-8.1-L14

Tested

Also, if congestion is now confirmed for the first time by the current feedback message being processed, then the offered load rate is decreased by more than one rate setting (e.g., Rx-30).

Note: Congestion Confirmed.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::congestion_is_confirmed_by_back_to_back_errored_intervals
• crates/udpstp-core/tests/algorithm_b.rs::the_confirming_drop_stops_at_row_0_and_follows_the_row_it_starts_from
• crates/udpstp-core/tests/algorithm_b.rs::a_downstream_search_converges_near_the_bottleneck

RFC9097-8.1-L15

Tested

In all other cases, the offered load rate is only decreased by one (Rx-1).

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::congestion_is_confirmed_by_back_to_back_errored_intervals

RFC9097-8.1-L16

Tested

If the feedback indicates that there were no sequence number anomalies AND the delay range was above the lower threshold but below the upper threshold, the offered load rate is not changed.

Note: Hold Interval.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::intermittent_errored_intervals_do_not_confirm_congestion

RFC9097-8.1-L17

Tested

Lastly, the method for inferring congestion is that there were sequence number anomalies AND/OR the delay range was above the upper threshold for three consecutive feedback intervals.

Note: Congestion; slowAdjThresh.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::congestion_is_confirmed_by_back_to_back_errored_intervals
• crates/udpstp-core/tests/algorithm_b.rs::intermittent_errored_intervals_do_not_confirm_congestion

RFC9097-8.1-8

Tested

The load rate adjustment algorithm MUST include timers that stop the test when received packet streams cease unexpectedly.

Note: ADR 0002; RFC 9946 section 5.1 item 7.

Proving tests:

• crates/udpstp-core/tests/timeouts.rs::a_downstream_path_that_breaks_stops_within_1_s_and_ends_at_3_s
• crates/udpstp-core/tests/timeouts.rs::an_upstream_client_stops_when_status_pdus_stop

RFC9097-8.1-9

Tested

The load packet timeout SHALL be reset to the configured value each time a load packet is received.

Note: ADR 0002; RFC 9946 section 5.1 item 8.

Proving tests:

• crates/udpstp-core/tests/timeouts.rs::rx_stopped_clears_when_traffic_comes_back_in_time

RFC9097-8.1-10

Tested

If the timeout expires, the Receiver SHALL be closed and no further feedback sent.

Note: Load packet timeout. ADR 0002.

Proving tests:

• crates/udpstp-core/tests/timeouts.rs::a_downstream_path_that_breaks_stops_within_1_s_and_ends_at_3_s
• crates/udpstp-core/tests/timeouts.rs::traffic_that_comes_back_after_the_timeout_changes_nothing

RFC9097-8.1-11

Tested

The feedback message timeout SHALL be reset to the configured value each time a feedback message is received.

Note: ADR 0002; RFC 9946 section 5.1 item 9.

Proving tests:

• crates/udpstp-core/tests/timeouts.rs::the_load_sender_keeps_sending_when_status_pdus_come_back_in_time

RFC9097-8.1-12

Tested

If the timeout expires, the Sender SHALL be closed and no further load packets sent.

Note: The Status PDU timeout, RFC 9097’s “feedback message” timeout. ADR 0002.

Proving tests:

• crates/udpstp-core/tests/timeouts.rs::an_upstream_client_stops_when_status_pdus_stop

RFC9097-8.1-L18

Tested

If no status feedback messages arrive at the Sender for the interval greater than the Lost Status Backoff timeout:

Note: Lost Status Backoff: UDRT + (2+w)*FT, from the last message of any type received.

Proving tests:

• crates/udpstp-core/tests/lost_status_backoff.rs::lost_status_pdus_back_the_rate_off_and_confirm_congestion

RFC9097-8.1-L19

Tested

Beginning when the last message (of any type) was successfully received at the Sender:

Note: Lost Status Backoff timer start.

Proving tests:

• crates/udpstp-core/tests/lost_status_backoff.rs::lost_status_pdus_back_the_rate_off_and_confirm_congestion
• crates/udpstp-core/tests/lost_status_backoff.rs::any_status_pdu_starts_the_backoff_over

RFC9097-8.1-13

Deviation

The offered load SHALL then be decreased, following the same process as when the feedback indicates the presence of one or more sequence number anomalies OR the delay range was above the upper threshold (as described above), with the same load rate adjustment algorithm variables in their current state.

Note: Lost Status Backoff.

Recorded in no-lost-status-backoff-upstream.

Conformance Records: lost-status-backoff-is-an-errored-interval.

Proving tests:

• crates/udpstp-core/tests/lost_status_backoff.rs::lost_status_pdus_back_the_rate_off_and_confirm_congestion
• crates/udpstp-core/tests/lost_status_backoff.rs::a_backoff_counts_as_an_errored_interval

RFC9097-8.1-14

Tested

The RECOMMENDED initial value for w is 0, taking a Round-Trip Time (RTT) of less than FT into account.

Note: Lost Status Backoff.

Conformance Records: lost-status-backoff-initial-w.

Proving tests:

• crates/udpstp-core/tests/lost_status_backoff.rs::lost_status_pdus_back_the_rate_off_and_confirm_congestion

RFC9097-8.1-L20

Tested

A test with an RTT longer than FT is a valid reason to increase the initial value of w appropriately.

Note: Lost Status Backoff.

Conformance Records: lost-status-backoff-initial-w.

Proving tests:

• crates/udpstp-core/tests/lost_status_backoff.rs::a_long_path_gets_no_backoff_before_its_first_status_pdu

RFC9097-8.1-15

Tested

Variable w SHALL be incremented by one whenever the Lost Status Backoff timeout is exceeded.

Note: Lost Status Backoff.

Proving tests:

• crates/udpstp-core/tests/lost_status_backoff.rs::lost_status_pdus_back_the_rate_off_and_confirm_congestion

RFC9097-8.1-L21

Tested

Also, if congestion is now confirmed for the first time by a Lost Status Backoff timeout, then the offered load rate is decreased by more than one rate setting (e.g., Rx-30).

Note: Lost Status Backoff.

Conformance Records: lost-status-backoff-is-an-errored-interval.

Proving tests:

• crates/udpstp-core/tests/lost_status_backoff.rs::lost_status_pdus_back_the_rate_off_and_confirm_congestion
• crates/udpstp-core/tests/lost_status_backoff.rs::a_backoff_counts_as_an_errored_interval
• crates/udpstp-core/tests/lost_status_backoff.rs::backoffs_stop_at_row_0_and_two_in_a_row_leave_fast_mode_on

RFC9097-8.1-L22

Tested

In all other cases, the offered load rate is only decreased by one (Rx-1).

Note: Lost Status Backoff.

Proving tests:

• crates/udpstp-core/tests/lost_status_backoff.rs::lost_status_pdus_back_the_rate_off_and_confirm_congestion
• crates/udpstp-core/tests/lost_status_backoff.rs::a_backoff_counts_as_an_errored_interval

RFC9097-8.2-L1

Operational

It is of course necessary to calibrate the equipment performing the IP-Layer Capacity measurement, to ensure that the expected capacity can be measured accurately and that equipment choices (processing speed, interface bandwidth, etc.) are suitably matched to the measurement range.

Note: Deployment of the measurement hosts.

RFC9097-8.2-L2

Operational

Samples exhibiting supra-threshold packet losses or increasing queue occupation require a repeated search and/or test at a reduced fixed Sender rate for Qualification.

Note: The Operator repeats the Test; a Fixed-Rate Test serves for Qualification.

RFC9097-8.3-1

Operational

In general, it is RECOMMENDED to locate test endpoints as close to the intended measured link(s) as practical (for reasons of scale, this is not always possible; there is a limit on the number of test endpoints coming from many perspectives – for example, management and measurement traffic).

Note: Deployment of the measurement hosts.

RFC9097-8.3-2

Tested

The testing operator MUST set a value for the MaxHops Parameter, based on the expected path length.

Note: MaxHops setting; RFC 9946 section 10.

Proving tests:

• crates/udpstp/src/start/server.rs::the_server_warns_when_max_hops_is_not_set

RFC9097-8.3-3

Tested

Both load packets and status feedback messages MUST contain sequence numbers; this helps with measurements based on those packets.

Note: lpduSeqNo and spduSeqNo; RFC 9946 section 5.1 item 3.

Proving tests:

• crates/udpstp-core/tests/stale_status_pdus.rs::spdu_seq_err_reports_the_status_pdus_missing_before_the_latest
• crates/udpstp-wire/tests/load_pdu.rs::header_encodes_to_the_rfc_layout
• crates/udpstp-wire/tests/status_pdu.rs::status_pdu_encodes_to_the_rfc_layout

RFC9097-8.3-4

Deviation

Methods MUST be prepared to provide a short preamble transmission to activate on-demand communications access and to discard the preamble from subsequent test results.

Note: RFC 9946 defines no preamble; OB-UDPST’s JSON reports PreambleDuration 0.

Recorded in no-preamble-transmission.

RFC9097-8.3-5

Operational

If this condition is suspected, alternate configurations SHOULD be used.

Note: A shaper or policer whose burst size exceeds the Burst; the user changes the configuration.

RFC9097-8.3-L1

Tested

Each flow would be controlled using its own implementation of the load rate adjustment (search) algorithm.

Note: Each Test Connection of a Multi-Connection Test runs its own Load Rate Adjustment Algorithm.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::each_test_connection_runs_its_own_algorithm

RFC9097-8.3-6

Deviation

The number of concurrent, independent tests of a path SHALL be limited to one.

Note: RFC 9946 section 4.2 says the same.

Recorded in tests-per-source-above-one.

Proving tests:

• crates/udpstp-core/tests/tests_per_source.rs::a_second_test_from_the_same_source_is_refused_at_setup

RFC9097-8.3-L2

Operational

As long as both IPv4 packets and IPv6 packets sent/received are standard-formed, this should be allowed (and the change in header size easily accounted for on a per-packet basis).

Note: Testing a v4-v6 transition mechanism; nothing in udpstp prevents it.

Proving tests:

• crates/udpstp-core/tests/sub_interval_results.rs::over_ipv6_the_headers_are_48_bytes

RFC 9097 §9: Reporting Formats

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.

RFC9097-9-1

Tested

The Singleton IP-Layer Capacity results SHOULD be accompanied by the context under which they were measured. * Timestamp (especially the time when the maximum was observed in dtn). * Source and Destination (by IP or other meaningful ID). * Other inner Parameters of the test case (Section 4). * Outer Parameters, such as “test conducted in motion” or other factors belonging to the context of the measurement. * Result validity (indicating cases where the process was somehow interrupted or the attempt failed). * A field where unusual circumstances could be documented, and another one for “ignore / mask out” purposes in further processing.

Proving tests:

• crates/udpstp/src/results.rs::a_completed_test
• crates/udpstp/src/results.rs::terminal_layout_preserves_measurements_context_and_validity
• crates/udpstp/src/test_results.rs::human_context_preserves_private_identities_and_received_times

RFC9097-9-2

Deviation

The Maximum IP-Layer Capacity results SHOULD be reported in tabular format.

Recorded in compact-human-final-metrics.

Proving tests:

• crates/udpstp/src/results.rs::a_completed_test
• crates/udpstp/src/results.rs::terminal_layout_preserves_measurements_context_and_validity

RFC9097-9-3

Deviation

There SHOULD be a column that identifies the test Phase.

Note: Maximum IP-Layer Capacity table.

Recorded in compact-human-final-metrics.

Conformance Records: results-name-the-phase-and-f.

Proving tests:

• crates/udpstp/src/results.rs::a_completed_test
• crates/udpstp/src/results.rs::terminal_layout_preserves_measurements_context_and_validity

RFC9097-9-4

Deviation

There SHOULD be a column listing the number of flows used in that Phase.

Recorded in compact-human-final-metrics.

Conformance Records: results-name-the-phase-and-f.

Proving tests:

• crates/udpstp/src/results.rs::a_completed_test
• crates/udpstp/src/results.rs::terminal_layout_preserves_measurements_context_and_validity

RFC9097-9-5

Deviation

The remaining columns SHOULD report the following results for the aggregate of all flows, including the Maximum IP-Layer Capacity, the Loss Ratio, the RTT minimum, RTT maximum, and other metrics tested having similar relevance.

Recorded in compact-human-final-metrics.

Proving tests:

• crates/udpstp/src/results.rs::a_completed_test
• crates/udpstp/src/results.rs::terminal_layout_preserves_measurements_context_and_validity

RFC9097-9-6

Tested

As mentioned in Section 6.6, bimodal (or multi-modal) maxima SHALL be reported for each mode separately.

Note: Capacity Modes; restates RFC9097-6.6-3.

Proving tests:

• crates/udpstp/src/json.rs::a_bimodal_test_has_obudpst_keys_and_forms
• crates/udpstp/src/results.rs::a_watchdog_ended_test_with_two_capacity_modes
• crates/udpstp/src/results.rs::terminal_layout_preserves_measurements_context_and_validity
• crates/udpstp-core/src/results.rs::a_split_makes_two_capacity_modes

RFC9097-9-7

Tested

The sub-interval time, dt, MUST accompany a report of Maximum IP- Layer Capacity results, as well as the remaining Parameters from Section 4 (“General Parameters and Definitions”).

Proving tests:

• crates/udpstp/src/results.rs::a_completed_test
• crates/udpstp/src/results.rs::terminal_layout_preserves_measurements_context_and_validity

RFC9097-9-8

Tested

The PM list metrics corresponding to the sub-interval where the Maximum Capacity occurred MUST accompany a report of Maximum IP-Layer Capacity results, for each test Phase.

Proving tests:

• crates/udpstp/src/results.rs::a_completed_test
• crates/udpstp/src/results.rs::terminal_layout_preserves_measurements_context_and_validity
• crates/udpstp/src/results.rs::maxima_keep_measured_rtt_minimum_without_variation

RFC9097-9-9

Tested

The IP-Layer Sender Bit Rate results SHOULD be reported in tabular format.

Proving tests:

• crates/udpstp/src/results.rs::an_upstream_test

RFC9097-9-10

Tested

There SHOULD be a column that identifies the test Phase.

Note: The table of IP-Layer Sender Bit Rates.

Conformance Records: results-name-the-phase-and-f.

Proving tests:

• crates/udpstp/src/results.rs::a_completed_test

RFC9097-9-11

Deviation

There SHOULD be a column listing each individual (numbered) flow used in that Phase, or the aggregate of flows in that Phase.

Recorded in sender-bit-rate-per-sub-interval.

RFC9097-9-12

Deviation

A corresponding column SHOULD identify the specific sending rate sub- interval, stn, for each flow and aggregate.

Recorded in sender-bit-rate-per-sub-interval.

RFC9097-9-13

Tested

A final column SHOULD report the IP-Layer Sender Bit Rate results for each flow used, or the aggregate of all flows.

Proving tests:

• crates/udpstp/src/results.rs::an_upstream_test

RFC9097-9-14

Tested

The sub-interval duration, st, MUST accompany a report of Sender IP- Layer Bit Rate results.

Proving tests:

• crates/udpstp/src/results.rs::an_upstream_test

RFC9097-9-15

Tested

Also, the values of the remaining Parameters from Section 4 (“General Parameters and Definitions”) MUST be reported.

Proving tests:

• crates/udpstp/src/results.rs::an_upstream_test

RFC 9097 §10: Security Considerations

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.

RFC9097-10-1

Operational

Cooperating Source and Destination hosts and agreements to test the path between the hosts are REQUIRED.

Note: Agreements between the parties that run the hosts.

RFC9097-10-2

Tested

It is REQUIRED to have a user client-initiated setup handshake between cooperating hosts that allows firewalls to control inbound unsolicited UDP traffic that goes to either a control port (expected and with authentication) or ephemeral ports that are only created as needed.

Note: Setup exchange on the Standard Port; Test Connections on Ephemeral Ports.

Proving tests:

• crates/udpstp/tests/loopback.rs::test_connections_use_ports_from_the_configured_range
• crates/udpstp-core/tests/setup_exchange.rs::unauthenticated_setup_ends_in_ack_with_a_test_port_when_both_ends_opt_in

RFC9097-10-3

Tested

Client-server authentication and integrity protection for feedback messages conveying measurements are RECOMMENDED.

Note: Authentication Mode 2 (RFC 9946 section 5.3.2).

Proving tests:

• crates/udpstp-core/tests/auth_mode_default.rs::a_server_without_mode_2_is_reported_and_the_client_does_not_fall_back
• crates/udpstp-core/tests/mode2_status.rs::each_status_pdu_is_signed_with_its_sender_s_key

RFC9097-10-4

Tested

Hosts MUST limit the number of simultaneous tests to avoid resource exhaustion and inaccurate results.

Note: Admission.

Proving tests:

• crates/udpstp-core/src/admission.rs::a_cap_full_of_activated_tests_still_refuses
• crates/udpstp-core/tests/unactivated_share.rs::a_new_setup_evicts_the_oldest_unactivated_test_connection

RFC9097-10-5

Tested

Senders MUST be rate limited.

Note: Sending Rate Table; Admitted Rate Cap.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::rows_stay_within_the_table_and_fast_mode_stops_at_1_gbps
• crates/udpstp-core/tests/algorithm_capped.rs::fast_mode_stops_at_the_row_matching_max_bandwidth

RFC9097-10-L1

Tested

The recommended load control search algorithm results in “ramp-up” from the lowest rate in the table.

Note: A Search Test starts at row 0 unless srIndexConf asks otherwise.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::in_fast_mode_each_clean_interval_adds_high_speed_delta_rows
• crates/udpstp-core/tests/algorithm_b.rs::the_default_search_starts_at_row_0

RFC9097-10-6

Tested

Testing with the Service Provider’s measurement hosts SHOULD be limited in frequency and/or overall volume of test traffic (for example, the range of duration values, I, SHOULD be limited).

Note: testIntTime’s maximum.

Proving tests:

• crates/udpstp-core/tests/test_interval_limits.rs::an_ordinary_key_gets_at_most_60_s

RFC 9946 §2: Conventions and Terminology

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.

RFC9946-2-1

Not applicable

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Note: BCP 14 boilerplate: it defines the keywords and requires nothing of an endpoint.

RFC 9946 §3: Scope, Goals, and Applicability

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.

RFC9946-3-L1

Operational

Per [RFC9097], that algorithm must not be used as a general Congestion Control Algorithm (CCA).

Note: A usage statement; RFC9946-5.1-3 says it with a keyword.

RFC 9946 §4: Protocol Overview

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.

RFC9946-4-1

Tested

All messages defined by this document SHALL use UDP transport [RFC0768].

Proving tests:

• crates/udpstp/tests/loopback.rs::a_client_completes_the_control_phase_over_ipv4_loopback

RFC9946-4-L1

Tested

It is the responsibility of the client process to manage the inter-related connections such as handling the individual connection setup successes and failures, cleaning up connections during a test (should some fail), and aggregating the individual test results into an overall set of performance statistics.

Note: Multi-Connection Test: Minimum Test Connections, failed Test Connections, the aggregate Sub-Interval.

Conformance Records: minimum-test-connections, multi-connection-isolated-failures, aggregate-clock-delta-min.

Proving tests:

• crates/udpstp-core/tests/multi_connection_aggregation.rs::the_summed_capacity_never_exceeds_the_shared_bottleneck
• crates/udpstp-core/tests/multi_connection_aggregation.rs::upstream_sub_intervals_are_summed_by_number_and_their_offset_measured
• crates/udpstp-core/tests/multi_connection_failures.rs::the_test_goes_on_when_one_fails_and_enough_remain
• crates/udpstp-core/tests/multi_connection_failures.rs::below_the_minimum_the_rest_are_stopped_and_released
• crates/udpstp-core/tests/multi_connection_failures.rs::test_connections_that_fall_silent_together_stop_the_test
• crates/udpstp-core/tests/multi_connection_failures.rs::failures_are_counted_until_too_few_remain
• crates/udpstp-core/tests/multi_connection_failures.rs::failures_apart_are_isolated_ones
• crates/udpstp-core/tests/multi_connection_start.rs::too_few_setups_abort_the_test_before_any_activation
• crates/udpstp-core/tests/multi_connection_start.rs::a_lower_minimum_goes_on_with_the_setups_that_succeeded
• crates/udpstp-core/tests/multi_connection_start.rs::an_unanswered_setup_is_given_up_once_enough_have_succeeded
• crates/udpstp-core/tests/multi_connection_start.rs::servers_that_set_different_parameters_abort_the_test
• crates/udpstp-core/tests/multi_connection_start.rs::an_acceptance_that_arrives_after_the_abort_is_stopped_at_once

RFC9946-4-L2

Tested

The server instance(s) would process each connection independently, as if they were coming from separate clients.

Conformance Records: multi-connection-agreement-checks.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::each_test_connection_runs_its_own_algorithm

RFC9946-4-L3

Tested

Test Setup Request and Response: If a server instance is identified with a host name that resolves to both IPv4/IPv6 addresses, it is recommended to use the first address returned in the name resolution response, regardless of whether it is IPv4 or IPv6.

Note: Client host name resolution.

Proving tests:

• crates/udpstp/tests/loopback.rs::a_client_resolves_a_host_name

RFC9946-4-L4

Tested

Distinct UDP port numbers will be assigned if all Setup Response messages originate from the same server in that case.

Note: An Ephemeral Port per Test Connection.

Proving tests:

• crates/udpstp-core/tests/multi_connection_start.rs::every_setup_goes_out_before_the_activations_which_go_out_together

RFC9946-4.1-1

Operational

Fixed-rate testing SHOULD only be activated for operation and maintenance purposes by operators within their local network domain.

Note: Who runs a Fixed-Rate Test, and where; the software limits it to Operator Keys (RFC9946-4.1-3).

RFC9946-4.1-2

Operational

If a subscriber requests a diagnostic test from the network operator, it strongly implies that there is no certainty on the bottleneck capacity and initiating a UDP Speed Test based on the load adjustment algorithm is RECOMMENDED.

Note: An operator’s choice of test.

RFC9946-4.1-3

Tested

To protect against misuse, a client (and in general, a consumer) MUST NOT be able to initiate a fixed-rate test.

Note: A Fixed-Rate Test needs an Operator Key.

Conformance Records: fixed-rate-needs-operator-key.

Proving tests:

• crates/udpstp-core/tests/fixed_rate.rs::a_fixed_rate_test_is_refused_without_an_operator_key
• crates/udpstp-core/tests/fixed_rate.rs::a_refused_downstream_fixed_rate_test_sends_no_load

RFC9946-4.1-L1

Tested

A network operator may conduct a fixed-rate test for a stable measurement at or near the maximum determined by the load rate adjustment algorithm for debugging purposes.

Note: srIndexConf a row with CHTA_SRIDX_ISSTART clear, under an Operator Key.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::a_fixed_rate_test_holds_its_row
• crates/udpstp-core/tests/fixed_rate.rs::an_operator_runs_a_fixed_rate_test_at_the_requested_row

RFC9946-4.2-L1

Operational

Measurements that generate traffic on shared paths (including Wi-Fi and Internet paths) need to consider the impact on other traffic.

Note: A deployment statement.

RFC9946-4.2-L2

Operational

Fixed-rate testing operates without congestion control and therefore must not be executed over other operators’ network segments.

Note: Where an operator runs a Fixed-Rate Test.

RFC9946-4.2-L3

Operational

Fixed- rate testing, therefore, is limited to paths within a domain entirely managed and operated section-wise and end-to-end by the network operator performing the measurement.

Note: Where an operator runs a Fixed-Rate Test.

RFC9946-4.2-L4

Operational

When the risks of disruption to other flows has been considered, testing could be extended to include adjacent operational domains for which there is also a testing agreement.

Note: Where an operator runs a Fixed-Rate Test.

RFC9946-4.2-1

Deviation

The number of concurrent independent tests of a path SHALL be limited to one, regardless of the number of flows.

Note: Server admission: one activated Test per source.

Recorded in tests-per-source-above-one.

Conformance Records: path-approximated-by-source.

Proving tests:

• crates/udpstp-core/src/admission.rs::the_test_connections_of_one_test_are_one_test
• crates/udpstp-core/tests/tests_per_source.rs::a_second_test_from_the_same_source_is_refused_at_setup
• crates/udpstp-core/tests/tests_per_source.rs::of_two_tests_set_up_together_the_second_is_refused_at_activation

RFC9946-4.2-L5

Tested

A load rate adjustment algorithm (see Section 5.1) is required to mitigate the impact of this congestion and to limit the duration of any congestion by terminating the test when sudden impairments or a loss of connectivity is detected.

Conformance Records: multi-connection-path-failure.

Proving tests:

• crates/udpstp-core/tests/multi_connection_failures.rs::test_connections_that_fall_silent_together_stop_the_test

RFC 9946 §5: Requirements, Security Operations, and Optional Checksum

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.

RFC9946-5-L1

Tested

Due to the additional complexities, and loss of the direct mapping of packets to datagrams between Layer 3 and Layer 4, it is recommended that Layer 3 fragmentation be avoided.

Note: Default datagram sizes fit a traditional MTU.

Proving tests:

• crates/udpstp-core/src/sending_rate_table.rs::packet_sizes_follow_the_modifiers_and_the_mtu

RFC9946-5-1

Deviation

Unless IP fragmentation is expected, and is one of the attributes being measured, the IPv4 Don’t Fragment (DF) bit SHOULD be set for all tests.

Note: The dont_fragment setting, on by default.

Recorded in windows-dont-fragment-unset.

Proving tests:

• crates/udpstp/tests/netns.rs::downstream_and_upstream_tests_measure_the_bottleneck
• crates/udpstp-runtime/src/ip_options.rs::test_traffic_carries_df_and_max_hops

RFC9946-5-L2

Tested

Note: When this specification is used for network debugging, it may be useful for fragmentation to be under the control of the test administrator.

Note: The dont_fragment setting.

Proving tests:

• crates/udpstp/tests/cli.rs::the_admission_limits_are_server_settings

RFC9946-5-2

Not applicable

This section specifies generic requirements, which a measurement load rate adjustment algorithm conforming to this specification MUST fulfill.

Note: An introduction to the section’s Requirements, each recorded with its own ID; nothing to do beyond them.

RFC9946-5.1-1

Not applicable

Load rate adjustment algorithms for capacity measurement MUST comply with the requirements specified by this section.

Note: An introduction to the section’s Requirements, each recorded with its own ID; nothing to do beyond them.

RFC9946-5.1-2

Not applicable

New standard load rate adjustment algorithms for capacity measurement MUST be reviewed by IETF designated experts prior to assignment of a code point in the “Test Activation PDU Rate Adjustment Algo” registry.

Note: An IANA registration process, not endpoint behaviour.

RFC9946-5.1-3

Operational

The measurement load rate adjustment algorithm described in this section MUST NOT be used as a general CCA.

Note: A usage statement: udpstp runs the algorithm only within a Test.

RFC9946-5.1-4

Operational

This specification MUST only be used in the application of diagnostic and operations measurements.

Note: A usage statement.

RFC9946-5.1-5

Tested

Both Load PDU messages and Status Feedback PDU messages MUST contain sequence numbers.

Note: lpduSeqNo and spduSeqNo fields.

Proving tests:

• crates/udpstp-core/tests/status_pdus.rs::status_pdus_follow_the_first_load_pdu_every_trial_interval

RFC9946-5.1-6

Tested

The nominal duration of a measurement interval at the Destination, parameter testIntTime (“I” in [RFC9097]), MUST default to a value of no more than 10 seconds.

Note: testIntTime default.

Proving tests:

• crates/udpstp-core/tests/parameter_ranges.rs::the_client_asks_for_the_defaults

RFC9946-5.1-7

Tested

A high-speed mode to achieve high sending rates quickly MUST reduce the measurement load below a level for which the first feedback interval inferred “congestion” from the measurements.

Note: Fast Mode’s drop when Congestion is confirmed.

Conformance Records: fast-mode-stops-at-the-gigabit-row, confirming-drop-below-the-gigabit-row-only.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::congestion_is_confirmed_by_back_to_back_errored_intervals
• crates/udpstp-core/tests/algorithm_b.rs::the_confirming_drop_stops_at_row_0_and_follows_the_row_it_starts_from

RFC9946-5.1-L1

Tested

Consecutive feedback intervals that have a supra-threshold count of sequence number anomalies and/or contain an upper delay variation threshold exception in all of the consecutive intervals indicate “congestion” within a test.

Note: Congestion Confirmed after slowAdjThresh Errored Intervals back to back (ADR 0005).

Conformance Records: latched-congestion-confirmed.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::congestion_is_confirmed_by_back_to_back_errored_intervals
• crates/udpstp-core/tests/algorithm_b.rs::intermittent_errored_intervals_do_not_confirm_congestion

RFC9946-5.1-8

Deviation

The threshold of consecutive feedback intervals SHALL be configurable with a default of 3 intervals and a maximum duration to infer congestion of 500 ms (milliseconds).

Note: slowAdjThresh and trialInt.

Recorded in operator-keys-exempt-from-500-ms-congestion-inference.

Conformance Records: congestion-inference-within-500-ms.

Proving tests:

• crates/udpstp-core/tests/algorithm_b.rs::the_accepted_parameters_drive_the_algorithm
• crates/udpstp-core/tests/test_interval_limits.rs::slow_adj_thresh_times_trial_int_is_at_most_500_ms

RFC9946-5.1-9

Tested

Congestion MUST be indicated if the Status Feedback PDUs indicate that either sequence number anomalies were detected OR the delay range was above the upper delay variation threshold.

Note: seqErrThresh and upperThresh.

Conformance Records: clean-needs-delay-var-below-low-thresh, seq-err-thresh-always-applied, no-delay-sample-is-never-clean.

Proving tests:

• crates/udpstp-core/tests/interval_classification.rs::the_average_rounds_and_clean_is_strictly_below_the_low_threshold
• crates/udpstp-core/tests/interval_classification.rs::the_maximum_is_the_default_and_the_average_a_setting
• crates/udpstp-core/tests/interval_classification.rs::no_delay_samples_is_never_clean
• crates/udpstp-core/tests/interval_classification.rs::seq_err_thresh_is_always_applied
• crates/udpstp-core/tests/interval_classification.rs::an_upstream_server_classifies_the_status_pdus_it_sends

RFC9946-5.1-10

Tested

The RECOMMENDED threshold values are 10 for sequence number gaps, 30 ms for lower delay variation thresholds, and 90 ms for upper delay variation thresholds.

Note: seqErrThresh, lowThresh and upperThresh defaults.

Proving tests:

• crates/udpstp-core/tests/parameter_ranges.rs::the_client_asks_for_the_defaults

RFC9946-5.1-11

Tested

The load rate adjustment algorithm MUST include a Load PDU timeout and a Status PDU timeout, which both stop the test when received PDU streams cease unexpectedly.

Note: ADR 0002 reconciles them with the Section 6.1 Watchdog.

Conformance Records: receive-timeouts-stop-sending-at-1s, receive-timeouts-run-from-data-phase-start.

Proving tests:

• crates/udpstp/tests/loopback.rs::the_client_reports_a_server_that_goes_away
• crates/udpstp-core/tests/timeouts.rs::a_downstream_path_that_breaks_stops_within_1_s_and_ends_at_3_s
• crates/udpstp-core/tests/timeouts.rs::an_upstream_client_stops_when_status_pdus_stop
• crates/udpstp-core/tests/timeouts.rs::load_pdus_failing_the_checksum_do_not_reset_the_watchdog

RFC9946-5.1-12

Tested

The Load PDU timeout SHALL be reset to the configured value each time a Load PDU is received.

Proving tests:

• crates/udpstp-core/tests/timeouts.rs::rx_stopped_clears_when_traffic_comes_back_in_time

RFC9946-5.1-13

Tested

If the Load PDU timeout expires, the receiver SHALL be closed and no further Status PDU feedback sent.

Conformance Records: receive-timeout-is-final.

Proving tests:

• crates/udpstp-core/tests/timeouts.rs::a_downstream_path_that_breaks_stops_within_1_s_and_ends_at_3_s
• crates/udpstp-core/tests/timeouts.rs::an_upstream_client_stops_when_status_pdus_stop

RFC9946-5.1-14

Tested

The default Load PDU timeout MUST be no more than 1 second.

Proving tests:

• crates/udpstp/tests/loopback.rs::the_client_reports_a_server_that_goes_away
• crates/udpstp-core/tests/timeouts.rs::a_downstream_path_that_breaks_stops_within_1_s_and_ends_at_3_s

RFC9946-5.1-15

Tested

The Status PDU timeout SHALL be reset to the configured value each time a feedback message is received.

Proving tests:

• crates/udpstp-core/tests/stale_status_pdus.rs::a_stale_status_pdu_still_counts_as_heard

RFC9946-5.1-16

Tested

If the Status PDU timeout expires, the sender SHALL be closed and no further load packets sent.

Conformance Records: receive-timeout-is-final.

Proving tests:

• crates/udpstp-core/tests/timeouts.rs::a_downstream_path_that_breaks_stops_within_1_s_and_ends_at_3_s
• crates/udpstp-core/tests/timeouts.rs::an_upstream_client_stops_when_status_pdus_stop

RFC9946-5.1-17

Tested

The default Status PDU timeout MUST be no more than 1 second.

Proving tests:

• crates/udpstp-core/tests/timeouts.rs::a_downstream_path_that_breaks_stops_within_1_s_and_ends_at_3_s
• crates/udpstp-core/tests/timeouts.rs::an_upstream_client_stops_when_status_pdus_stop

RFC9946-5.1-18

Tested

A network operator who is certain of the IP-Layer Capacity to be validated MAY start with a fixed-rate test at the IP-Layer Capacity and avoid activating the measurement load rate adjustment algorithm (see Section 8.1 of [RFC9097]).

Note: A Fixed-Rate Test under an Operator Key.

Proving tests:

• crates/udpstp/tests/interop.rs::unauthenticated_and_fixed_rate_tests_interoperate
• crates/udpstp/tests/loopback.rs::fixed_rate_tests_complete_over_loopback

RFC9946-5.1-19

Operational

However, the stimulus for a diagnostic test (such as a subscriber request) strongly implies that there is no certainty, and the load adjustment algorithm is RECOMMENDED.

Note: An operator’s choice of test.

RFC9946-5.1-20

Operational

This specification MUST only be used in circumstances consistent with Section 10 (Security Considerations) of [RFC9097].

Note: A usage statement.

RFC9946-5.3-1

Deviation

A REQUIRED mode with authentication during the Control phase (Test Setup and Test Activation exchanges).

Note: Authentication Mode 1; authMode field.

Recorded in unauthenticated-mode.

Proving tests:

• crates/udpstp/tests/interop.rs::our_client_completes_a_mode_1_downstream_test_against_obudpst
• crates/udpstp/tests/loopback.rs::a_mode1_test_runs_with_a_toml_key_table_and_an_obudpst_key_file
• crates/udpstp-core/tests/activation_mode1.rs::mode1_tests_are_activated_in_both_directions
• crates/udpstp-core/tests/setup_mode1.rs::mode1_setup_between_our_cores_is_accepted

RFC9946-5.3-2

Tested

An OPTIONAL mode with the additional authentication of the Status Feedback messages during the Data phase.

Note: Authentication Mode 2; authMode field.

Proving tests:

• crates/udpstp/tests/loopback.rs::a_mode2_test_completes_both_ways

RFC9946-5.3.1-1

Tested

In this mode, the client and the server SHALL be configured to use one of a number of shared secret keys, designated via the numeric keyId field (see Section 5.4).

Note: keyId field; the Key Table.

Proving tests:

• crates/udpstp/tests/loopback.rs::a_mode1_test_runs_with_a_toml_key_table_and_an_obudpst_key_file

RFC9946-5.3.1-2

Tested

This key SHALL be used as input to the KDF, as specified in Section 5.4.1, to obtain the actual keys used by the client and server for authentication.

Proving tests:

• crates/udpstp-core/tests/setup_mode1.rs::server_drops_a_request_signed_with_the_shared_key_itself

RFC9946-5.3.1-3

Tested

During the Control phase, the sender SHALL read the current system (wall-clock) time and populate the authUnixTime field and next calculate the 32-octet HMAC-SHA-256 hash of the entire PDU according to Section 6 of [RFC6234] (with the authDigest and checkSum preset to all zeroes).

Note: authUnixTime and authDigest fields.

Proving tests:

• crates/udpstp-core/tests/activation_mode1.rs::server_answers_a_signed_activation_with_a_response_signed_with_the_server_key
• crates/udpstp-core/tests/activation_mode1.rs::client_signs_its_activation_request_with_the_client_key
• crates/udpstp-core/tests/setup_mode1.rs::server_accepts_a_request_signed_with_the_client_key_and_answers_with_the_server_key
• crates/udpstp-core/tests/setup_mode1.rs::client_signs_its_setup_request_with_the_client_key_from_its_own_auth_unix_time
• crates/udpstp-wire/tests/hmac_rfc4231.rs::hmac_sha256_matches_every_rfc_4231_test_case
• crates/udpstp-wire/tests/obudpst_control_kat.rs::our_wire_layer_reproduces_every_obudpst_pdu_from_its_fields

RFC9946-5.3.1-L1

Tested

The authDigest field is filled by the result, then the packet is sent to the receiver.

Note: authDigest field.

Proving tests:

• crates/udpstp-core/tests/activation_mode1.rs::client_signs_its_activation_request_with_the_client_key
• crates/udpstp-core/tests/setup_mode1.rs::client_signs_its_setup_request_with_the_client_key_from_its_own_auth_unix_time

RFC9946-5.3.1-4

Tested

The value in the authUnixTime field is a 32-bit timestamp, and a 10-second tolerance window (+/- 5 seconds) SHALL be used by the receiver to distinguish a subsequent replay of a PDU.

Note: authUnixTime field; the replay cache.

Conformance Records: auth-time-window-inclusive-modulo-2-32, replay-cache-for-setup-requests, replay-cache-activation-keyed-on-sender, replay-cache-lifetime-and-capacity.

Proving tests:

• crates/udpstp-core/tests/activation_mode1.rs::server_silently_drops_activations_that_fail_verification
• crates/udpstp-core/tests/activation_mode1.rs::server_accepts_an_activation_time_5_s_off
• crates/udpstp-core/tests/activation_mode1.rs::client_ignores_responses_that_fail_verification
• crates/udpstp-core/tests/setup_mode1.rs::clocks_five_seconds_apart_are_within_the_window
• crates/udpstp-core/tests/setup_mode1.rs::server_silently_drops_a_setup_more_than_five_seconds_off
• crates/udpstp-core/tests/setup_mode1.rs::setup_is_accepted_across_the_2106_wraparound
• crates/udpstp-core/tests/setup_mode1.rs::client_ignores_a_response_more_than_five_seconds_off

RFC9946-5.3.1-L2

Not applicable

See Table 2 of [TR-471] for a recommended timestamp resolution.

Note: A pointer to TR-471’s recommended timestamp resolution, not a behaviour; authUnixTime is whole seconds as the PDU defines it.

RFC9946-5.3.1-5

Tested

Upon reception, the receiver SHALL validate the message PDU for correct length, validity of authDigest, immediacy of authUnixTime, and expected formatting (PDU-specific fields are also checked, such as protocol version).

Proving tests:

• crates/udpstp-core/tests/activation_mode1.rs::server_silently_drops_activations_that_fail_verification
• crates/udpstp-core/tests/activation_mode1.rs::server_verifies_the_digest_over_the_bytes_received
• crates/udpstp-core/tests/activation_mode1.rs::client_ignores_responses_that_fail_verification

RFC9946-5.3.1-L3

Tested

Validation of the authDigest requires that it be extracted from the PDU and the field, along with the checkSum field, zeroed prior to the Hashed Message Authentication Code (HMAC) calculation used for comparison (see Section 7.2 of [RFC9145]).

Proving tests:

• crates/udpstp-core/tests/setup_mode1.rs::server_verifies_the_digest_over_the_bytes_received
• crates/udpstp-core/tests/setup_mode1.rs::server_accepts_a_request_whose_checksum_was_filled_after_the_digest
• crates/udpstp-wire/tests/null_pdu.rs::a_signed_null_pdu_verifies_as_received
• crates/udpstp-wire/tests/obudpst_control_kat.rs::our_wire_layer_verifies_every_obudpst_digest

RFC9946-5.3.1-6

Tested

If the validation fails, the receiver SHOULD NOT continue with the Control phase and SHOULD implement silent rejection (no further packets sent on the address/port pairs).

Proving tests:

• crates/udpstp-core/tests/activation_mode1.rs::server_silently_drops_activations_that_fail_verification
• crates/udpstp-core/tests/key_table.rs::a_key_outside_its_accept_lifetime_is_an_authentication_failure
• crates/udpstp-core/tests/setup_mode1.rs::server_silently_drops_a_setup_signed_from_a_different_shared_key
• crates/udpstp-core/tests/setup_mode1.rs::server_silently_drops_a_setup_whose_key_id_it_does_not_have
• crates/udpstp-core/tests/setup_mode1.rs::server_silently_drops_a_setup_more_than_five_seconds_off
• crates/udpstp-core/tests/troubleshooting_mode.rs::by_default_authentication_failures_are_silent
• crates/udpstp-core/tests/troubleshooting_mode.rs::a_failed_activation_request_stays_silent_in_troubleshooting_mode

RFC9946-5.3.1-L4

Tested

The exception is when the testing hosts have been configured for troubleshooting Control phase failures and rejection messages will aid in the process.

Note: Permits reporting a failed validation when configured for troubleshooting.

Proving tests:

• crates/udpstp-core/tests/troubleshooting_mode.rs::an_unknown_key_id_is_answered_with_authfail
• crates/udpstp-core/tests/troubleshooting_mode.rs::a_time_outside_the_window_is_answered_with_a_signed_authtime
• crates/udpstp-core/tests/troubleshooting_mode.rs::an_unauthenticated_request_is_answered_with_authreq
• crates/udpstp-core/tests/troubleshooting_mode.rs::an_authenticated_request_to_a_server_without_keys_is_answered_with_authnc
• crates/udpstp-core/tests/troubleshooting_mode.rs::an_unsupported_mode_is_answered_with_authinv

RFC9946-5.3.1-7

Tested

If the validation succeeds, the receiver SHALL continue with the Control phase and compose a successful response or a response indicating the error conditions identified (if any).

Proving tests:

• crates/udpstp-core/tests/setup_mode1.rs::mode1_setup_between_our_cores_is_accepted

RFC9946-5.3.1-8

Tested

This process SHALL be executed for the request and response in the Test Setup exchange, including the Null Request (Section 6) and the Test Activation exchange (Section 7).

Proving tests:

• crates/udpstp-core/tests/activation_mode1.rs::server_answers_a_signed_activation_with_a_response_signed_with_the_server_key
• crates/udpstp-core/tests/null_request.rs::a_mode_1_null_request_is_signed_with_the_server_key
• crates/udpstp-core/tests/setup_mode1.rs::mode1_setup_between_our_cores_is_accepted

RFC9946-5.3.2-1

Tested

When using the optional authentication during the Data phase, authentication SHALL also be applied to the Status Feedback PDU (see Section 8.2).

Proving tests:

• crates/udpstp/tests/loopback.rs::a_mode2_test_completes_both_ways
• crates/udpstp-core/tests/mode2_status.rs::each_status_pdu_is_signed_with_its_sender_s_key
• crates/udpstp-core/tests/mode2_status.rs::a_client_s_early_stop_is_authenticated

RFC9946-5.3.2-2

Tested

The Status PDU sender SHALL 1) read the current system (wall-clock) time and populate the authUnixTime field, 2) calculate the authDigest field of the entire Status PDU (with the authDigest and checkSum preset to all zeroes), and 3) send the packet to the receiver.

Note: Status PDU authUnixTime and authDigest fields.

Proving tests:

• crates/udpstp/tests/loopback.rs::a_mode2_test_completes_both_ways
• crates/udpstp-core/tests/mode2_status.rs::each_status_pdu_is_signed_with_its_sender_s_key
• crates/udpstp-wire/tests/status_pdu.rs::a_signed_status_pdu_verifies_as_received
• crates/udpstp-wire/tests/status_pdu.rs::verification_covers_every_byte_but_the_digest_and_checksum

RFC9946-5.3.2-L1

Tested

The values of authUnixTime field and authDigest field are determined as defined by Section 5.3.1.

Proving tests:

• crates/udpstp-core/tests/mode2_status.rs::each_status_pdu_is_signed_with_its_sender_s_key

RFC9946-5.3.2-3

Tested

Upon reception, the receiver SHALL validate the message PDU for correct length, validity of authDigest, immediacy of authUnixTime, and expected formatting (PDU-specific fields are also checked, such as protocol version).

Proving tests:

• crates/udpstp-core/src/data_phase.rs::a_status_pdu_must_pass_every_mode_2_check
• crates/udpstp-core/tests/mode2_status.rs::each_status_pdu_is_signed_with_its_sender_s_key

RFC9946-5.3.2-L2

Tested

Validation of the authDigest will require that it be extracted from the PDU and the field, along with the checkSum field, zeroed prior to the HMAC calculation used for comparison.

Proving tests:

• crates/udpstp-wire/tests/status_pdu.rs::a_signed_status_pdu_verifies_as_received

RFC9946-5.3.2-4

Tested

If the authentication validation fails, the receiver SHALL ignore the message.

Proving tests:

• crates/udpstp-core/tests/mode2_status.rs::failing_status_pdus_are_ignored_until_the_watchdog_ends_the_test

RFC9946-5.3.2-5

Tested

If the watchdog timer expires (due to successive failed validations), the test session will prematurely terminate (and no further load traffic SHALL be transmitted).

Proving tests:

• crates/udpstp-core/tests/mode2_status.rs::failing_status_pdus_are_ignored_until_the_watchdog_ends_the_test

RFC9946-5.3.2-6

Tested

If this optional mode has not been selected, then the keyId, authUnixTime, and authDigest fields of the Status PDU (see Section 8.2) SHALL be set to all zeroes.

Note: Status PDU keyId, authUnixTime and authDigest fields.

Conformance Records: status-pdu-auth-fields-ignored-outside-mode-2.

Proving tests:

• crates/udpstp-core/tests/mode2_status.rs::in_mode_1_the_status_pdu_s_authentication_fields_are_zero
• crates/udpstp-core/tests/status_pdus.rs::status_pdus_carry_the_auth_mode_and_zero_auth_fields
• crates/udpstp-core/tests/upstream.rs::the_server_sends_status_pdus_with_its_row

RFC9946-5.4-1

Tested

The key table SHALL be used with the REQUIRED authentication mode and the OPTIONAL authentication mode (using the same key).

Proving tests:

• crates/udpstp/tests/loopback.rs::a_mode2_test_completes_both_ways
• crates/udpstp-core/tests/mode2_status.rs::each_status_pdu_is_signed_with_its_sender_s_key

RFC9946-5.4-2

Tested

For authentication, this key SHALL only be used as input to the KDF, as specified in Section 5.4.1, to derive the actual keys used for authentication processing.

Proving tests:

• crates/udpstp-core/tests/setup_mode1.rs::server_drops_a_request_signed_with_the_shared_key_itself

RFC9946-5.4-3

Tested

The key table SHALL have (at least) the following fields per Section 2 of [RFC7210]: * AdminKeyName * LocalKeyName * KDF * AlgID * Key * SendLifetimeStart * SendLifeTimeEnd * AcceptLifeTimeStart * AcceptLifeTimeEnd

Note: The TOML Key Table.

Conformance Records: key-table-lifetimes, key-table-alg-id, key-table-operator-extension.

Proving tests:

• crates/udpstp/tests/key_files.rs::the_server_loads_a_toml_key_table
• crates/udpstp-core/tests/key_table.rs::a_key_outside_its_accept_lifetime_is_an_authentication_failure
• crates/udpstp-core/tests/key_table.rs::a_key_is_accepted_on_the_edges_of_its_accept_lifetime
• crates/udpstp-core/tests/key_table.rs::a_shared_key_id_uses_the_row_valid_at_the_time
• crates/udpstp-core/tests/key_table.rs::the_client_sends_with_the_newest_valid_key

RFC9946-5.4-4

Tested

The LocalKeyName SHALL be determined from the corresponding keyId field in the PDUs that follow.

Note: keyId field.

Conformance Records: key-table-alg-id.

Proving tests:

• crates/udpstp-core/tests/setup_mode1.rs::server_silently_drops_a_setup_whose_key_id_it_does_not_have

RFC9946-5.4.1-1

Tested

The KDF algorithm SHALL be a Key Derivation Function in Counter Mode, as specified in Section 4.1 of [NIST800-108].

Proving tests:

• crates/udpstp-wire/tests/kdf_kat.rs::derived_keys_match_every_openssl_vector

RFC9946-5.4.1-2

Tested

The Pseudorandom Function (PRF) used in the KDF SHALL be HMAC-SHA-256, as defined in Section 6 of [RFC6234].

Proving tests:

• crates/udpstp-wire/tests/kdf_kat.rs::derived_keys_match_every_openssl_vector

RFC9946-5.4.1-3

Tested

The KDF SHALL use the following parameters: * Kin (key-derivation key): The shared key as identified by the keyId field in the PDU. * Label: The fixed string “UDPSTP” (without quotes), encoded as a UTF-8 string, used to bind the derived keys to this specific protocol. * Context: The UTF-8 string representation of the authUnixTime field received in the very first Setup Request PDU sent from the client to the server. This ensures that the derived keys are unique to the session and tied to the temporal context of the initial setup exchange. The authUnixTime field serves as a nonce and is protected from modification by the HMAC-SHA-256 hash present in the authDigest field. * r: The length of the binary encoding of the counter SHALL be 32 (bits).

Note: The fixed input is laid out as Appendix A builds it.

Conformance Records: kdf-appendix-a-layout.

Proving tests:

• crates/udpstp-core/tests/setup_mode1.rs::server_accepts_a_request_signed_with_the_client_key_and_answers_with_the_server_key
• crates/udpstp-core/tests/setup_mode1.rs::server_drops_a_request_whose_keys_come_from_another_auth_unix_time
• crates/udpstp-core/tests/setup_mode1.rs::client_signs_its_setup_request_with_the_client_key_from_its_own_auth_unix_time
• crates/udpstp-wire/tests/kdf_kat.rs::derived_keys_match_every_openssl_vector

RFC9946-5.4.1-4

Tested

The length of the binary encoding of the counter SHALL be 32 (bits).

Note: The r parameter.

Proving tests:

• crates/udpstp-wire/tests/kdf_kat.rs::derived_keys_match_every_openssl_vector

RFC9946-5.4.1-5

Tested

The total derived key material SHALL be 512 bits (64 octets) in length.

Proving tests:

• crates/udpstp-wire/tests/kdf_kat.rs::derived_keys_match_every_openssl_vector

RFC9946-5.4.1-6

Tested

The key material SHALL be structured as follows, from most significant bit (MSB) to least significant bit (LSB): * Client Authentication Key: 256 bits (32 octets); used for authenticating messages sent by the client. * Server Authentication Key: 256 bits (32 octets); used for authenticating messages sent by the server.

Proving tests:

• crates/udpstp-core/tests/activation_mode1.rs::server_answers_a_signed_activation_with_a_response_signed_with_the_server_key
• crates/udpstp-core/tests/activation_mode1.rs::client_signs_its_activation_request_with_the_client_key
• crates/udpstp-core/tests/mode2_status.rs::each_status_pdu_is_signed_with_its_sender_s_key
• crates/udpstp-core/tests/setup_mode1.rs::server_accepts_a_request_signed_with_the_client_key_and_answers_with_the_server_key
• crates/udpstp-core/tests/setup_mode1.rs::server_drops_a_request_signed_with_the_server_key
• crates/udpstp-core/tests/setup_mode1.rs::client_signs_its_setup_request_with_the_client_key_from_its_own_auth_unix_time
• crates/udpstp-core/tests/setup_mode1.rs::client_ignores_a_response_signed_with_the_client_key
• crates/udpstp-wire/tests/kdf_kat.rs::derived_keys_match_every_openssl_vector
• crates/udpstp-wire/tests/obudpst_control_kat.rs::our_wire_layer_verifies_every_obudpst_digest

RFC9946-5.4.1-7

Tested

If authentication of the initial Setup Request PDU received by the server fails, due to an invalid authDigest field, any and all derived keying material and keys SHALL be considered invalid.

Conformance Records: derived-keys-depend-only-on-the-row-and-time.

Proving tests:

• crates/udpstp-core/tests/setup_mode1.rs::server_silently_drops_a_setup_signed_from_a_different_shared_key

RFC9946-5.4.1-8

Tested

The key material derived from the initial Setup Request PDU, either at the client prior to transmission or at the server upon reception, SHALL be used for all subsequent PDUs sent between them for that test connection.

Conformance Records: activation-auth-matches-setup.

Proving tests:

• crates/udpstp-core/tests/activation_mode1.rs::server_answers_a_signed_activation_with_a_response_signed_with_the_server_key
• crates/udpstp-core/tests/activation_mode1.rs::client_signs_its_activation_request_with_the_client_key
• crates/udpstp-core/tests/setup_mode1.rs::server_accepts_a_request_signed_with_the_client_key_and_answers_with_the_server_key

RFC9946-5.5-L1

Operational

Successful interaction with a local firewall assumes the firewall is configured to allow a host to open a bidirectional connection using unique source and destination addresses as well as port numbers (i.e., a 4-tuple) by sending a packet using that 4-tuple for a given transport protocol.

Note: Client-side firewall configuration.

RFC9946-5.5-1

Operational

The firewall at the server MUST be configured with an open pinhole for the server IP address and standard UDP port number of the server.

Note: Server firewall configuration.

RFC9946-5.5-2

Tested

Assuming that the firewall administration at the server does not allow an open UDP ephemeral port range, then the server MUST send a Null Request to the client from the ephemeral port number communicated to the client in the Test Setup Response.

Note: Null Request, sent from the Ephemeral Port.

Proving tests:

• crates/udpstp/tests/netns.rs::a_stateful_firewall_needs_only_the_standard_port_open
• crates/udpstp-core/tests/null_request.rs::the_server_sends_a_null_request_after_the_setup_response

RFC9946-5.5-L2

Tested

If the server firewall administration allows an open UDP ephemeral port range, then the Null Request is not strictly necessary.

Note: Permits leaving out the Null Request.

Proving tests:

• crates/udpstp-core/tests/null_request.rs::a_forged_or_missing_null_request_changes_nothing

RFC9946-5.6-1

Operational

The protocol MUST utilize the standard UDP checksum for all IPv4 and IPv6 datagrams it sends.

Note: The operating system’s UDP stack computes the UDP checksum; udpstp never turns it off (no SO_NO_CHECK), and IPv6 requires it.

RFC9946-5.6-L1

Tested

All of the PDUs exchanged between the client and server support an optional header checksum that covers the various fields in the UDPSTP PDU (excluding the payload content of the Load PDU and, to be clear, also the IP and UDP headers).

Note: checkSum field.

Proving tests:

• crates/udpstp-wire/tests/load_pdu.rs::load_header_checksum_covers_the_header_only

RFC9946-5.6-L2

Tested

The calculation is the same as the 16-bit one’s complement Internet checksum used in the IPv4 packet Header Checksum specification (see Section 3.1 of [RFC0791]).

Note: checkSum field.

Proving tests:

• crates/udpstp-wire/tests/load_pdu.rs::internet_checksum_matches_the_rfc_1071_example
• crates/udpstp-wire/tests/load_pdu.rs::internet_checksum_pads_an_odd_length
• crates/udpstp-wire/tests/load_pdu.rs::internet_checksum_folds_every_carry

RFC9946-5.6-2

Operational

However, all UDPSTP datagrams transmitted via IPv4 or IPv6 SHALL include a standard UDP checksum to protect other potential recipients to whom a corrupted packet may be delivered.

Note: The operating system’s UDP stack computes the UDP checksum; udpstp never turns it off (no SO_NO_CHECK), and IPv6 requires it.

RFC9946-5.6-L3

Not applicable

In the case of a nonstandard network API, one option to reduce processing overhead may be to restrict testing to only utilize a payload content of all zeros so that the UDP checksum calculation need not include it for Load PDUs.

Note: udpstp sends through the standard socket API.

RFC9946-5.6-3

Tested

If a PDU sender is populating the checkSum field, it SHALL do so as the last step after the PDU is built in all other respects (with the checkSum field set to zero prior to the calculation).

Note: checkSum field.

Conformance Records: zero-checksum-sent-as-ffff.

Proving tests:

• crates/udpstp-core/tests/control_checksum.rs::every_control_pdu_carries_a_checksum_that_verifies
• crates/udpstp-core/tests/downstream_load.rs::the_server_fills_the_header_checksum_when_configured
• crates/udpstp-core/tests/status_pdus.rs::status_pdus_carry_a_checksum_when_configured
• crates/udpstp-wire/tests/control_checksum.rs::a_zero_checksum_is_sent_as_ffff
• crates/udpstp-wire/tests/load_pdu.rs::load_header_checksum_covers_the_header_only
• crates/udpstp-wire/tests/load_pdu.rs::a_zero_checksum_is_sent_as_all_ones
• crates/udpstp-wire/tests/obudpst_control_kat.rs::our_wire_layer_reproduces_every_obudpst_pdu_from_its_fields
• crates/udpstp-wire/tests/status_pdu.rs::status_checksum_covers_the_whole_pdu
• crates/udpstp-wire/tests/status_pdu.rs::a_zero_status_checksum_is_sent_as_all_ones

RFC9946-5.6-4

Tested

The PDU receiver SHALL subsequently verify the PDU checksum whenever checksum processing has been configured and the field is populated.