Tune a Linux Interface Queue with the PIE AQM

You will configure the PIE active queue management (AQM) algorithm on one Linux interface, inspect the queue's delay and drop statistics, and remove the test configuration cleanly. The examples match iproute2 6.1.0, installed here as package version 6.1.0-1ubuntu6.4.

Allow about fifteen minutes. You need the tc command, the interface name, and root privileges for changes. A root qdisc affects traffic on that interface, so use a maintenance window for a busy link. This guide uses a placeholder interface and does not assume that a particular NIC exists.

1. Check the installed command

Start with read-only checks. These do not need elevated privileges on a normal installation:

$ tc -V
tc utility, iproute2-6.1.0, libbpf 1.3.0
$ ip -br link
lo               UNKNOWN        127.0.0.1/8 ::1/128
IFACE_NAME       UP             192.0.2.10/24

Replace IFACE_NAME with the real interface from your output. Do not use lo for a throughput test. If the interface name is not obvious, confirm it with your network configuration before making any queue change.

Checkpoint: record the current root qdisc before replacing it:

$ tc -s qdisc show dev IFACE_NAME
qdisc fq_codel 0: root refcnt 2 limit 10240p ...

Your qdisc, counters and formatting will differ. Save this output somewhere outside the command line. It is the best clue for restoring the previous setup if PIE is not suitable.

2. Understand what PIE will change

PIE estimates dequeue rate and uses the estimated delay to adjust a probability. Packets can then be dropped or, with ECN enabled, marked. It aims to keep queue delay near a target while retaining link utilisation. It is not a bandwidth shaper: it does not impose a rate limit.

With no options, the installed manpage documents a queue limit of 1000 packets, a target delay of 15ms, and a probability update interval of 15ms. It also documents default alpha 2 and beta 20 in the example output. ECN, byte mode and the dequeue-rate estimator are disabled unless requested. Treat these as this iproute2/kernel implementation's documented defaults, not universal defaults for every older or newer system.

The limit is in packets unless bytemode is selected. Byte mode scales the drop probability according to packet size; it does not turn the limit into a byte limit. The dequeue-rate estimator uses Little's law to calculate delay and adds an average dequeue rate to statistics.

3. Apply a conservative PIE configuration

This is the first state-changing step. sudo tc qdisc replace replaces the interface's root qdisc, which can alter latency, drops and connectivity for traffic using that link. Confirm the interface name twice before running it, and make sure you have console or another recovery access if the interface carries your current connection.

$ DEV=IFACE_NAME
$ sudo tc qdisc replace dev "$DEV" root pie limit 1000 target 15ms tupdate 15ms noecn nobytemode no_dq_rate_estimator

There is no need to spell out defaults, but doing so makes a copied configuration easier to review. The alpha and beta parameters are omitted here because the documented values are normally appropriate for a first test. If you set them, the manpage specifies a range of 0 to 32 for each.

Checkpoint: ask the kernel to show the resulting qdisc:

$ tc qdisc show dev "$DEV"
qdisc pie 8001: root refcnt 2 limit 1000p target 15.0ms tupdate 15.0ms alpha 2 beta 20

The handle and exact time formatting can differ. The important checks are that the qdisc kind is pie, the interface is the one you selected, and the requested limit and target are present.

4. Read PIE statistics

Use the statistics form after the interface has carried traffic:

$ sudo tc -s qdisc show dev "$DEV"
qdisc pie 8001: root refcnt 2 limit 1000p target 15.0ms tupdate 15.0ms alpha 2 beta 20
 Sent 123456 bytes 1200 pkt (dropped 3, overlimits 0 requeues 0)
 backlog 0b 0p requeues 0
  prob 0.001234 delay 9000us
  pkts_in 1200 overlimit 0 dropped 3 maxq 24 ecn_mark 0

Values are workload-dependent. delay is reported in microseconds, prob is the current drop or mark probability, dropped counts packets dropped by the qdisc, and ecn_mark counts ECN marks when ECN is enabled. A zero counter is not proof that PIE is broken; it may simply mean the link has not built a queue.

Use a short observation period and compare several readings. A rising backlog or delay means the offered traffic is exceeding what the link can currently dequeue. PIE can react to that queue, but it cannot create link capacity or repair a duplex, driver or physical-layer problem.

5. Enable ECN only when the path supports it

ECN changes the response from dropping to marking for the probability-controlled portion of the algorithm. End hosts and the path must handle ECN correctly. Test it with the applications and peers that actually use this link; do not enable it in production merely because the option is available.

$ sudo tc qdisc replace dev "$DEV" root pie limit 1000 target 15ms tupdate 15ms ecn
$ sudo tc -s qdisc show dev "$DEV"
qdisc pie 8001: root refcnt 2 limit 1000p target 15.0ms tupdate 15.0ms alpha 2 beta 20 ecn
 ... ecn_mark 0

The initial ecn_mark value may be zero. If you need ordinary dropping rather than marking, use noecn explicitly. PIE's manpage notes that beyond 10 percent, packets are dropped according to the probability even in ECN mode, so ECN is not a promise that every congested packet will be marked.

6. Try byte mode or the dequeue estimator deliberately

These options answer different questions. Use bytemode when packet sizes are varied and proportional treatment by byte is desirable:

$ sudo tc qdisc replace dev "$DEV" root pie limit 1000 target 20ms tupdate 30ms bytemode
$ tc qdisc show dev "$DEV"
qdisc pie 8001: root refcnt 2 limit 1000p target 20.0ms tupdate 32.0ms alpha 2 beta 20 bytemode

The displayed update interval may be normalised by the implementation, as in the manpage's example. Verify the actual output instead of assuming that the requested text is reproduced exactly.

Use dq_rate_estimator when you want PIE to calculate delay from a dequeue-rate estimate:

$ sudo tc qdisc replace dev "$DEV" root pie dq_rate_estimator
$ sudo tc -s qdisc show dev "$DEV"
qdisc pie 8001: root refcnt 2 limit 1000p target 15.0ms tupdate 15.0ms alpha 2 beta 20
 ... prob 0.000092 delay 22200us avg_dq_rate 12145996

The example output is illustrative: counters, handle and rate are expected to change. Do not combine options just to make the command look comprehensive. Change one behaviour at a time and observe the resulting statistics.

7. Remove PIE or restore the previous qdisc

Do this when the test ends, or immediately if the link behaves badly. Deleting the root qdisc lets the kernel use its normal device setup, but it does not restore a custom qdisc you replaced:

$ sudo tc qdisc del dev "$DEV" root
$ tc qdisc show dev "$DEV"
qdisc noqueue 0: root refcnt 2

The exact post-delete qdisc depends on the device. If the checkpoint showed a managed qdisc such as fq_codel, restore it with the configuration used by your host's network manager rather than guessing. A manually restored qdisc can be overwritten on link restart, reboot or network-manager reload.

For a persistent setup, put the reviewed command in the network configuration system that owns the interface, then test restart and rollback separately. The tc commands above are runtime changes and do not create a persistent configuration file.