Manage vDPA Devices Safely with iproute2

vdpa is the iproute2 command for finding, inspecting, creating and removing vDPA devices on a running kernel. It is a control-plane tool: it talks to the kernel over vdpa Netlink, so an installed binary alone does not mean a usable device is actually present.

Allow about fifteen minutes for an inspection, or longer if you are creating a device and need to confirm which driver owns its management device. These examples use the installed Ubuntu package iproute2 6.1.0-1ubuntu6.4, whose utility reports itself as iproute2 6.1.0. Run inspection commands as an ordinary user first. Device creation and deletion may require elevated privileges, depending on your system policy.

Checkpoint: This guide changes kernel-managed device state only in the explicitly marked creation and deletion steps. Stop if you are working on a host where a virtual machine, container or network service depends on the target device.

1. Confirm the installed utility

Start by checking which executable will run and which iproute2 release it belongs to:

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

The top-level syntax is vdpa [OPTIONS] { dev | mgmtdev } { COMMAND | help }. The dev object represents a vDPA device. The mgmtdev object represents a management device that can create vDPA devices. JSON output is available with -j, and -p makes that JSON easier to read.

For a script or monitoring check, prefer JSON and check the exit status. Do not parse a human-formatted listing if a stable machine-readable result is available:

$ vdpa -j mgmtdev show
$ printf 'exit status: %s\n' "$?"
exit status: 0

The output above is the shape of a successful query, not a promise that every host has a management device. An empty result can be valid. On a host without the vdpa Netlink support needed by this utility, the command instead fails with Failed to connect to vdpa Netlink and a non-zero status. That is a host capability or kernel setup problem, not an empty inventory.

2. List management devices first

Inspect management devices before attempting to create anything:

$ vdpa mgmtdev show
$ printf 'exit status: %s\n' "$?"
exit status: 0

The names are host-specific. A typical name might be supplied by a simulator or a hardware driver, but do not guess it from a module name. Copy the exact management-device name from your own output and store it in a shell variable:

$ MGMTDEV='REPLACE_WITH_A_NAME_FROM_vdpa_mgmtdev_show'
$ printf '%s\n' "$MGMTDEV"
REPLACE_WITH_A_NAME_FROM_vdpa_mgmtdev_show

If the listing is empty, stop here and investigate the driver or simulator setup. vdpa dev add cannot create a device without a management device that supports addition.

3. Inspect existing vDPA devices

List all vDPA devices and then inspect one device by name if the list is not empty:

$ vdpa dev show
$ vdpa dev show REPLACE_WITH_DEVICE_NAME

The first command omits the optional device argument and lists all devices. The second narrows the query to one device. To inspect device configuration, use the separate config show command:

$ vdpa dev config show REPLACE_WITH_DEVICE_NAME

Keep these queries separate from creation. They are read-only checks and give you a before-state to compare against later. If a device is already present, record its exact name and whether another service owns it before making changes.

Vendor-specific virtqueue statistics are also available when the device and driver support them. The queue index is required:

$ vdpa dev vstats show REPLACE_WITH_DEVICE_NAME qidx 0

The result is a set of name-value pairs defined by the vendor. A failure here does not necessarily mean that the device is unusable; the driver may simply provide no statistics for that queue or this command.

4. Create a device deliberately

Warning: Creation changes kernel state and may make a device visible to a guest or another consumer. Confirm the management-device name, requested device name and MAC address before running the command. Use elevated privileges only if your system requires them.

$ sudo vdpa dev add name REPLACE_WITH_NEW_DEVICE_NAME mgmtdev "$MGMTDEV" mac 02:00:00:00:00:01 mtu 1500
$ vdpa dev show REPLACE_WITH_NEW_DEVICE_NAME

The name and mgmtdev arguments are required. The mac and mtu values apply to a network vDPA device and are optional. The MAC address must be suitable for your environment; the locally administered example above is only a placeholder. The mtu value describes the network device, not a request to resize unrelated interfaces.

The max_vqp argument can be used when the management device supports it:

$ sudo vdpa dev add name REPLACE_WITH_NEW_DEVICE_NAME mgmtdev "$MGMTDEV" max_vqp 8

Do not add optional arguments merely because they appear in an example. Match them to the capabilities and requirements of the driver that supplied your management device. If the add command fails, inspect the error, confirm the management-device name, and check whether a partial device was created before retrying.

5. Verify configuration and recover from a mistake

After a successful add, verify both existence and configuration:

$ vdpa dev show REPLACE_WITH_NEW_DEVICE_NAME
$ vdpa dev config show REPLACE_WITH_NEW_DEVICE_NAME

For a repeatable check, request JSON and fail the shell command if either query fails:

$ vdpa -j dev show REPLACE_WITH_NEW_DEVICE_NAME > vdpa-device.json
$ test -s vdpa-device.json
$ vdpa -j dev config show REPLACE_WITH_NEW_DEVICE_NAME > vdpa-config.json
$ test -s vdpa-config.json

The redirected files are local inspection artefacts. Remove them when no longer needed with rm -- vdpa-device.json vdpa-config.json; this does not remove the kernel device.

Recovery: If you created the wrong device and it is safe to remove, delete it by its exact name:

$ sudo vdpa dev del REPLACE_WITH_NEW_DEVICE_NAME
$ vdpa dev show REPLACE_WITH_NEW_DEVICE_NAME
Failed to connect to vdpa Netlink

The final output above is only an example of a failed lookup on a host with no vdpa Netlink connection. On a functioning host, a missing device may produce an error or an empty result. Treat a successful deletion as the point at which the device is no longer listed. Do not delete a device just to test the command if a guest or service may be using it.

Common traps

Done means