Inspect and Safely Reconfigure Devlink Ports with iproute2

Splitting a switch port in the wrong place drops a whole uplink, so devlink port deserves a read-first habit. This guide gives you a repeatable way to inspect ports, identify the exact device and port index, and understand the checks around splitting, adding, activating or deleting them. The examples match the installed iproute2 6.1.0 and its devlink-port(8) interface.

• Time: about fifteen minutes to inspect, longer for a hardware change.
• You need: a shell and the iproute2 package.
• Privileges: port changes normally need root or an equivalent capability, and can disrupt networking.

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 man page is older than the installed binary, so use the binary's help output as the final syntax check on this host. This guide covers the port commands that installation exposes. 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 anything and should not need sudo:

$ devlink port show

On a host without a devlink-capable device, the command may print no port records. On a supported device, each record gives a bus, device address and port index. Later commands use this address form:

BUS_NAME/BUS_ADDRESS/PORT_INDEX

The installed manual uses pci/0000:01:00.0/1 as its example. Do not copy that identifier unless it appears on your machine. When you have an exact identifier, narrow the inventory to that one port:

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

3. Inspect before planning a change

Use the record from devlink port show to establish the port's current type and attributes. Output is driver-specific, so treat the actual record as authoritative. Do not assume a physical connector, Ethernet interface and port index map one-to-one.

The port type can be set to eth, ib or auto. Setting it changes a device attribute, so 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 your driver requires. This can change how the driver presents the port, and the hardware may reject the requested type.

4. Understand split and unsplit operations

A port split turns 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, depending on the hardware. Recheck the full inventory too, because the split group can expose more than the original record:

$ devlink port show

To reverse it, use unsplit on any port in the split group, as the driver permits:

$ 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 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

• Port index: the driver may allocate it when omitted, or you can request one with DEV/PORT_INDEX. Identify the resulting port from the show output before you configure it.
• External controller: select one with controller CNUM, when the device supports it.
• State change: 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 operational state using the port output and the network tooling that suits the 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

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 the 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 decides when it takes effect:

• runtime applies while the driver runs.
• driverinit waits for a driver reload.
• permanent writes non-volatile device memory and, according to the manual, requires a hard reset.

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

7. Use health reporting when a port fails

The port health commands are an alias for devlink-health(8). Show the 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.