]> China Mobile

Beijing100053 China lizhiqiangyjy@chinamobile.com

China Mobile

Beijing100053 China duzongpeng@chinamobile.com

Centec

Shanghai201203 China wangjj@centec.com

Centec

Shanghai201203 China chengw@centec.com

Centec

Shanghai201203 China zhanggy@centec.com

Inesa

Shanghai200030 China sunxun@inesa.com

SAIA

Shanghai200125 China chunhao.zhao@sh-aia.com

TSV IPPM IOAM encapsulation insertion point telemetry IPv6 NSH In Situ Operations, Administration, and Maintenance (IOAM) enables on-path telemetry by inserting operational metadata into data packets as they traverse a network path. IOAM Data-Fields, as defined in RFC 9197, are designed to be independent of the encapsulating transport protocol. However, the procedures for inserting, updating, and removing IOAM Data-Fields are currently specified separately for each transport protocol (e.g., IPv6, NSH, GRE, Geneve), leading to redundant specification effort and inconsistent implementation behavior. This document defines a set of common encapsulation procedures for IOAM Data-Fields that are applicable across multiple transport protocols. The insertion point for IOAM Data-Fields is expressed as a configurable byte offset from a well-defined reference position in the encapsulating header, enabling a uniform insertion procedure that does not require protocol-specific parsing logic. The document specifies the general steps for identifying the insertion point, validating transport-layer constraints, performing the insertion of IOAM Option-Types, and updating affected header fields to maintain protocol compliance.

Introduction In Situ Operations, Administration, and Maintenance (IOAM) collects telemetry information by embedding IOAM Data-Fields into live data packets while they traverse a network path. The IOAM Data-Fields themselves are defined independently of any specific transport protocol. This design allows IOAM to be carried within various encapsulations such as IPv6 , NSH , GRE, and Geneve. Each transport protocol that carries IOAM defines its own encapsulation specification, describing how IOAM Option-Types map into that protocol's extension mechanisms. While the data field definitions remain the same across protocols, the encapsulation documents each independently describe similar operational steps: how to identify where in the packet IOAM data should be placed, how to expand the packet to accommodate the additional data, and how to update the enclosing headers to reflect the modified packet structure. This redundancy creates practical challenges. First, implementations supporting multiple transport protocols must encode logically equivalent procedures in protocol-specific code paths, increasing development and verification effort. Second, the absence of a shared procedural framework can lead to inconsistent behavior across encapsulations, particularly in areas such as Maximum Transmission Unit (MTU) handling, header field updates, and error handling. Third, as new transport protocols emerge, the effort required to specify IOAM encapsulation for each protocol remains unnecessarily high. This document addresses these challenges by defining a set of common encapsulation procedures for IOAM Data-Fields. The central concept is that the insertion point for IOAM data within a packet is expressed as a configurable byte offset from a well-defined reference position in the encapsulating header. This approach enables a single encapsulation procedure to handle multiple transport protocols: the protocol-specific knowledge is confined to the provisioning of the correct offset value, while the insertion operation itself is uniform across all protocols.

Requirements Language 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 when, and only when, they appear in all capitals, as shown here.

Terminology This document uses the IOAM terminology defined in and . The following additional terms are used:

Insertion Point:

The byte position within a packet at which IOAM Data-Fields are to be placed. The insertion point is determined by adding a configured insertion offset to the reference position.

Reference Position:

A well-defined, unambiguous byte position within the encapsulating protocol header from which the insertion offset is measured. Typical reference positions include the start of the network-layer (Layer 3) header or the start of a specific extension header.

Insertion Offset:

A non-negative integer value, expressed in octets, that specifies the displacement from the reference position to the insertion point. The insertion offset is provisioned per IOAM Encapsulation Profile and depends on the transport protocol in use.

Base Header:

The fixed-length portion of the encapsulating protocol header that precedes the area where IOAM Data-Fields can be inserted.

Header Consistency Update:

The process of modifying header fields in the encapsulating protocol and any outer encapsulations to accurately reflect the change in packet size and structure resulting from the insertion or removal of IOAM Data-Fields.

Transport Constraints:

Protocol-specific limitations that restrict the size, alignment, or placement of IOAM Data-Fields within a given transport protocol.

IOAM Encapsulation Profile:

A configuration object that associates a set of flow-matching criteria with the IOAM encapsulation parameters to be applied, including the IOAM Option-Types to insert, the insertion offset, and protocol-specific constraint parameters.

Scope and Relationship to Existing Specifications This document is intended to complement, not replace, the existing IOAM encapsulation specifications. defines the IOAM Data-Fields and their formats. This document does not modify or extend those definitions. provides deployment guidance for IOAM. This document focuses on encapsulation procedures rather than deployment considerations. defines a YANG data model for IOAM configuration. The IOAM Encapsulation Profile concept defined in this document is compatible with the configuration structures in . Protocol-specific encapsulation documents (e.g., for IPv6, for NSH) define how IOAM Option-Types are mapped into specific protocol header structures. This document abstracts the common operational steps shared across those specifications and provides a framework for specifying IOAM encapsulation in future transport protocols. The common procedures defined in this document are informational for existing encapsulations and normative for future transport protocol encapsulations that choose to reference this document.

