Configure IPv6 IOAM Namespaces and Schemas with ip ioam

You will inspect and configure the IPv6 In-situ OAM (IOAM) objects exposed by ip ioam: namespaces, schemas, and the link between them. The examples match iproute2 6.1.0, installed here as package version 6.1.0-1ubuntu6.4.

Allow about fifteen minutes, plus time to confirm the IOAM design used by your network. You need the ip command from the iproute2 package, an IOAM-capable kernel and permission to use the relevant netlink operations. These commands change kernel networking state, so run them during a controlled maintenance window and keep the values supplied by your network design close at hand.

1. Confirm the installed command

Start with a read-only version and help check. Neither command changes 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 }

The subcommand is ioam below the normal ip utility. The installed manual describes this interface as configuration for IOAM namespaces and schemas, including their mapping. It does not describe a service, a configuration file or a persistent database.

2. Inspect current namespaces and schemas

Read the two object types separately:

$ ip ioam namespace show
$ ip ioam schema show

An empty result means that this network namespace has no objects of that type. Output is host-specific, so preserve it before making changes:

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

These are ordinary reads, but the kernel can still reject them when the IOAM netlink interface is unavailable or your process lacks permission. On this machine, an unprivileged probe returns RTNETLINK answers: Operation not permitted. Retry with the privilege required by your host's policy, normally:

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

sudo does not add IOAM support to a kernel. If the privileged commands still fail, check the running kernel and distribution documentation before changing boot parameters or network services.

3. Add a namespace with the values your design specifies

A namespace has an ID. The command can also carry a 32-bit data value, a 64-bit wide data value, or both. The manual's concrete example is:

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

The hexadecimal values are example payloads, not safe defaults for a production network. Replace them only with values defined by your IOAM deployment. Do not invent a namespace ID because another node may already use it, and do not assume that a value meaningful to one collector is meaningful to another.

This is a state-changing command. Before running it, check the existing listing and choose an unused ID. Afterward, verify the result:

$ sudo ip ioam namespace show
1

The exact listing format can vary with the kernel and iproute2 build. The useful check is that the namespace you requested is present. If the add operation fails, read the error before retrying. Repeating a command with the same ID will not repair an unknown configuration problem.

4. Add a schema only when its DATA format is known

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 deliberately a placeholder. The installed ip-ioam(8) manual specifies that a schema has an ID and DATA, but it does not define the encoding, field order or a universal example for DATA. Do not replace it with a guessed string or assume it is interchangeable with the namespace data values.

Once your deployment documentation supplies the exact value, add it and inspect the result:

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

In a shell, angle brackets are placeholder notation and must not be pasted literally. Quote a schema value if its documented representation contains shell metacharacters. If the command rejects the value, preserve the error and consult the IOAM implementation or specification that defines the encoding.

5. Link the schema to the namespace

Both objects must exist before you create the mapping. The following links schema 7 to namespace 1, matching the manual's example:

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

This changes the namespace's schema mapping. A listing that shows the mapping is the checkpoint; do not infer success solely from a zero exit status if the output is available. The command has no separate create operation for the mapping.

To remove the mapping while keeping the namespace and schema, use the documented none value:

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

This is the undo for the mapping step. It does not delete either object.

6. Delete objects only after checking dependencies

Deletion is irreversible from the command's point of view: it removes the object from the current kernel networking state. First save fresh listings and confirm that the ID is the intended one:

$ 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

Unlink a namespace from its schema before deleting either side. Then delete the selected object:

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

Verify both listings again. If a deletion fails, leave the remaining state in place and investigate the reported error. Do not work around a dependency by restarting networking: that can disrupt unrelated interfaces and routes.

7. Keep the scope of the configuration clear

These commands configure the current kernel networking namespace. The manual does not promise persistence across reboot, network-namespace destruction or service restart. If the objects must return after boot, use the network-management mechanism approved for your distribution and validate that it supports these exact IOAM operations. Do not assume that writing an arbitrary file under /etc will make the state persistent.

Also keep three failure cases separate: an unsupported or unavailable kernel interface, insufficient netlink permission, and invalid IOAM data. The same Operation not permitted wording can be a permission problem, while a rejected schema value is a data or implementation problem. Capture the command, package version, kernel version and complete error when escalating.