Inspect and Safely Reconfigure RDMA Devices with rdma dev

Rename an RDMA device without checking who depends on the old name, and something a service unit or monitoring rule expected just stops resolving. This covers a small operational workflow with rdma dev: listing devices and, when you've actually planned the change, renaming one, moving it to an existing network namespace, or changing its adaptive interrupt moderation setting.

• You need: a shell and the rdma command from the iproute2 package. Listing is read-only, about fifteen minutes. The set commands change kernel networking state, can disrupt users of the device, and belong in an administrative shell during a maintenance window.

The examples match the rdma-dev(8) interface in iproute2 6.1.0-1ubuntu6.4, installed on this machine.

1. Check the installed command

Confirm the binary and package version you're using. This is an ordinary, read-only check:

$ command -v rdma
/usr/bin/rdma
$ rdma -V
rdma utility, iproute2-6.1.0
$ dpkg-query -W -f='${Package} ${Version}\n' iproute2
iproute2 6.1.0-1ubuntu6.4

The package version and the utility's own displayed version are related but not identical strings. Record both in a change note if you need to reproduce the result on another host.

2. Inventory the RDMA devices

List every device, no mutation:

$ rdma dev show

Expect one entry per RDMA device the kernel exposes, with attributes like its current name and state. An empty result is still useful information: there's no device for this command to configure in the current environment. Don't invent a device name from a PCI address or a network interface name.

The shorter form works too:

$ rdma dev

To inspect one device, substitute an exact name copied from the listing:

$ rdma dev show RDMA_DEVICE_NAME

Replace RDMA_DEVICE_NAME with a value like mlx5_3 only when that exact device appears on your host. If the name is wrong, fix the selection rather than trying repeated changes hoping one sticks.

3. Rename a device deliberately

A stable name can make host-specific automation easier, but renaming is a live configuration change. First capture the current listing and search your configuration, service units and monitoring rules for the old name: a consumer that still expects it may stop working the moment you change it.

The command shape:

$ sudo rdma dev set RDMA_DEVICE_NAME name NEW_RDMA_NAME

For example, if the inventory really contains mlx5_3 and the new name is unused:

$ sudo rdma dev set mlx5_3 name rdma_0
$ rdma dev show rdma_0

There's no generic undo documented by rdma-dev(8). To reverse a successful rename, issue another administrative rename with the recorded old and new names:

$ sudo rdma dev set rdma_0 name mlx5_3
$ rdma dev show mlx5_3

Do this only after confirming the old name is free and dependent services are ready for the transition.

4. Move a device to an existing network namespace

The namespace target has to already exist. Create and manage namespaces with ip(8); rdma dev set only performs the device assignment. Check the available names first:

$ ip netns list
NAMESPACE_NAME (id: NAMESPACE_ID)

That's a shape, not guaranteed output. If the target is absent, stop and have the namespace owner create it through the host's normal network configuration. Moving an RDMA device can disconnect applications and change which processes can reach it.

Once reviewed, use the exact device and namespace names:

$ sudo rdma dev set RDMA_DEVICE_NAME netns NAMESPACE_NAME
$ sudo ip netns exec NAMESPACE_NAME rdma dev show

The verification command runs inside the target namespace: the device should show up there, while a host-level rdma dev show may no longer list it at all.

5. Set adaptive interrupt moderation

Adaptive moderation changes how the RDMA device manages interrupt moderation for completion queues. The manpage treats this as a global device setting, even though the value is printed per completion queue because it's fixed when that queue is allocated. Treat this as a performance and latency change, not a harmless display preference.

Use one of the two documented values:

$ sudo rdma dev set RDMA_DEVICE_NAME adaptive-moderation on
$ sudo rdma dev set RDMA_DEVICE_NAME adaptive-moderation off

Make one change, measure the workload, and keep a record of the previous setting. There's no separate query or undo subcommand for this one: recovery means issuing the opposite value once you actually know what the previous value was. If you don't, don't guess: check the device's operational record or ask the workload owner.

6. Keep diagnostics narrow

Ask the command for its own device-specific help when you need to confirm the accepted grammar:

$ rdma dev help
Usage: rdma dev show [DEV]
       rdma dev set [DEV] name DEVNAME
       rdma dev set [DEV] netns NSNAME
       rdma dev set [DEV] adaptive-moderation [on|off]

This is from the installed iproute2 build. It confirms show accepts an optional device, while each set form has its own final argument. Don't append flags borrowed from another rdma object, such as link or resource.

Common traps

• Wrong device name reported? Re-run rdma dev show and copy the name exactly rather than retyping it from memory.
• Permission failure? Go back to the administrative shell rather than weakening permissions on device or namespace files.
• Set succeeded but an application failed afterwards? Treat it as an operational dependency problem: restore the recorded state if safe, then inspect service logs and namespace placement.