Overview of Common Encapsulation Procedures The process of encapsulating IOAM Data-Fields into a transit packet can be decomposed into the following general steps, regardless of the specific transport protocol:

• Step 1 - Flow Matching and Profile Selection: Match the incoming packet against the configured flow-matching criteria and select the associated IOAM Encapsulation Profile, which provides the insertion offset and IOAM Option-Type parameters.
• Step 2 - Insertion Point Calculation: Compute the insertion point as the sum of the reference position and the provisioned insertion offset.
• Step 3 - Constraint Validation: Verify that the IOAM Data-Fields to be inserted satisfy the transport-specific constraints (e.g., maximum option size, alignment requirements, MTU limits).
• Step 4 - Data-Field Insertion: Expand the packet at the computed insertion point and write the IOAM Option-Type header and associated IOAM Data-Fields.
• Step 5 - Header Consistency Update: Update all affected header fields in the encapsulating protocol and any outer encapsulations to reflect the new packet size and structure.
• Step 6 - Integrity Verification: Recompute any checksums or integrity fields that cover the modified portions of the packet.

Insertion Point Provisioning The insertion point for IOAM Data-Fields is not determined through runtime parsing of the transport protocol header. Instead, it is provisioned as part of the IOAM Encapsulation Profile, which is configured on the IOAM encapsulating node. This approach confines all protocol-specific knowledge to the configuration plane, enabling the data plane insertion procedure to operate uniformly across different transport protocols.

IOAM Encapsulation Profile An IOAM Encapsulation Profile binds the following parameters together: (a) Flow-matching criteria compatible with the ACL-based flow identification defined in ; (b) IOAM Option-Type parameters as defined in and ; (c) Insertion offset; (d) Transport constraint parameters. The IOAM encapsulating node MUST be provisioned with at least one IOAM Encapsulation Profile for each combination of transport protocol type and IOAM Option-Type that it is configured to support.

Insertion Offset Provisioning The insertion offset value is determined by the network operator based on the structure of the encapsulating transport protocol. The operator MUST ensure that the provisioned insertion offset points to a location within the legitimate extension area of the transport protocol. Mechanisms for validating the correctness of provisioned offset values are described in the Security Considerations.

Insertion Point Calculation At runtime, when a packet matches the flow-matching criteria of an IOAM Encapsulation Profile, the encapsulating node computes the insertion point: Insertion_Point = Reference_Position + Insertion_Offset. The reference position is typically the byte position of the start of the Layer 3 (network layer) header. For tunneled packets, the reference position corresponds to the start of the outermost encapsulating header that is relevant to the IOAM-Domain. The insertion offset MUST satisfy the following requirements: (a) it MUST point to a location within the legitimate extension area of the transport protocol; (b) it MUST account for any alignment requirements imposed by the transport protocol (e.g., IPv6 IOAM options require 4-octet alignment as specified in ); (c) it MUST NOT point into the immutable fixed-length portion of the transport header or into the packet payload beyond the transport header's extension area. If the computed insertion point does not satisfy these requirements, the encapsulating node MUST NOT insert IOAM Data-Fields and SHOULD increment an error counter.

Constraint Validation Before inserting IOAM Data-Fields, the encapsulating node MUST verify that the insertion will not violate any transport-specific constraints.

Size Constraints The encapsulating node MUST verify that the total size of the IOAM Option-Type header plus the IOAM Data-Fields does not exceed the maximum extension size permitted by the transport protocol. Additionally, the encapsulating node MUST verify that the resulting packet size does not exceed the Path MTU (PMTU) within the IOAM-Domain. If the addition of IOAM Data-Fields would cause the packet to exceed the PMTU, the node MUST NOT insert IOAM and SHOULD maintain counters for packets not instrumented due to MTU constraints.

Alignment Constraints Some transport protocols require optional data fields to be aligned to specific byte boundaries. The encapsulating node MUST insert any necessary padding to satisfy alignment requirements. The padding MUST conform to the padding conventions defined by the transport protocol (e.g., PadN options in IPv6).

Ordering Constraints Some transport protocols impose ordering requirements on optional headers. The encapsulating node MUST ensure that IOAM Data-Fields respect any such requirements. For example, in IPv6, the Hop-by-Hop Options header must be the first extension header following the IPv6 header .

IOAM Data-Field Insertion Once the insertion point has been computed and constraints have been validated, the encapsulating node performs the actual insertion.

Insertion Operation (a) Packet Expansion: The packet is expanded at the computed insertion point by the required number of octets. All octets at and following the insertion point are shifted toward the end of the packet. (b) Option-Type Header Write: The IOAM Option-Type header is written at the insertion point, in the format specified by the corresponding encapsulation specification. For EtherType-based encapsulations, a shim header containing the IOAM-Type and Next Protocol fields is written. (c) Data-Field Write: The IOAM Data-Fields are written immediately following the Option-Type header, formatted according to . For Pre-allocated Trace, the data area is initialized with placeholder values. For Incremental Trace, only the fixed trace header is written; node data is appended by transit nodes. For Direct Export , the option header triggers export at transit nodes without embedding trace data.

