Inspect and Safely Reconfigure Devlink Ports with iproute2

You will finish with a repeatable way to inspect devlink ports, identify the exact device and port index, and understand the checks around splitting, adding, activating or deleting ports. The examples match the installed iproute2 6.1.0 command and its devlink-port(8) interface.

Allow about fifteen minutes for inspection, or longer for a hardware change. You need a shell and the iproute2 package. Port changes normally require root or an equivalent capability and can disrupt networking. Start with the read-only commands, record the current state, and use a maintenance window for any command that changes hardware or function state.

1. Confirm the installed command

Check which executable is selected and which iproute2 release supplies it. These are ordinary read-only commands:

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

The manpage is older than the installed binary, so use the binary's help output as a final syntax check on this host. This guide covers the port commands exposed by that installation. A different distribution or iproute2 release may offer more subcommands.

2. Inventory ports without changing anything

List every devlink port. This does not create, remove or reconfigure a port and should not need sudo:

$ devlink port show

On a host without a devlink-capable device, the command may produce no port records. On a supported device, each record identifies a bus, device address and port index. The address used by later commands has this form:

BUS_NAME/BUS_ADDRESS/PORT_INDEX

For example, the installed manual uses pci/0000:01:00.0/1. Do not copy that identifier unless it appears on your machine. Narrow the inventory to one known port when you have an exact identifier:

$ devlink port show pci/0000:01:00.0/1

Checkpoint: write down the complete identifier, not just the final number. Port index 1 is meaningful only with its device.

3. Inspect before planning a change

Use the record from devlink port show to establish the port's current type and attributes. The command's output is driver-specific, so treat the actual record as authoritative rather than assuming that a physical connector, Ethernet interface or port index maps one-to-one to another.

The port type can be set to eth, ib or auto. Setting it changes a device attribute and is not a harmless display operation. Review the current output and the hardware documentation first:

$ sudo devlink port set pci/0000:01:00.0/1 type eth
$ devlink port show pci/0000:01:00.0/1

Use your real identifier and the type required by the driver. This can affect how the driver presents the port, and the command may be rejected if the hardware does not support the requested type. If the change is wrong, run the same command with the previous type shown by your recorded output, then inspect the port again. Do not guess the previous value.

4. Understand split and unsplit operations

A port split changes one port into a requested number of ports. It is a hardware-level operation, not a way to create ordinary Linux network interfaces:

$ sudo devlink port split pci/0000:01:00.0/1 count 4
$ devlink port show pci/0000:01:00.0/1

The count is the number of ports requested. Expect the driver to report the resulting records, indices or an error according to the hardware. Recheck the full inventory as well, because the split group can expose more than the original record:

$ devlink port show

Splitting may remove or re-enumerate ports and can interrupt traffic. Do not run it against a production uplink merely to see what happens. If the operation must be reversed, use unsplit on any port in the split group, as permitted by the driver:

$ sudo devlink port unsplit pci/0000:01:00.0/1
$ devlink port show

There is no universal rollback interval: the driver and hardware decide when an unsplit operation is accepted. Save the pre-change inventory and keep a console or out-of-band route available.

5. Manage a PCI subfunction port carefully

devlink port add can create a port for a PCI subfunction. The manual's representative shape supplies a device, flavour, PF number and SF number:

$ sudo devlink port add pci/0000:06:00.0 flavour pcisf pfnum 0 sfnum 88
$ devlink port show pci/0000:06:00.0

The driver may allocate the port index when it is omitted, or you can request an index with DEV/PORT_INDEX. The resulting port must be identified from the show output before you configure it. An external controller can be selected with controller CNUM, when the device supports that feature.

Adding a port changes device state. Record the returned identifier and do not continue if the driver reports an error. When the function supports state management, configure its hardware address before activation:

$ sudo devlink port function set pci/0000:06:00.0/PORT_INDEX hw_addr 00:00:00:11:22:33
$ sudo devlink port function set pci/0000:06:00.0/PORT_INDEX state active
$ devlink port show pci/0000:06:00.0/PORT_INDEX

Replace PORT_INDEX with the actual index. Activation initiates function enumeration and driver loading, so the machine may gain a new device. Check the resulting operational state using the port output and the network tooling appropriate to that driver.

To retire the function, deactivate it first and wait for the device teardown, then delete the port:

$ sudo devlink port function set pci/0000:06:00.0/PORT_INDEX state inactive
$ devlink port show pci/0000:06:00.0/PORT_INDEX
$ sudo devlink port del pci/0000:06:00.0/PORT_INDEX
$ devlink port show pci/0000:06:00.0

Deletion is destructive to that devlink port's configuration. Keep the original add command and values so you can recreate it if the device and driver support that workflow. If the function cannot be deactivated, stop: investigate its users instead of forcing deletion.

6. Check port parameters without changing them

Port configuration parameters are displayed through the devlink dev param form shown in the port manual. List supported parameters first:

$ devlink dev param show

For a single parameter, include the complete device and name reported by that command:

$ devlink dev param show pci/0000:01:00.0/1 name PARAMETER

Changing a parameter is a separate, elevated operation. The configuration mode controls when it takes effect: runtime applies while the driver runs, driverinit waits for a driver reload, and permanent writes non-volatile device memory and requires a hard reset according to the manual. Prefer runtime for a planned test when the parameter supports it:

$ sudo devlink dev param set pci/0000:01:00.0/1 name PARAMETER value VALUE cmode runtime
$ devlink dev param show pci/0000:01:00.0/1 name PARAMETER

Do not use permanent as a shortcut for persistence. It can write hardware memory and may survive operating-system changes. Record the old value and the supported modes before making a change; recovery depends on the device's own parameter support.

7. Use health reporting when a port fails

The port health commands are an alias for devlink-health(8). Show supported reporters before attempting recovery:

$ devlink port health show
$ devlink port health show pci/0000:01:00.0/1 reporter tx

These commands are read-only. The health interface also exposes recover, diagnose, dump and set actions, but their accepted arguments and effect depend on the reporter and driver. A recovery action can reset a component or interrupt traffic. Use it only after recording the health output and consulting the device documentation.