Inspect Linux Network Devices Safely with devlink

You will use devlink to discover the switch or network devices exposed through Linux devlink, inspect their ports, and capture machine-readable output without changing hardware state. Allow about 15 minutes for a first inspection. The examples are read-only unless a command is explicitly marked as disruptive.

This guide uses the installed iproute2 package, version 6.1.0-1ubuntu6.4. The command-line interface and available objects are driver-dependent. A system can have working network interfaces without exposing anything through devlink.

1. Confirm the installed tool

Start as your ordinary user. The version option is -V, with a capital letter. The long spelling --version is not accepted by this installed command.

$ command -v devlink
/usr/sbin/devlink
$ devlink -V
devlink utility, iproute2-6.1.0

The version line identifies the iproute2 utility, not the firmware or driver managing a device. Keep those versions separate when reporting a problem.

2. List devlink devices

The main inventory command is devlink dev show. With no device argument it asks the kernel for every registered devlink device.

$ devlink dev show

No output and exit status 0 means this query found no device to print. That is different from a command failure. On this machine, the equivalent JSON query returns an empty object:

$ devlink -j dev show
{"dev":{}}

On a host with a supported device, expect a device identifier such as pci/0000:03:00.0. Do not invent that identifier. Copy the exact value from your own output before using it in a later command.

Check the status directly when a script needs to distinguish an empty result from an error:

$ devlink dev show
$ printf 'devlink exit status: %s\n' "$?"
devlink exit status: 0

3. Inspect the device and its ports

Ask the installed command what the device object supports before trying a specialised operation:

$ devlink dev help
Usage: devlink dev show [ DEV ]
       devlink dev eswitch set DEV [ mode { legacy | switchdev } ]
       devlink dev param set DEV name PARAMETER value VALUE cmode { permanent | driverinit | runtime }
       devlink dev reload DEV [ netns { PID | NAME | ID } ]
       devlink dev info [ DEV ]
       devlink dev flash DEV file PATH [ component NAME ]
       devlink dev selftests run DEV [id TESTNAME ]

The full help text is longer than this example. It shows an important boundary: show and info inspect state, while reload, flash, parameter changes and some self-tests can affect a device.

If a device identifier appeared in step 2, substitute it literally:

$ DEV='pci/0000:03:00.0'
$ devlink dev info "$DEV"
$ devlink port show "$DEV"

The placeholder above is not a value to guess. Replace it only with an identifier printed by your host. Port output can include a devlink port identifier and a related netdevice name. The friendly netdevice name is normally shown; use -n when you need to turn off these nice names and see the devlink identification instead.

Port layout is device and driver specific. Linux documentation describes a devlink port as a logical ingress or egress point, not necessarily a one-to-one copy of the interfaces shown by ip link.

4. Save JSON for repeatable inspection

Use -j for JSON output. Add -p when a human needs formatted JSON. Put options before the object name:

$ devlink -p -j dev show
{
    "dev": {}
}
$ devlink -j port show
{"port":{}}

JSON is useful for collection because it avoids parsing aligned columns. It does not make unsupported data appear: an empty result still means that the kernel exposed no objects for that query. If you need hexadecimal values, add -x; if you need IEC units for human-readable rates, add -i.

For a one-off record, redirect standard output to a new file rather than overwriting an existing capture:

$ devlink -j dev show > devlink-devices.json.new
$ test -s devlink-devices.json.new
$ mv devlink-devices.json.new devlink-devices.json

That final move replaces the old capture only after the command has produced non-empty output. If the command fails, remove the .new file after checking its contents and keep the previous record. The command itself does not alter the device.

5. Watch netlink events when investigating a change

devlink monitor watches for devlink netlink messages. Start with the broad command in a terminal used only for observation:

$ devlink monitor all

Leave it running while an already-approved maintenance action takes place in another terminal. Stop it with Ctrl-C; this ends the monitor and does not undo the event it observed. Narrow the stream when the output is noisy:

$ devlink monitor dev port health trap

The monitor syntax accepts all or an object list. It reports messages; it does not provide a rollback facility. Record the original device and port inventory before a maintenance window so that you have something concrete to compare afterwards.

6. Keep state-changing commands out of an inspection

Several commands visible in devlink dev help are operational controls, not harmless discovery. A reload can interrupt a device, a flash operation can replace firmware, and changing an eswitch mode, port split, port function or persistent parameter can disrupt networking. Do not paste any of these into a production shell merely because they appeared in help.

For the same reason, do not use devlink port set, devlink port split, devlink port unsplit, devlink port add or devlink port del during an inventory exercise. If a later change is required, first record the current output, confirm the exact driver documentation, arrange console or out-of-band recovery, and schedule a maintenance window. There is no universal undo command: the recovery procedure depends on the driver, device and change.

Most read-only queries can be attempted without elevated privileges. If a query fails with a permissions error, retrying with sudo may be appropriate on a machine you administer, but it will not create a missing devlink device or add unsupported commands. Treat firmware paths, device identifiers and batch files as sensitive operational inputs.

7. Use batch mode only for reviewed read-only commands

The -b option reads commands from a file or standard input and stops at the first failure. -force continues after errors but returns a non-zero status if any command failed. That makes batch mode useful for a reviewed inventory, but risky if the file contains a reload, flash or set operation.

$ devlink -b /path/to/reviewed-devlink-inventory.txt
$ printf 'batch exit status: %s\n' "$?"

Review the file before running it. Keep one read-only command per line, use explicit device identifiers copied from discovery, and do not put secrets in comments or shell-expanded paths. A batch run is not transactional: if a later command fails, earlier commands have not been rolled back.