Configure IPv6 IOAM Namespaces and Schemas with ip ioam

Someone hands you an IOAM design document and says "make this box match it": ip ioam is the tool for that job. It manages exactly two object types, namespaces and schemas, and the link between them. The examples here match iproute2 6.1.0, installed as package version 6.1.0-1ubuntu6.4.

• Time: about fifteen minutes, plus whatever it takes to track down the design values.
• You need: the ip command from iproute2, an IOAM-capable kernel, and permission to use the relevant netlink operations.
• Not needed: a config file. IOAM state here is kernel networking state, not a service.

These commands change kernel networking state, so do the changing steps in a maintenance window, with your network design's actual values close at hand rather than the examples below.

1. Check the command matches what you expect

Two read-only commands, neither touches IOAM state:

$ ip -Version
ip utility, iproute2-6.1.0, libbpf 1.3.0
$ ip ioam help
Usage:  ip ioam { COMMAND | help }
        ip ioam namespace show
        ip ioam namespace add ID [ data DATA32 ] [ wide DATA64 ]
        ip ioam namespace del ID
        ip ioam schema show
        ip ioam schema add ID DATA
        ip ioam schema del ID
        ip ioam namespace set ID schema { ID | none }

ioam is a subcommand under the ordinary ip utility, and that usage block is the whole grammar: namespaces, schemas, and a way to set a schema on a namespace. Nothing here describes a service, a config file or a persistent database.

2. Read the current namespaces and schemas

Look at each object type on its own:

$ ip ioam namespace show
$ ip ioam schema show

Nothing back means this network namespace has none of that object type yet, not that the command failed. Save what is there before you touch anything:

$ ip ioam namespace show > /tmp/ioam-namespaces.before
$ ip ioam schema show > /tmp/ioam-schemas.before

These reads can still be blocked. On this machine an unprivileged probe returns RTNETLINK answers: Operation not permitted, in which case retry with the privilege your host's policy requires:

$ sudo ip ioam namespace show
$ sudo ip ioam schema show

sudo unlocks the read. It does not add IOAM support to a kernel that lacks it. If the privileged version still fails, check the running kernel before you go anywhere near boot parameters or network services.

3. Add a namespace with your design's values

A namespace has an ID, and optionally a 32-bit data value, a 64-bit wide data value, or both. The manual's own example:

$ sudo ip ioam namespace add 1 data 0xdeadbeef wide 0xcafec0caf00dc0de

• Those hex values are example payloads. Swap them for values defined by your IOAM deployment, not safe-looking defaults.
• Don't pick your own ID. Another node may already be using it.
• Don't assume portability. A data value that means something to one collector may mean nothing to another.

Check the existing listing first, choose an unused ID, then verify:

$ sudo ip ioam namespace show
1

4. Add a schema, but only once you know the DATA format

The schema command takes an ID and a positional DATA value:

$ sudo ip ioam schema add 7 DATA_VALUE_FROM_YOUR_IOAM_DESIGN

DATA_VALUE_FROM_YOUR_IOAM_DESIGN is a placeholder on purpose. The installed ip-ioam(8) manual says a schema has an ID and DATA, and stops there: no encoding, no field order, no universal example. Do not guess a string, and do not assume it is interchangeable with a namespace's data values.

Once your deployment documentation gives you the real value, add it and check the result:

$ sudo ip ioam schema add 7 <VERIFIED_SCHEMA_DATA>
$ sudo ip ioam schema show

5. Link the schema to the namespace

Both objects need to exist first. This links schema 7 to namespace 1, matching the manual's example:

$ sudo ip ioam namespace set 1 schema 7
$ sudo ip ioam namespace show

To unlink without deleting either object, use the documented none value:

$ sudo ip ioam namespace set 1 schema none
$ sudo ip ioam namespace show

That is the undo for the mapping step only. Namespace and schema both survive it.

6. Delete in the right order

Deletion is irreversible as far as the command is concerned: it removes the object from the current kernel networking state. Save fresh listings first and double-check the ID:

$ sudo ip ioam namespace show
$ sudo ip ioam schema show
$ sudo ip ioam namespace show > /tmp/ioam-namespaces.before-delete
$ sudo ip ioam schema show > /tmp/ioam-schemas.before-delete

$ sudo ip ioam namespace set 1 schema none
$ sudo ip ioam schema del 7
$ sudo ip ioam namespace del 1

Verify both listings again afterwards. If a deletion fails, leave the remaining state alone and investigate the error rather than restarting networking to force it through, that can disrupt interfaces and routes that have nothing to do with IOAM.

Common traps

• Persistence. The manual makes no promise about surviving reboot, network-namespace destruction or a service restart. If the objects need to come back after boot, use your distribution's approved network-management mechanism, and confirm it actually supports these IOAM operations before relying on it. Writing an arbitrary file under /etc will not make the state persistent on its own.
• The same error, three causes. Operation not permitted can mean an unavailable kernel interface or a permissions problem. A rejected schema value is a data or implementation problem, a different thing entirely. Keep the command, package version, kernel version and full error together when escalating.