Peer-to-Peer (P2P) Overlay Diagnostics
Extracted elements (30)
An earlier design generated responses from each intermediate peer as the message traversed the overlay, but this was discarded because it created a DoS amplification vector: one spoofed request would cause multiple peers to send responses to the spoofed victim. The iterative PathTrack approach preserves the request-response model of RELOAD.
PathTrack was chosen over a RouteQuery-then-Fetch approach because in high-churn environments, the path can change between the two separate operations, making results inconsistent. A single message per step is more likely to traverse the same path and provide coherent diagnostics.
After receiving a PathTrackAns where the next_hop node ID equals the responding node ID, the initiator MUST stop the iterative PathTrack process, as this indicates the responding peer is the responsible peer for the destination ID.
Each intermediate peer receiving a Ping with diagnostic extensions or a PathTrack request/response MUST check the expiration value and, if the message is expired, MUST generate a response with error code 0x17 (Error_Message_Expired) and discard the message.
For single-hop latency measurement, traditional IP-layer ping MUST be used instead of overlay diagnostics methods, since overlay timestamps require time synchronization and are unsuitable for single-hop precision.
Intermediate peers MUST return error code 0x15 on ICMP Destination Unreachable, 0x16 on ICMP Time Exceeded, 0x18 when the upstream peer disobeys routing rules (also conveying upstream peer info), 0x19 when a loop is detected via the Via List, and 0x1a when the TTL field is no more than 0.
P2P overlay networks using these diagnostics methods MUST enforce time synchronization with a central time server (e.g., NTP per RFC 5905) to enable meaningful one-way-delay and timestamp computations.
The destination peer MUST check if the initiator node is authorized to request specific diagnostic information types. If the initiator is not authorized, the peer MUST return error code 2 (Error_Forbidden). Access to each diagnostic kind MUST NOT be allowed unless compliant with the authorization rules in Section 7.
The Diagnostic_Ping extension MAY be used for new Ping method requests and MUST NOT be included in requests using any other method. Senders MUST accept a response that lacks diagnostic information and SHOULD NOT resend the message expecting a reply.
The expiration field in DiagnosticsRequest MUST have a value between 1 and 600 seconds in the future. The ext_length field MUST NOT be negative. Kinds 0x0000 to 0x003f MUST NOT be indicated in the diagnostic_extensions_list as they are representable via dMFlags.
The hop_counter field in DiagnosticsResponse MUST be exactly copied from the TTL field of the forwarding header in the received request, allowing the initiator to compute the number of overlay hops traversed.
The overlay configuration file MUST contain XML elements for authorizing nodes to access diagnostic kinds: a 'diagnostic-kind' element with a 'kind' attribute (hex DiagnosticKindId) and one or more 'access-node' subelements each containing a NodeID.
When constructing a Ping message with diagnostic extensions, the sender MUST create a MessageExtension with type 0x2 and critical set to FALSE. The extension_contents MUST be a DiagnosticsRequest structure. The message MUST NOT be sent to the broadcast NodeID.
EWMA_BYTES_SENT and EWMA_BYTES_RCVD are 32-bit unsigned integers representing exponential weighted moving averages of bytes sent/received per second, computed as: value = alpha * present + (1 - alpha) * last, with a suggested alpha of 0.8 recalculated every five seconds.
Six new RELOAD error codes are defined for diagnostics: Error_Underlay_Destination_Unreachable (0x15), Error_Underlay_Time_Exceeded (0x16), Error_Message_Expired (0x17), Error_Upstream_Misrouting (0x18), Error_Loop_Detected (0x19), and Error_TTL_Hops_Exceeded (0x1a).
SOFTWARE_VERSION is a US-ASCII C-style null-terminated string identifying the peer's manufacturer, model, OS, and software version. The string MUST be terminated by '\0', and '\0' MUST NOT appear within the string itself.
STATUS_INFO is an 8-bit field encoding congestion status in the rightmost 4 bits, with 16 levels (0x00 = zero load, 0x0f = congestion). Other bits MUST be cleared to 0. This can be used for congestion-aware routing to avoid forwarding to overloaded peers.
The dMFlags field is a 64-bit unsigned integer where each bit requests a specific diagnostic kind. Bits 0 and 63 are reserved; all zeros means nothing requested; all ones means everything requested. Defined base diagnostics include STATUS_INFO, ROUTING_TABLE_SIZE, PROCESS_POWER, UPSTREAM_BANDWIDTH, DOWNSTREAM_BANDWIDTH, SOFTWARE_VERSION, MACHINE_UPTIME, APP_UPTIME, MEMORY_FOOTPRINT, DATASIZE_STORED, INSTANCES_STORED, MESSAGES_SENT_RCVD, EWMA_BYTES_SENT, EWMA_BYTES_RCVD, UNDERLAY_HOP, and BATTERY_STATUS.
The PathTrack method is a new RELOAD request (message code 0x27 for request, 0x28 for response) that allows a node to iteratively collect diagnostic information from each hop along the routing path to a destination. Each step returns the next-hop peer and optional diagnostic data.
The Ping diagnostic extension uses a new MessageExtensionType (0x2, named 'Diagnostic_Ping') carrying a DiagnosticsRequest structure in the extension_contents field. This extension is non-critical; peers that do not support it treat the message as a normal Ping.
The RELOAD diagnostics framework defines two primary data collection mechanisms: an extended Ping method that gathers diagnostics along the path, and a new PathTrack method for iterative hop-by-hop diagnostic information retrieval.
A new RELOAD message extension code 'Diagnostic_Ping' (0x2) added to the RELOAD extension registry, and a new XML namespace 'urn:ietf:params:xml:ns:p2p:config-diagnostics' registered in the IETF XML registry.
IANA created the 'RELOAD Diagnostic Kind ID' registry under RELOAD, containing 16-bit integers for diagnostic extension data kinds. Codes 0x0001-0x0010 correspond to the base diagnostics, 0xf000-0xfffe are reserved for local/overlay-specific use without IANA registration, and new entries require Standards Action.
IANA created the 'RELOAD Diagnostics Flag' registry under RELOAD, containing 1-bit flags in a 64-bit dMFlags integer. New entries require Standards Action. Initial entries include STATUS_INFO through BATTERY_STATUS with their respective flag bit positions.
Six new error codes added to the 'RELOAD Error Codes' registry: Error_Underlay_Destination_Unreachable (0x15), Error_Underlay_Time_Exceeded (0x16), Error_Message_Expired (0x17), Error_Upstream_Misrouting (0x18), Error_Loop_Detected (0x19), Error_TTL_Hops_Exceeded (0x1a).
Two new message codes added to the 'RELOAD Message Codes' registry: path_track_req (0x27) and path_track_ans (0x28).
Diagnostic information must be carefully authorized because attackers can use it to analyze overlay topology, fingerprint peers, and target key nodes. Networks where anonymity is critical may find diagnostics problematic or undesirable, as defenses against fingerprinting are very difficult.
The DiagnosticsRequest structure contains: expiration (uint64, milliseconds since Unix epoch), timestamp_initiated (uint64), dMFlags (uint64 bitmask of requested diagnostics), ext_length (uint32), and a diagnostic_extensions_list of DiagnosticExtension structures.
The DiagnosticsResponse structure contains: expiration (uint64), timestamp_initiated (uint64, copied from request), timestamp_received (uint64), hop_counter (uint8, copied from the TTL field of the forwarding header), ext_length (uint32), and a diagnostic_info_list of DiagnosticInfo structures.
The PathTrackReq structure contains a Destination field (NodeID, opaque id, or ResourceID) and a DiagnosticsRequest field. The PathTrackAns structure contains a next_hop Destination field and a DiagnosticsResponse field.