Atomicity of Insertion The insertion operation, together with the header consistency update, MUST be performed atomically from the perspective of packet forwarding. A partially modified packet MUST NOT be forwarded. If the insertion fails, the original unmodified packet MUST be forwarded without IOAM Data-Fields, and the failure SHOULD be logged or counted.

Header Consistency Update After IOAM Data-Fields have been inserted, the enclosing protocol headers must be updated to reflect the modified packet structure. The encapsulating node MUST update all length fields affected by the insertion (IPv6 Payload Length and Hdr Ext Len for IPv6; NSH Length field for NSH; outer IP Total Length for GRE; UDP Length plus tunnel-specific length for UDP-encapsulated protocols). Length fields in any outer encapsulation layers MUST also be updated. The encapsulating node MUST recompute checksums covering modified packet portions. If IOAM is within a UDP-encapsulated protocol and the UDP checksum is non-zero, it MUST be recomputed. If the IOAM Data-Fields include a Checksum Complement field , the node MAY perform a checksum-neutral update. If an outer IPv4 header Total Length was updated, the IPv4 header checksum MUST be recomputed. When IOAM Data-Fields are inserted using a shim header or new extension header, the encapsulating node MUST update the relevant next-header or next-protocol pointers. For IPv6, the Next Header field of the preceding header MUST point to the new extension header. For NSH, the Next Protocol field MUST indicate IOAM. For EtherType-based shim headers (GRE, Geneve), the Protocol Type or EtherType field MUST be set to the IOAM shim value, and the IOAM shim's Next Protocol field MUST indicate the original inner protocol.

IOAM Data-Field Removal The IOAM decapsulating node reverses the encapsulation process: (1) identify the IOAM Data-Fields based on protocol-specific indicators; (2) extract and process the IOAM Data-Fields; (3) remove the IOAM Option-Type header, Data-Fields, and associated padding, shifting subsequent octets toward the beginning of the packet; (4) perform the header consistency update in reverse: decrement length fields, recompute checksums, and restore next-header/protocol pointers. The removal MUST be performed atomically. IOAM-Domain boundary nodes MUST remove IOAM Data-Fields before forwarding packets outside the IOAM-Domain .

Applicability to Existing and Future Protocols For IPv6 : reference position is the start of the IPv6 header; insertion offset points to the options area within the Hop-by-Hop or Destination Options header; alignment requirement is 4 octets; maximum option size is 255 octets; header consistency update covers IPv6 Payload Length and Hdr Ext Len. For NSH : reference position is the start of the NSH Base Header; insertion offset points past the Service Path Header; IOAM is indicated through the Next Protocol field; header consistency update covers the NSH Length field. For EtherType-Based Encapsulations (GRE, Geneve): reference position is the start of the outer IP header; insertion offset spans the outer IP header, any UDP header, and the tunnel header; IOAM is indicated through the Protocol Type or EtherType value; header consistency update covers outer IP length fields and any applicable UDP checksum. When specifying IOAM encapsulation for a new transport protocol, the specification SHOULD reference this document and provide: (a) the reference position for IOAM insertion, (b) the method for indicating IOAM presence in the header chain, (c) protocol-specific size, alignment, or ordering constraints, and (d) the header fields requiring update. This approach enables new encapsulation specifications to be concise.

Security Considerations The common procedures inherit all security considerations from and . An incorrectly configured insertion offset could cause IOAM data to overwrite critical header fields or payload data, leading to packet corruption, forwarding failures, or information leakage. Implementations MUST validate that the computed insertion point falls within the legitimate extension area before performing insertion. Implementations MUST reject offset configurations that would place IOAM data outside protocol-defined boundaries. Operators SHOULD validate offset configurations in a controlled environment before production deployment. The procedures in this document MUST only be performed within an IOAM-Domain . Domain boundary nodes MUST ensure IOAM packets do not leak outside the domain. The filtering requirements in and apply to all transport protocols using these procedures. An attacker influencing IOAM configuration might configure excessively large IOAM Data-Fields or incorrect offsets, causing packet drops or malformed packets. The constraint validation step mitigates this by requiring pre-insertion checks. Because the insertion offset is provisioned through the configuration plane, unauthorized modification could cause widespread packet corruption. Operators MUST protect the configuration channel using authentication and access control. The YANG module security considerations in apply to IOAM Encapsulation Profile configuration.

IANA Considerations This document has no IANA actions. It defines common operational procedures for existing IOAM Data-Fields and Option-Types defined in and introduces no new protocol identifiers or registry entries.

Acknowledgements The authors would like to thank the members of the IPPM Working Group for their review and feedback. The existing body of IOAM encapsulation specifications, particularly the work by Frank Brockners, Shwetha Bhandari, Tal Mizrahi, and their collaborators, provided the foundation upon which these common procedures are defined.