Inspect and Rate-Limit Hardware Packet Traps with devlink

You will use devlink trap to discover the packet traps, groups and policers exposed by a devlink device, inspect their counters, and make one controlled policer change. The examples use the installed iproute2 6.1.0 command. Hardware support is driver-specific, so an empty listing is a valid result on a machine without a suitable device.

Allow about fifteen minutes for inspection and a further ten minutes for a change. You need a Linux host with the iproute2 package and a devlink-capable network device. Listing is normally unprivileged, but changing a trap, group or policer changes device behaviour and usually requires root. Do not test these commands on a production interface during live traffic.

1. Confirm the installed command

Start with read-only checks. The version option is -V, not --version in this installed build:

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

Checkpoint: if devlink -V does not report iproute2 6.1.0, keep the local manual page beside you. Option details and output fields can vary between releases.

2. Discover devices and packet traps

Ask devlink for every trap registered by every available device:

$ devlink trap show

On a host with no registered traps this prints nothing and exits successfully. That is not evidence that the command failed. It means the kernel and drivers currently expose no packet traps through devlink. Do not invent a device identifier from an interface name.

When output is available, it contains device-specific trap names. The device identifier commonly has a form such as pci/0000:01:00.0, but use the exact value from your own listing. A trap name such as source_mac_is_multicast is only usable when your device reports it.

Checkpoint: save the exact device and trap names you intend to inspect. This avoids the common distraction of copying an example identifier from another host.

3. Inspect one trap and its statistics

Pass the device followed by trap and the trap name. Add -v for attributes and -s for counters:

$ sudo devlink -vs trap show pci/0000:01:00.0 trap source_mac_is_multicast

Replace both placeholders with names from your discovery output. The exact fields are driver-dependent. A statistics view can show packet and byte counts, and may show drops attributed to a policer. A zero counter is useful: it says that no matching traffic has been counted since the relevant counter was reset or the device was initialised.

The command only reads state. If it reports that the device or trap does not exist, return to step 2 and copy the names exactly. If it reports an unsupported operation, the driver may register the trap without implementing every optional attribute.

4. Inspect trap groups before changing anything

Groups let the driver expose related traps as one operational unit. List them first:

$ devlink trap group show
$ sudo devlink -s trap group show pci/0000:01:00.0 group l2_drops

The first command discovers group names. The second is an example of a device and group-specific statistics query; substitute a group that actually exists. Group actions apply to member traps where the action is allowed. Non-drop traps cannot have their action changed, so a group operation can skip some members rather than turning every member into a new policy.

The three actions have different consequences. trap sends the sole packet copy to the CPU. drop drops it in the underlying device without sending a copy to the CPU. mirror forwards it and also sends a copy to the CPU. The last option can increase CPU load, so do not use it as a casual diagnostic toggle.

5. Check the available policers

Policers limit how many trapped packets the hardware sends towards the CPU. Discover them without changing state:

$ devlink trap policer show
$ sudo devlink -s trap policer show pci/0000:01:00.0 policer 1

A policer number is local to the device. The example number 1 is not a universal default. Use only an identifier listed by the first command. Record the current rate, burst and any group association before planning a change.

rate is measured in packets per second and burst in packets. These are packet counts, not bits per second or bytes. That distinction matters when the trapped traffic contains large packets.

6. Apply a cautious policer change

This is the first state-changing step. Changing a policer can reduce control-plane visibility or leave a CPU exposed to too much traffic if the values are poorly chosen. Take a maintenance window or use a non-production device, and keep the old values recorded.

$ sudo devlink trap policer set pci/0000:01:00.0 policer 1 rate 1000 burst 128
$ sudo devlink -s trap policer show pci/0000:01:00.0 policer 1

The second command is the checkpoint. Confirm that the reported rate and burst match the values you requested. If the driver rejects the update, no assumption should be made about partial application; inspect the policer again and use its reported values as the current state.

To undo this example, set the previously recorded rate and burst, not guessed values:

$ sudo devlink trap policer set pci/0000:01:00.0 policer 1 rate OLD_RATE burst OLD_BURST

Replace OLD_RATE and OLD_BURST with shell-safe decimal values you recorded before the change. If you did not record them, do not guess. The listing is your source of truth.

7. Change a trap or group action only with a rollback plan

Action changes are more disruptive than counter inspection. Before changing one, record its current action and confirm that it is a changeable drop trap. A representative command is:

$ sudo devlink trap set pci/0000:01:00.0 trap source_mac_is_multicast action drop
$ sudo devlink -v trap show pci/0000:01:00.0 trap source_mac_is_multicast

This example discards the packet in hardware and removes its CPU copy. It can hide traffic that operators were relying on for diagnosis. Restore the recorded action with another devlink trap set command if the result is wrong. Do not change control or exception traps to force a test; their actions protect normal control-plane operation and may be rejected by the driver.

Common failure modes

• An empty listing means there are no currently registered objects, not that a made-up PCI identifier is correct.
• Operation not supported usually identifies a driver capability boundary. Check the object with plain show before trying another option.
• A successful command does not prove that matching traffic exists. Use -s and inspect counters after a controlled test.
• Trap names, group names and policer numbers are device-specific. Copy them from discovery output and do not reuse them across hosts.
• Use elevated privileges only for set operations. Do not run the whole diagnostic shell as root when read-only commands are enough.