# 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. ```text $ 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] 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 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](../guides/running-a-test.md) shows the options in use. ```text Usage: udpstp client [OPTIONS] ... ``` | 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](configuration.md)); an option given on the command line replaces the file's value. [Hosting a Server](../guides/hosting-a-server.md) shows them in use. ```text 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') |