Shape devlink Traffic Rates with Nodes and Port Limits

You will inspect devlink rate objects, create a named parent node, attach a leaf port to it, and apply shared and maximum transmit rates. The examples use the devlink-rate(8) interface from iproute2 6.1.0, installed here as package version 6.1.0-1ubuntu6.4. Allow about fifteen minutes, plus time to confirm the correct device and port identifiers with whoever owns the network configuration.

These commands are for hardware and drivers that expose devlink rate objects. They do not shape an arbitrary Linux network interface. You need the devlink command and a device whose driver supports this feature. Reading state is normally unprivileged on a suitably configured host; creating, changing or deleting objects may require sudo and can affect live traffic.

1. Check the command and the current objects

Start with the installed binary and its built-in usage text. This is a read-only check:

$ command -v devlink
/usr/sbin/devlink
$ devlink -V
devlink utility, iproute2-6.1.0
$ devlink port function rate help
Usage: devlink port function rate help
       devlink port function rate show [ DEV/{ PORT_INDEX | NODE_NAME } ]
       devlink port function rate add DEV/NODE_NAME
               [ tx_share VAL ][ tx_max VAL ][ { parent NODE_NAME | noparent } ]
       devlink port function rate del DEV/NODE_NAME
       devlink port function rate set DEV/{ PORT_INDEX | NODE_NAME }
               [ tx_share VAL ][ tx_max VAL ][ { parent NODE_NAME | noparent } ]

List everything before choosing an identifier:

$ devlink port function rate show
pci/0000:03:00.0/1 type leaf parent some_group
pci/0000:03:00.0/2 type leaf tx_share 12Mbit
pci/0000:03:00.0/some_group type node tx_share 1Gbps tx_max 5Gbps

Your output is host-specific. A leaf belongs to a devlink port and is normally supplied by the driver. A node is a user-created group. A node name must not be a decimal number, because that would collide with the way a leaf port is addressed. If this command prints nothing, or JSON output is {"rate":{}}, stop here and identify a supported device rather than guessing a path.

2. Read one object in a script-friendly format

The ordinary display uses SI units such as Mbit and Gbps. Add -i when IEC units are easier to compare. Add -j for JSON; JSON rate values are always bytes per second, regardless of the display unit used for ordinary output.

$ devlink -j port function rate show DEV_PATH/PORT_INDEX
{
    "rate": {
        "DEV_PATH/PORT_INDEX": {
            "type": "leaf",
            "tx_share": 1500000
        }
    }
}
$ devlink -i port function rate show DEV_PATH/PORT_INDEX
DEV_PATH/PORT_INDEX type leaf tx_share 11718Kibit

The examples above show the output shapes from the manual. Exact values, indentation and fields depend on the driver and current configuration. A zero rate means unlimited, so unlimited values and an unset parent are omitted from the display. For automation, parse the JSON rather than matching the human-readable unit suffix.

3. Create an empty parent node

Creating a node changes device rate configuration. Confirm the name, limits and maintenance window first. The following creates a node with no limits, which is useful as a grouping point:

$ sudo devlink port function rate add DEV_PATH/test_group
$ devlink port function rate show DEV_PATH/test_group
DEV_PATH/test_group type node

Use a name that is meaningful on this device and is not only digits. The node belongs to the devlink device named by DEV_PATH; it is not a Linux directory or a persistent object in a general-purpose configuration file.

4. Set a group limit and attach a leaf

Values are floating-point or integer amounts followed by bits or bytes per second units. SI prefixes include kbit, mbit and gbit; byte units include kbps, mbps and gbps. IEC forms use kibit, mibit and so on. A bare number means bits per second, so explicit units are easier to review.

$ sudo devlink port function rate set DEV_PATH/test_group \
    tx_share 100mbit tx_max 500mbit
$ sudo devlink port function rate set DEV_PATH/PORT_INDEX \
    tx_share 20mbit tx_max 200mbit parent test_group
$ devlink port function rate show DEV_PATH/test_group
DEV_PATH/test_group type node tx_share 100Mbit tx_max 500Mbit
$ devlink port function rate show DEV_PATH/PORT_INDEX
DEV_PATH/PORT_INDEX type leaf parent test_group tx_share 20Mbit tx_max 200Mbit

tx_share is the minimum transmit rate shared by members of the same group. tx_max is the maximum transmit rate for that object. The parent node's limits apply to its children, but the exact enforcement is driver-dependent. A successful command means the driver accepted the setting; it does not prove that a workload is currently reaching or being limited by that rate.

Set the parent in the same command as the leaf rates when you want one reviewed change. If you need to change only one field, omit the others. When an argument is supplied more than once, the last occurrence wins, which is a useful reason to avoid generated command lines containing duplicate fields.

5. Verify the live state before testing traffic

Inspect both objects, then use JSON if a monitoring script will record the result:

$ devlink port function rate show
$ devlink -jp port function rate show DEV_PATH/PORT_INDEX
{
    "rate": {
        "DEV_PATH/PORT_INDEX": {
            "type": "leaf",
            "parent": "test_group",
            "tx_share": 2500000,
            "tx_max": 25000000
        }
    }
}

JSON values are bytes per second: 20 Mbit is 2,500,000 bytes per second and 200 Mbit is 25,000,000 bytes per second. Treat the displayed result as the authoritative check for what the driver stored. Test traffic only after confirming that the selected port serves the intended function.

6. Undo the test without leaving a child behind

Removing a parent while it still has a child is rejected. First detach the leaf, then remove the node. These are state-changing commands and can alter traffic behaviour immediately:

$ sudo devlink port function rate set DEV_PATH/PORT_INDEX \
    tx_share 0 tx_max 0 noparent
$ devlink port function rate show DEV_PATH/PORT_INDEX
DEV_PATH/PORT_INDEX type leaf
$ sudo devlink port function rate del DEV_PATH/test_group

Zero means unlimited, and noparent removes the group relationship. If the leaf had an existing limit before this test, record it first and restore those values instead of assuming zero is the right rollback. Re-run devlink port function rate show and confirm that the node no longer appears. If deletion fails, confirm the node name and check for another child still attached to it.

Common traps

• Wrong address: leaf objects use DEV/PORT_INDEX, while nodes use DEV/NODE_NAME. Copy the complete identifier from show.
• Unexpected units: human output uses SI units unless -i is selected; JSON is bytes per second. Do not compare the numbers without converting.
• Missing parent: parent NODE_NAME must name an existing node on the same device. Use noparent to detach instead.
• Failed deletion: a node with children cannot be deleted. Detach every child explicitly, then retry.
• No visible effect: rate enforcement details are part of the driver's implementation. Confirm the stored configuration, the correct function and the driver documentation before blaming the command.