Inspect and Rate-Limit Packet Traps with devlink

Packets are vanishing inside your switch ASIC and nothing in the kernel log says why, so you ask devlink what the hardware is trapping. With devlink trap you will list traps, groups and policers, read their counters and make one controlled policer change.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Confirm the installed command
2. Discover devices and packet traps
3. Inspect one trap and its statistics
4. Inspect trap groups before changing anything
5. Check the available policers
6. Apply a cautious policer change
7. Change a trap or group action only with a rollback plan
Common failure modes

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.

Time: about fifteen minutes for inspection, then ten more for a change.
You need: a Linux host with the iproute2 package and a devlink-capable network device.
Privileges: listing is normally unprivileged. Changing a trap, group or policer alters device behaviour and usually needs root.

Warning

Do not test these commands on a production interface during live traffic.

1. Confirm the installed command

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

$ 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 a failure. It means the kernel and drivers currently expose no packet traps through devlink. Do not invent a device identifier from an interface name.

When there is output, it contains device-specific trap names. The device identifier commonly looks like 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 if your device reports it.

Checkpoint

Save the exact device and trap names you intend to inspect. That saves you from copying an example identifier from another host.

3. Inspect one trap and its statistics

Pass the device, then trap, then 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. 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 still information: no matching traffic has been counted since the counter was reset or the device was initialised.

The command only reads state. If it says the device or trap does not exist, go back 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 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 statistics query, so substitute a group that 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 instead of switching every one to the new policy.

The three actions have different consequences:

trap sends the sole packet copy to the CPU.
drop drops the packet in the underlying device, with no copy to the CPU.
mirror forwards the packet and also sends a copy to the CPU.

Warning

mirror can raise 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 1 is not a universal default, so use only an identifier listed by the first command. Record the current rate, burst and any group association before you plan a change.

Tip

rate is in packets per second and burst is in packets. They are not bits per second or bytes, which matters when the trapped traffic is made of large packets.

6. Apply a cautious policer change

Warning

This is the first state-changing step. Poorly chosen values can cut control-plane visibility or leave the CPU exposed to too much traffic. Use a maintenance window or 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

Checkpoint

The second command is your check. The reported rate and burst should match what you asked for. If the driver rejects the update, assume nothing about partial application: inspect the policer again and treat 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

Recovery

Replace OLD_RATE and OLD_BURST with the 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 reading counters. Before changing one, record its current action and confirm that it is a changeable drop trap. A representative command:

$ 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. If the result is wrong, restore the recorded action with another devlink trap set.

Warning

Do not change control or exception traps just to force a test. Their actions protect normal control-plane operation, and the driver may reject the change.

Common failure modes

Empty listing. It means no objects are currently registered, not that a made-up PCI identifier is correct.
Operation not supported. This usually marks a driver capability boundary. Check the object with plain show before trying another option.
Success is not traffic. A clean command does not prove matching traffic exists. Use -s and read the counters after a controlled test.
Names do not travel. Trap names, group names and policer numbers are device-specific. Copy them from discovery output and never reuse them across hosts.
Root only where needed. Use elevated privileges for set operations, not for the whole diagnostic shell.

Done means

Version and device known. You have the installed iproute2 version and the device identifier.
Names discovered. Trap, group and policer names came from the target device.
Counters read. You checked statistics with -s rather than inferring from command success.
Changes recorded and verified. Any rate, burst or action change used elevated privileges, was recorded beforehand and was checked afterwards.
Rollback ready. A command using the recorded old values is to hand.