How to Configure IPv6 In-Situ Operations Administration and Maintenance (IOAM) in Linux Terminal Using ip ioam

Traditional network monitoring mechanisms—such as ICMP ping, traceroute, and active synthetic probes—provide coarse-grained visibility into network transit paths. However, synthetic probe packets frequently experience different routing decisions and queue priorities compared to actual user application traffic. In modern high-throughput IPv6 networks, In-situ Operations, Administration, and Maintenance (IOAM, RFC 9197 and RFC 9359) solves this challenge by embedding telemetry data directly into live data packets as they transit intermediate nodes. The Linux kernel natively integrates an IOAM subsystem, manageable from the terminal via ip ioam.

Understanding IPv6 IOAM Architecture and Trace Insertion

IOAM embeds diagnostic records directly within the IPv6 Hop-by-Hop (HbH) or Routing Options extension headers without disrupting payload delivery:

• Encapsulating Node (Ingress): An edge router or gateway host inserts the IOAM header containing trace instructions into outbound IPv6 data packets.
• Transit Nodes: Intermediate switches or Linux routers running IOAM read the header instructions and append real-time telemetry metrics—such as ingress/egress interface IDs, hop latency timestamps, transit sequence numbers, and buffer queue depth.
• Decapsulating Node (Egress): The destination edge router or final host strips the accumulated IOAM data records and forwards them to a telemetry analytics collector (e.g., Prometheus, Grafana, or Kafka pipeline).
• IOAM Namespaces: Segment telemetry metrics into administrative domains, allowing multi-tenant cloud networks to maintain independent tracing configurations.

Prerequisites and Kernel IOAM Module Loading

Linux kernels (version 5.14 and higher) natively include the ioam6 driver. On Debian, Ubuntu, or enterprise Linux distributions, verify iproute2 support and load the kernel modules:

# Check kernel version compatibility
uname -r

# Load the IPv6 IOAM kernel driver
sudo modprobe ioam6

# Verify module initialization
lsmod | grep ioam6

# Confirm iproute2 ioam subcommand availability
ip ioam help

Configuring IOAM Namespaces

All IOAM operations require at least one active namespace. An IOAM namespace acts as an isolated context identified by a 16-bit integer (e.g., 123) or a symbolic name:

# Add an IOAM namespace with ID 123
sudo ip ioam namespace add 123

# List configured IOAM namespaces
ip ioam namespace show

To associate cryptographic security or opaque data tags with the namespace, you can attach an optional 32-bit data attribute:

# Add a secured namespace with an opaque 32-bit telemetry tag
sudo ip ioam namespace add 456 data 0xcafebeef

Defining IOAM Trace Schemas

IOAM schemas define the structured format of telemetry data inserted into packets. This includes specifying which metrics intermediate routers must record:

# Create an IOAM schema mapping telemetry fields
sudo ip ioam schema add 10 "node_id,ingress_if,egress_if,timestamp"

# Inspect configured schemas
ip ioam schema show

Commonly recorded metrics include:

• Hop Limit & Node ID: Identifies which physical router processed the packet.
• Transit Delay / Timestamps: Sub-microsecond timestamps recorded upon packet ingress and egress.
• Queue Depth: Current hardware buffer utilization at the outgoing interface.

Enabling IOAM Ingress and Egress on Network Interfaces

To instruct the Linux kernel to process and append IOAM trace records as packets pass through local network interfaces, enable IOAM sysctl directives:

# Enable IOAM processing on a specific network interface (e.g., eth0)
sudo sysctl -w net.ipv6.conf.eth0.ioam6_enabled=1

# Enable IOAM hop-by-hop extension header processing globally
sudo sysctl -w net.ipv6.conf.all.ioam6_enabled=1

To persist these network interface tuning settings across system reboots, append them to /etc/sysctl.d/99-ioam.conf:

# Persist IOAM kernel parameters
echo "net.ipv6.conf.all.ioam6_enabled = 1" | sudo tee -a /etc/sysctl.d/99-ioam.conf
echo "net.ipv6.conf.default.ioam6_enabled = 1" | sudo tee -a /etc/sysctl.d/99-ioam.conf

Attaching IOAM Trace Encapsulation to Routing Tables

To inject IOAM trace headers into live application traffic traversing a specific network path, utilize the ip route lightweight tunnel (encap) infrastructure:

# Route outbound traffic destined for 2001:db8:acad::/48 through an IOAM trace tunnel
sudo ip -6 route add 2001:db8:acad::/48 \
    encap ioam6 trace prealloc type 0x800000 ns 123 size 64 \
    via fe80::1 dev eth0

The command parameters specify:

• encap ioam6 trace: Directs the kernel to encapsulate matching packets in an IOAM trace header.
• prealloc: Pre-allocates fixed buffer space in the hop-by-hop header for intermediate routers to write metrics into.
• ns 123: Binds the trace operation to IOAM namespace 123.
• size 64: Allocates 64 bytes of telemetry trace space per packet.

Capturing and Auditing IOAM Packet Telemetry

To verify that live IPv6 packets carry valid IOAM hop-by-hop extension headers, execute tcpdump with verbose protocol decoding:

# Capture IPv6 Hop-by-Hop headers containing IOAM telemetry
sudo tcpdump -i eth0 -nn -vvv "ip6 and ip6[6] == 0" -c 10

The output prints the decoded IOAM Option Type (0x11 or 0x31), namespace identifier, and raw telemetry metrics inserted by each intermediate hop.

Removing and Resetting IOAM Configurations

When decommissioning a telemetry session or resetting namespace allocations, remove the routes and namespace handles cleanly:

# Remove the encapsulated IOAM route
sudo ip -6 route del 2001:db8:acad::/48

# Delete the IOAM namespace
sudo ip ioam namespace del 123

Configuring IPv6 IOAM via ip ioam provides network engineers with microsecond-accurate, per-hop network telemetry on live production traffic without relying on artificial synthetic probes.