Shape Fair Queues with tc fq_pie

fq_pie pairs per-flow fair queuing with the PIE algorithm, aiming for a delay target instead of an ever-growing queue. This guide attaches it to an interface, walks through its live counters, and removes it cleanly when the test is over. Allow about fifteen minutes, plus time to observe traffic. You need the iproute2 package and elevated privileges for changes.

This guide uses tc from iproute2 6.1.0, package version 6.1.0-1ubuntu6.4. The installed help confirms the option names shown here; your interface names, queue statistics and traffic effects will differ.

1. Check the interface and command

Choose the interface carrying the traffic you want to test. This ordinary command lists interfaces without changing anything:

$ ip -br link
lo               UNKNOWN        00:00:00:00:00:00
eth0             UP             02:00:00:00:00:00

Replace eth0 below with the real interface. Check the parser before making a change:

$ tc qdisc add dev eth0 root fq_pie help
Usage: ... fq_pie [ limit PACKETS ] [ flows NUMBER ]
                  [ target TIME ] [ tupdate TIME ]
                  [ alpha NUMBER ] [ beta NUMBER ]
                  [ quantum BYTES ] [ memory_limit BYTES ]
                  [ ecn_prob PERCENTAGE ] [ [no]ecn ]
                  [ [no]bytemode ] [ [no_]dq_rate_estimator ]

2. Record the current root qdisc

Save the current state before changing it. This is a read-only command:

$ tc -s qdisc show dev eth0
qdisc mq 0: root
...

Your output may show another qdisc, or a different root layout. The recovery command later in this guide removes the temporary root qdisc; it does not recreate an earlier custom configuration. On a production interface, record the existing configuration and its owner before continuing.

3. Add a conservative FQ-PIE test

Run this as root, or prefix it with sudo:

# tc qdisc add dev eth0 root fq_pie limit 10240 flows 1024 target 15ms

• limit caps the queue at 10240 packets.
• flows creates 1024 hash buckets. FQ-PIE hashes source and destination addresses, ports and IP protocol into them, so collisions are possible.
• target tells PIE to aim for a 15 ms queue delay.

If the interface already has a root qdisc, add can fail rather than silently replace it. Stop there and decide whether the existing configuration may be changed; do not force a replacement just to make the command succeed.

# tc qdisc show dev eth0
qdisc fq_pie 8001: root refcnt 2 limit 10240p flows 1024 target 15.0ms tupdate 16.0ms alpha 2 beta 20 quantum 1514b memory_limit 32Mb ecn_prob 10

The handle and displayed timer precision are implementation output. The manual describes a 15 ms default for tupdate; this installed version shows 16.0 ms in its sample output. Treat the live output as authoritative for the host you are actually on.

4. Observe counters while traffic runs

Use statistics to check that the qdisc is receiving packets:

# tc -s qdisc show dev eth0
qdisc fq_pie 8001: root refcnt 2 limit 10240p flows 1024 target 15.0ms tupdate 16.0ms alpha 2 beta 20 quantum 1514b memory_limit 32Mb ecn_prob 10
 Sent 159173586 bytes 105261 pkt (dropped 24, overlimits 0 requeues 0)
 backlog 75700b 50p requeues 0
  pkts_in 105311 overlimit 0 overmemory 0 dropped 24 ecn_mark 0
  new_flow_count 7332 new_flows_len 0 old_flows_len 4 memory_used 108800

Counts are cumulative for this qdisc instance. pkts_in is input traffic; dropped covers packets discarded by the queue or its limit, while overmemory reports memory-limit events specifically. A non-zero backlog just means packets are currently queued, not that the qdisc is broken.

5. Choose ECN and memory controls deliberately

ECN marking is off unless you turn it on. This example enables ECN and keeps the documented 32 MiB memory limit:

# tc qdisc replace dev eth0 root fq_pie memory_limit 32Mb ecn ecn_prob 10

ecn_prob 10 makes packets eligible for marking below a 10 percent drop probability, but the manual requires ecn to be enabled for that setting to actually do anything. bytemode is also off by default; turning it on scales drop probability with packet size:

# tc qdisc replace dev eth0 root fq_pie ecn bytemode

6. Try the dequeue-rate estimator only with a reason

By default, FQ-PIE calculates queue delay from timestamps. Add dq_rate_estimator when you specifically want delay calculated using Little's Law instead:

# tc qdisc replace dev eth0 root fq_pie dq_rate_estimator
# tc -s qdisc show dev eth0
qdisc fq_pie 8001: root refcnt 2 limit 10240p flows 1024 target 15.0ms tupdate 16.0ms alpha 2 beta 20 quantum 1514b memory_limit 32Mb ecn_prob 10 dq_rate_estimator

Do not assume this option improves every workload. Compare the counters and observed latency for your own traffic, and remember that replacing the qdisc changes the live path each time.

7. Remove the test configuration

When finished, remove the FQ-PIE root qdisc only if it is the one you installed:

# tc qdisc show dev eth0
# tc qdisc del dev eth0 root
# tc qdisc show dev eth0