Data Fields for In Situ Operations, Administration, and Maintenance (IOAM)
Extracted elements (28)
IOAM-Data-Field definitions intentionally focus on syntax and avoid specifying semantics or units (e.g., for buffer occupancy or queue depth). This allows nodes to supply data in their native format without unit conversions, delegating interpretation and conversion to management systems that process the data.
IOAM-Namespaces are introduced to resolve the fact that IOAM node identifiers do not need to be globally unique and to allow namespace-specific interpretation of data fields (e.g., interface IDs, timestamp format, or buffer occupancy units). The Namespace-ID always travels with the data fields to provide necessary context.
Two separate trace option types (Pre-allocated and Incremental) are defined to optimize for different hardware and software forwarding implementations. Pre-allocated suits software forwarders that can index into a fixed array; Incremental suits hardware that benefits from pushing data without reading the full array and allows packets as long as MTU permits.
If not all nodes in an IOAM-Domain support IOAM, non-supporting nodes forward packets without modifying IOAM-Data-Fields, resulting in incomplete trace records. The Overflow (O-bit) flag signals when insufficient space remains in a pre-allocated option to record further node data.
When multiple encapsulation protocols are stacked (tunneling), IOAM-Data-Fields may be present at multiple layers and follow a 'ships-in-the-night' model: fields at one layer are entirely independent of fields at another layer. Operators can instrument whichever protocol layer they choose.
A transit node MUST ignore IOAM-Option-Types it does not understand; it MUST NOT add new IOAM-Option-Types, MUST NOT remove IOAM-Option-Types, and MUST NOT change the IOAM-Data-Fields of an E2E Option-Type.
An IOAM transit node MUST NOT modify any fixed-size trace option header fields other than Flags and RemainingLen; specifically it MUST NOT modify Namespace-ID, NodeLen, IOAM Trace-Type, or Reserved.
Any specification defining how IOAM-Data-Fields are carried in an encapsulating protocol MUST provide a mechanism for cryptographic integrity protection of the IOAM-Data-Fields.
If a node cannot populate an IOAM-Data-Field set in the Trace-Type, the field value MUST be set to 0xFFFFFFFF for 4-octet fields or 0xFFFFFFFFFFFFFFFF for 8-octet fields to indicate 'not populated'. All IOAM-Data-Fields MUST be 4-octet aligned.
IOAM encapsulating and decapsulating nodes that support tracing MUST support both Trace Option-Types (Pre-allocated and Incremental). For IOAM transit nodes, supporting one of the two is sufficient.
The Default-Namespace-ID (0x0000) MUST be supported by all nodes implementing IOAM. For any Namespace-ID that does not match one the node is configured to operate on, the node MUST NOT change the contents of the IOAM-Data-Fields.
When both trace options are present simultaneously, the Incremental Trace-Option MUST be placed before the Pre-allocated Trace-Option in the packet.
When using the Checksum Complement field over UDP-based encapsulations, an IOAM encapsulating or transit node adding data MUST either recompute the UDP Checksum or use the Checksum Complement to maintain UDP checksum correctness. IOAM decapsulating nodes MUST recompute the UDP Checksum.
An IOAM-Domain consists of encapsulating nodes (add options), transit nodes (read/write data fields), and decapsulating nodes (remove options). Node roles are defined per IOAM-Namespace and a node may serve multiple roles simultaneously.
IOAM defines four Option-Types: Pre-allocated Trace, Incremental Trace, POT (Proof of Transit), and E2E (Edge-to-Edge). These categorize IOAM-Data-Fields and are tracked in a common IANA registry.
IOAM-Namespaces are identified by a 16-bit Namespace-ID, split into an operator-assigned range (0x0001–0x7FFF) and an IANA-assigned range (0x8000–0xFFFF). The Namespace-ID field MUST be included in all IOAM-Option-Types.
IOAM supports three timestamp formats selectable per deployment via management plane: PTP Truncated (64-bit, 1 ns resolution, epoch 1970, wraps 2106), NTP 64-bit (233 ps resolution, epoch 1900, wraps 2036), and POSIX-based (1 µs resolution, epoch 1970, wraps 2106). The format is encoded as 32-bit seconds + 32-bit fraction fields.
IANA created the 'In Situ OAM (IOAM)' registry group containing seven registries: IOAM Option-Type (128 code points, IETF Review for 4–127), IOAM Trace-Type (24-bit bitmask, bits 12–21 via IETF Review), IOAM Trace-Flags (4-bit, bits 1–3 via IETF Review), IOAM POT-Type (256 code points), IOAM POT-Flags, IOAM E2E-Type (16-bit bitmask), and IOAM Namespace-ID (operator-assigned 0x0001–0x7FFF, IANA Expert Review 0x8000–0xFFFF).
Attackers can compromise IOAM integrity by modifying IOAM options in transit or injecting packets with maliciously generated IOAM options; all nodes in the path are potential attack vectors. The Proof of Transit Option-Type is provided to help verify that packets traversed a defined set of nodes.
IOAM can be used to mount or amplify DoS attacks: an attacker can inject IOAM headers to consume node resources or cause packets to exceed MTU (triggering fragmentation or drops). Timestamp integrity depends on the security of the underlying time synchronization protocol.
IOAM data can be misused for covert channels between network nodes, and IOAM options enable network reconnaissance (path topology, queue states, buffer occupancy). If IOAM data leaks beyond the IOAM-Domain boundary it can expose this information to external attackers.
Hop_Lim and node_id (short) is a 4-octet field: 1-octet Hop_Lim (copied from IP TTL/Hop Limit at egress) and 3-octet node_id. The wide variant is 8 octets: 1-octet Hop_Lim and 7-octet node_id.
ingress_if_id and egress_if_id (short) is a 4-octet field with two 2-octet unsigned integers. The wide variant is 8 octets with two 4-octet unsigned integers for ingress and egress interface IDs.
The E2E Option-Type header is 4 octets: Namespace-ID (16 bits) and IOAM E2E-Type (16-bit bitmask). E2E-Type bits define presence of 64-bit sequence number (bit 0), 32-bit sequence number (bit 1), timestamp seconds (bit 2), and timestamp fraction (bit 3); bits 0 and 1 are mutually exclusive.
The Opaque State Snapshot is a variable-length field: 1-octet Length (in 4-octet multiples), 3-octet Schema ID, followed by opaque data. When a node has no opaque state to report, Length MUST be 0 and Schema ID MUST be 0xFFFFFF.
The POT Option-Type header is 4 octets (Namespace-ID 16 bits, POT-Type 8 bits, POT-Flags 8 bits). POT Type 0 data is 16 octets: PktID (64-bit unique packet identifier) and Cumulative (64-bit value updated at each node per the verification algorithm).
The Trace Option header is 8 octets: Namespace-ID (16 bits), NodeLen (5-bit unsigned integer in multiples of 4 octets), Flags (4 bits), RemainingLen (7-bit unsigned integer), IOAM Trace-Type (24-bit bitmask), and Reserved (8 bits). Trace option data MUST be 4-octet aligned.
Transit delay is a 4-octet field (0 to 2^31-1 nanoseconds). When transit delay exceeds 2^31-1 ns, the top 'O' bit is set and value is 0x80000000 to indicate overflow; 0xFFFFFFFF indicates not populated.