22Open Broadband-UDP Speed Test (OB-UDPST) is a client/server software utility to
33demonstrate one approach of doing IP capacity measurements as described by:
44
5- - Broadband Forum TR-471 Issue 3 (12/2022 ): _ Maximum IP-Layer Capacity Metric,
5+ - Broadband Forum TR-471 Issue 4 (2024 ): _ Maximum IP-Layer Capacity Metric,
66Related Metrics, and Measurements_ , BBF TR-471,
77https://www.broadband-forum.org/technical/download/TR-471.pdf
88
@@ -151,7 +151,7 @@ load adjustment when conducting a search for the Maximum IP-Layer Capacity.
151151The Type C algorithm (a.k.a. Multiply and Retry) will provide a fast rate
152152increase until congestion, reaching 1 Gbps in ~ 1 second. The "fast" ramp-up
153153will be re-tried when conditions warrant, to ensure that the Maximum IP-Layer
154- Capacity has been reached. This option is activated using ` -A c ` (with the
154+ Capacity has been reached. This option is activated using ` -A C ` (with the
155155more linear Type B algorithm remaining the default).
156156
157157One change to the default settings was included in Release 7.5.1. All Load
@@ -352,10 +352,10 @@ the connection which closes the socket and deallocates it.
352352
353353** More Info**
354354
355- For much more detail on the test protocol, see the ./protocol.md file. Also, an
356- Internet-Draft,
355+ An Internet-Draft,
357356https://datatracker.ietf.org/doc/draft-ietf-ippm-capacity-protocol/ describes
358- Protocol Version 9 in even more detail.
357+ what will eventually be the official protocol version. Although fundamentally
358+ the same as described here, it includes accommodations for additional security.
359359
360360## JSON Output
361361For examples of the JSON output fields see the included sample files named
@@ -713,6 +713,7 @@ character:
713713- #D - Direction of test ('U' = Upstream, 'D' = Downstream)
714714- #H - Server host name (or IP) specified on command-line
715715- #p - Control port used for test setup
716+ - #E - Interface name specified with ` -E intf ` option (only valid on client)
716717
717718In addition to the above, all conversion specifications supported by strftime()
718719(and introduced by a '%' character) can also be utilized - see strftime() man
@@ -733,6 +734,7 @@ receiver's clock).
733734- OWD : The one-way delay of the datagram if the sender's and receiver's clocks
734735are sufficiently synchronized, else it merely reflects the difference in the
735736clocks (and could be negative). This value is in milliseconds.
737+ - IntfMbps : The client interface Mbps when the ` -E intf ` option is used.
736738- RTTTxTime : The transmit timestamp used for RTT (Round-Trip Time)
737739measurements and carried from the load receiver to the load sender in the
738740periodic status feedback messages.
@@ -745,9 +747,94 @@ turn-around time in the load sender). This value is in milliseconds.
745747- RTT : The resulting "network" RTT when the RTT response delay is subtracted
746748from the difference between the RTT transmit and receive times. This value is
747749in milliseconds.
750+ - StatusLoss : The count of lost status feedback messages sent from the load
751+ receiver to the load sender.
748752
749753* Because RTT measurements are only periodically sampled (as part of each status
750754feedback message), those columns will be empty most of the time. Also, all
751755timestamps are based on the local system time zone and utilize microsecond
752756resolution.*
753757
758+ ## Multi-Key Authentication
759+ For better support of large-scale deployments with various service offerings
760+ and device types, multiple authentication keys are now supported. As of version
761+ 8.2.0, and in addition to the legacy authentication key still available on the
762+ command-line, a key file can now be specified via ` -K file ` to allow up to 256
763+ unique authentication keys (see ` udpst.keys ` example file). The CSV formatted
764+ file expects a numeric key ID (0-255) followed by the key string (64 characters
765+ max). Commas, spaces, tabs, and comments (anything beginning with a '#') are
766+ all ignored.
767+
768+ * Because a key ID field is now needed in the Setup Request PDU, the protocol
769+ version had to be bumped from 10 to 11. However, the server is backward
770+ compatible and will support multi-key authentication for clients using either
771+ version. A default key ID of zero is assumed when one is not specified or is
772+ unavailable (as is the case with protocol version 10).*
773+
774+ The authentication process begins with the client using a shared key to create
775+ a 32-byte HMAC-SHA256 hash for the Setup Request PDU. This hash and a key ID are
776+ inserted in the PDU prior to transmission to the server. The key used to create
777+ the hash can come from the command-line via the ` -a key ` option OR from a key
778+ file specified via the ` -K file ` option. The key ID is specified via the
779+ ` -y keyid ` option. When a key file is being utilized, the key ID option is also
780+ used to determine which key in the key file will be used to create the hash.
781+ If the key file only contains a single entry, and a key ID was not explicitly
782+ specified on the command-line, that key ID and key will automatically be used.
783+ Otherwise, when a key ID is not explicitly specified on the command-line, or the
784+ Setup Request is coming from a client using the previous protocol version (10),
785+ a default key ID of zero is assumed.
786+
787+ When the server receives the Setup Request, and if it is utilizing a key file,
788+ the included key ID will be used to select the key used to create a
789+ corresponding hash (for comparison and validation). An entry in the key file
790+ with a key ID of zero can be used for older clients using the previous protocol
791+ version (10). In addition to the key file, a command-line key specified via
792+ ` -a key ` can also be used for secondary/backup authentication of the client.
793+ That is, if the authentication via a key file key fails for any reason (key ID
794+ not found, hash comparison mismatch, etc.) authentication is automatically
795+ attempted a second time using the command-line key. This flexibility allows for
796+ an easier transition from the previous protocol version, clients using an older
797+ command-line key, or clients moving from a zero (default) key ID to a non-zero
798+ ID.
799+
800+ Lastly, for clients transitioning from no authentication to authentication, a
801+ new compilation flag is available on the server that makes authentication
802+ optional.
803+ ```
804+ $ cmake -D AUTH_IS_OPTIONAL=ON .
805+ ```
806+ * Note: This mode of operation is considered low security and should only be
807+ utilized temporarily for a migration or upgrade of clients.*
808+
809+ ## Optional Header Checksum and PDU Integrity Checks
810+ On systems where the standard UDP checksum is not being inserted by the
811+ protocol stack/NIC, or is not being verified upon reception, corrupt datagrams
812+ will be passed up to udpst. As of protocol version 11, an optional header
813+ checksum can be calculated and inserted into all control and data PDU headers
814+ to deal with this. Upon reception, udpst will automatically validate the header
815+ checksum if populated. And although this mechanism can operate in one direction
816+ at a time, it should be enabled on both the client and server for bidirectional
817+ protection. The following compilation flag will enable this functionality on
818+ the sender for all outgoing PDUs:
819+ ```
820+ $ cmake -D ADD_HEADER_CSUM=ON .
821+ ```
822+ * Note: Because of the small to moderate performance impact (depending on the
823+ device), this flag is normally disabled since it is redundant when the standard
824+ UDP checksum is being utilized.*
825+
826+ Independent of whether the header checksum is enabled as an additional PDU
827+ integrity check (beyond size, format, etc.), new output messaging is displayed
828+ when an invalid PDU is received. A bad PDU during the control phase (whether a
829+ corrupted PDU or a rogue UDP datagram) will generate an ALERT while a bad PDU
830+ during the data phase will generate a WARNING (and result in a warning exit
831+ status and JSON ErrorStatus). In cases where the udpst control port on the
832+ server is exposed to the open Internet, and verbose is enabled, this may result
833+ in excessive alerts due to UDP port scanners and probing. If either of these
834+ new output message types is not desired, the following compilation flags can be
835+ used to suppress them (and the PDU is silently ignored):
836+ ```
837+ $ cmake -D SUPP_INVPDU_ALERT=ON .
838+ $ cmake -D SUPP_INVPDU_WARN=ON .
839+ ```
840+
0 commit comments