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>...
| Argument | Description |
|---|---|
<SERVER>… | The Server's host name or address, optionally with a port (the Standard Port 24601 by default). Several Servers share a Test's Test Connections in turn; they must all be IPv4 or all IPv6 |
| Option | Description |
|---|---|
–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] |
–test-connections <N> | How many Test Connections the Test runs, 1 to 255 [default: one per SERVER]. OB-UDPST Servers accept at most 24 |
–min-test-connections <N> | The Minimum Test Connections: how many must succeed for the Test to go on [default: all of them]. With all required, one lost Setup Response aborts the Test |
–unauthenticated | Run the Test unauthenticated. Not conformant to RFC 9946; the Server must allow it too |
–key-file <FILE> | The key file: a TOML Key Table if its name ends in .toml, else an OB-UDPST udpst.keys file. Group and others must not be able to read it. Keys are never given on the command line |
–key-id <KEYID> | Send with this keyId's key, for a key file with several keys valid now |
–auth-mode <MODE> | The Authentication Mode with a key file: 2 authenticates the Control Phase and every Status PDU (RFC 9946 §5.3), 1 the Control Phase only, for a Server that doesn't support mode 2. The Client never falls back to mode 1 by itself [default: 2] |
–mode-1-server <SERVER> | Use mode 1 with this SERVER, written as among the SERVERs, for one that doesn't support mode 2. Repeatable |
–allow-server-address <SERVER=IP> | Authorize an alternate IP address for this SERVER's authenticated Setup Responses. SERVER must match a positional SERVER; IP must be a literal address of the same family. Repeatable. Without this, only the selected address is accepted |
–time-limit <SECONDS> | Give up sooner than the Test initiation timer's 3 s if the Control Phase hasn't finished after this many seconds [default: 3] |
–direction <DIRECTION> | The direction of the Test: the Server sends the load (downstream) or the Client does (upstream) [default: downstream] [possible values: downstream, upstream] |
–test-interval <SECONDS> | The Test Interval to ask the Server for, in seconds (5-60; longer only with an Operator Key that allows it) [default: 10] |
–fixed-rate <ROW> | Run a Fixed-Rate Test at this Sending Rate Table row. The Server allows it only for an Operator Key |
–start-row <ROW> | Start the Server's search at this Sending Rate Table row instead of the first (row N offers N Mbit/s up to 1000) |
–random-payload | Ask for random payload content instead of zeros, so compression on the path can't inflate the result |
–delay-var <DELAY_VAR> | The delay variation the Load Rate Adjustment Algorithm judges by Possible values: - one-way: One-way delay variation (useOwDelVar 1): no clock synchronisation needed, but it follows clock drift - rtt: Round-trip time variation (useOwDelVar 0): immune to clock drift [default: one-way] |
–refuse-coercion <PARAMETER> | End the Test if the Server coerces this Activation parameter, named as in RFC 9946 (e.g. testIntTime). Repeatable |
–checksum[=<BOOL>] | Use the header checksum (RFC 9946 §5.6): fill it in every PDU sent, verify it in every PDU received when populated [default: false] [possible values: true, false] |
–jumbo[=<BOOL>] | Ask for Jumbo rows above 1 Gbps (CHSR_JUMBO_STATUS); the Server must serve the same [default: true] [possible values: true, false] |
–traditional-mtu[=<BOOL>] | Ask for 1500-byte packets (CHSR_TRADITIONAL_MTU); the Server must serve the same [default: false] [possible values: true, false] |
–algorithm <ALGORITHM> | The Load Rate Adjustment Algorithm the Server searches with [default: b] [possible values: b, c] |
–max-bandwidth <MBPS> | The most the Test is expected to send or receive, in Mbps (maxBandwidth), shared equally between its Test Connections. The Server searches no higher, and a Server with an Admitted Rate Cap may refuse the Test |
–dscp <DSCP> | The DSCP to mark the Test's traffic with, 0 to 63, so a specific traffic class is measured. The Server may coerce it to 0 [default: 0] |
–format <FORMAT> | How to print the results Possible values: - text: Human-readable text - json: JSON compatible with OB-UDPST's client schema; progress goes to stderr [default: text] |
–address-privacy <ADDRESS_PRIVACY> | How text and JSON results show this Client's own address: in full, pseudonymized with a keyed hash, or truncated to the IPv4 /24 or IPv6 /48 Possible values: - full: The address and port as they are - pseudonymize: anon- and the first 8 bytes of HMAC-SHA-256 over the IP address, in hex, keyed with the pseudonym key: one client keeps one pseudonym while the key is kept, and no one without it can reverse it - truncate: The IPv4 /24 or IPv6 /48 the address is in, without the port [default: full] |
–address-privacy-key-file <FILE> | The pseudonym key file, hexadecimal digits (16 bytes or more), for –address-privacy pseudonymize |
–json-extension[=<BOOL>] | With –format json, add udpstp's own results (the Performance Criterion, the Maximum and Highest IP-Layer Capacity, warnings, how the Test ran) as a last "udpstp" object; false leaves OB-UDPST's keys only [default: true] [possible values: true, false] |
–max-loss-ratio <RATIO> | The Performance Criterion: the most a Sub-Interval may lose, as a share of the Load PDUs sent, to count towards the Maximum IP-Layer Capacity (RFC 9097 §6.3). One lost Load PDU always passes; a Sub-Interval in which none arrived never does [default: 0.01] |
–faster-sub-interval-margin <PERCENT> | Warn when, in a Search Test, a Sub-Interval after the Maximum IP-Layer Capacity's ran more than this many percent faster and none after it met the Performance Criterion: the Maximum may then be well below the path, as a search through a drop-tail queue gives [default: 5] |
–first-mode-sub-intervals <N> | Put the first N Sub-Intervals in a Capacity Mode of their own, with its own Maximum IP-Layer Capacity, for a path whose capacity changes on a schedule (RFC 9097 §6.6) |
–socket-buffer-size <BYTES> | The Data Phase's receive and send buffer, in bytes; the OS's limits may hold it lower [default: 2097152] |
–dont-fragment[=<BOOL>] | Set the Don't Fragment bit on test traffic; false lets the path fragment it [default: true] [possible values: true, false] |
–max-hops <HOPS> | MaxHops: the IPv4 TTL or IPv6 hop limit of test traffic, from the expected path length [default: 64] |
-h, –help | Print help (see a summary with '-h') |
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]
| Option | Description |
|---|---|
–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] |
–config <FILE> | The Server's TOML configuration file. Command-line options override its settings |
–listen <ADDRESS> | An address to listen on for Setup Requests, instead of the IPv4 and IPv6 wildcards. Repeatable |
–port <PORT> | The UDP port to listen on for Setup Requests (the Standard Port 24601 by default) |
–allow-unauthenticated[=<BOOL>] | Serve unauthenticated Tests too. Not conformant to RFC 9946; Clients must opt in as well [possible values: true, false] |
–checksum[=<BOOL>] | Use the header checksum (RFC 9946 §5.6) [possible values: true, false] |
–jumbo[=<BOOL>] | Serve Jumbo rows above 1 Gbps (CHSR_JUMBO_STATUS) [default: true] [possible values: true, false] |
–traditional-mtu[=<BOOL>] | Serve 1500-byte packets (CHSR_TRADITIONAL_MTU) [default: false] [possible values: true, false] |
–server-mtu <BYTES> | The Server MTU: the largest IP packet the Server sends, in bytes [default: 1500] |
–ephemeral-ports <FIRST-LAST> | The Server's Ephemeral Ports for Test Connections, as FIRST-LAST, picked at random; its own range, not the OS's [default: 49152-65535] |
–delay-var-statistic <STATISTIC> | Which statistic of a Trial Interval's one-way delay variation classifies it [default: maximum] Possible values: - average: The Trial Interval's average, as OB-UDPST uses - maximum: The Trial Interval's maximum: the delay range, which the RFCs judge |
–tests-per-source <N> | How many Tests may run at once from one Source [default: 1, as RFC 9946 §4.2 requires] |
–max-test-connections <N> | How many Test Connections activated Tests may reserve at once [default: 256]. The Ephemeral Port range must hold this plus the unactivated share |
–test-connections-per-test <N> | How many Test Connections one Test may have over its life [default: 24] |
–max-unactivated-test-connections <N> | How many Test Connections may be admitted but not yet activated at once, separately from the global cap [default: half of –max-test-connections, at least –test-connections-per-test] |
–admitted-rate-cap <MBPS> | The Admitted Rate Cap: the most maxBandwidth admitted at once in each direction, in Mbps [default: no cap]. A Test over it is refused |
–max-test-share <PERCENT> | The most of the Admitted Rate Cap, in percent, that one Test without an Operator Key may state [default: 50] |
–require-max-bandwidth[=<BOOL>] | Refuse Tests that state no maxBandwidth [possible values: true, false] |
–troubleshooting[=<BOOL>] | Answer authentication failures with the reason instead of silence, to debug Clients; up to 10 a second. Anyone can then learn whether keys are configured, and spoofed requests get replies [possible values: true, false] |
–unverified-setups-per-second <N> | How many Setup Requests a second may reach authentication; the rest are dropped silently [default: 20000] |
–source-setup-burst <N> | How many authentic Setup Requests one Source may send at once [default: 48]; at least –test-connections-per-test |
–source-setups-per-second <N> | How many more a Source may send each second after its burst [default: 5] |
–key-setup-burst <N> | How many authentic Setup Requests one Key Table row may send at once, Unauthenticated Mode counting as one [default: 1000]; at least –test-connections-per-test |
–key-setups-per-second <N> | How many more a Key Table row may send each second after its burst [default: 1000] |
–allowed-dscp <DSCP,…>… | The DSCPs a Test without an Operator Key may mark its traffic with, comma-separated [default: 0]; another is coerced to 0 |
–operator-allowed-dscp <DSCP,…>… | The DSCPs a Test with an Operator Key may mark its traffic with, comma-separated [default: all but network control, 48 and 56] |
–max-start-row <ROW> | The highest Sending Rate Table row a Test without an Operator Key may start its search at [default: 100]; Operator Keys are exempt |
–quota-period <SECONDS> | The Quota Period Quotas are counted over, in seconds [default: 3600] |
–source-tests-per-quota-period <N> | Each Source's Quota of Tests per Quota Period [default: none]; Operator Keys are exempt |
–source-bytes-per-quota-period <BYTES> | Each Source's Quota of load bytes per Quota Period, both directions [default: none]; Operator Keys are exempt |
–socket-buffer-size <BYTES> | Each Test Connection's receive and send buffer in its Data Phase, in bytes [default: 2 MiB]; the OS's limits may hold it lower |
–dont-fragment[=<BOOL>] | Set the Don't Fragment bit on test traffic [default: true]; false lets the path fragment it [possible values: true, false] |
–max-hops <HOPS> | MaxHops: the IPv4 TTL and IPv6 hop limit of test traffic, from the expected path length (RFC 9946 §10 says the operator MUST set it) [default: 64, with a warning] |
–log-format <FORMAT> | The log's format on stdout [default: human]; json writes one object a line Possible values: - human: Readable events, with indented continuation lines when needed - json: One JSON object a line |
–log-file <FILE> | Where the log goes instead of stdout, with the startup's errors and warnings: a new file each day, the date before the extension, the last 14 kept |
–address-privacy <HOW> | How the log shows client addresses [default: full]: pseudonymize with a keyed hash, or truncate to the IPv4 /24 or IPv6 /48 Possible values: - full: The address and port as they are - pseudonymize: anon- and the first 8 bytes of HMAC-SHA-256 over the IP address, in hex, keyed with the pseudonym key: one client keeps one pseudonym while the key is kept, and no one without it can reverse it - truncate: The IPv4 /24 or IPv6 /48 the address is in, without the port |
–address-privacy-key-file <FILE> | The pseudonym key file, hexadecimal digits (16 bytes or more), for –address-privacy pseudonymize |
–statistics-interval <SECONDS> | How often the log reports the Server's counters, in seconds [default: 60]; 0 never does |
–key-file <FILE> | The key file: a TOML Key Table if its name ends in .toml, else an OB-UDPST udpst.keys file. Group and others must not be able to read it |
–print-config | Validate the settings and key file, print effective TOML, and exit |
–settings-only | With –print-config, preview settings without opening keys or logs |
–windows-service | Run as the Windows service the Service Control Manager started, which stops it, logging to log_file (Windows only) |
-h, –help | Print help (see a summary with '-h') |