Inspect and Safely Reconfigure RDMA Devices with rdma dev

You will finish with a small operational workflow for listing RDMA devices and, when you have a planned change, renaming one, moving it to an existing network namespace, or changing its adaptive interrupt moderation setting. The examples match the rdma-dev(8) interface in iproute2 6.1.0-1ubuntu6.4, installed on this machine.

Allow about fifteen minutes for inspection, or longer if you are changing a live host. You need a shell and the rdma command from the iproute2 package. Listing is read-only. The set commands change kernel networking state, can disrupt users of the device, and should be run from an administrative shell during a maintenance window.

1. Check the installed command

Start by confirming which binary and package version you are 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 displayed version are related but not identical strings. Record both in a change note if you need to reproduce the result on another host.

Checkpoint: if command -v finds nothing, install or repair the package through your normal operating system process before continuing. Do not copy a different host's rdma binary into place.

2. Inventory the RDMA devices

List every device with no mutation:

$ rdma dev show

The output is device-specific: expect one entry for each RDMA device that the kernel exposes, with attributes such as its current name and state. An empty result is still useful. It means there is no device for this command to configure in the current environment. Do not invent a device name from a PCI address or a network interface name.

You can also use the shorter form:

$ 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 such as mlx5_3 only when that exact device appears on your host. If the name is wrong, fix the selection rather than trying repeated changes.

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 the old name may stop working after the change.

The command shape is:

$ 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

The second command is the checkpoint. It should address the new name. If it fails, inspect the original listing and the command's error before making another change. A name collision or a typo is different from a missing device.

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

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

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

4. Move a device to an existing network namespace

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

$ ip netns list
NAMESPACE_NAME (id: NAMESPACE_ID)

The displayed line is 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 may alter which processes can reach it.

After a change review, 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 be visible there, while a host-level rdma dev show may no longer list it. If the move breaks a service, stop the service first, move the device back to the original namespace, and then restart it using the service's documented procedure. The namespace name alone is not a rollback record, so write down the original location before changing it.

5. Set adaptive interrupt moderation

Adaptive moderation changes how the RDMA device manages interrupt moderation for completion queues. The manpage describes this as a global device setting, even though the value is printed for each completion queue because it is fixed when that queue is allocated. Treat this as a performance and latency change, not as 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. The manpage does not provide a separate query or undo subcommand for this setting. Recovery therefore means issuing the opposite value when you know what the previous value was. If you do not know it, do not guess: consult the device's operational record or test with the workload owner.

6. Keep diagnostics narrow

Ask the command for its 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 help output is from the installed iproute2 build. It confirms that show accepts an optional device, while each set form has its own final argument. Do not append flags borrowed from another rdma object, such as link or resource.

If a command reports a wrong device name, re-run rdma dev show and copy the name exactly. If it reports a permission failure, return to the administrative shell rather than weakening permissions on device or namespace files. If a set command succeeds but an application fails afterwards, treat that as an operational dependency problem: restore the recorded state if safe, then inspect service logs and namespace placement.