Shape Fair Queues with tc-fq_pie Without Losing Your Undo Path

You will attach Linux's FQ-PIE queueing discipline to an interface, inspect its live counters, and remove it cleanly when the test is over. FQ-PIE combines per-flow queuing with the PIE active queue management algorithm. 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. Interface names, queue statistics and traffic effects will differ on your host.

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 ]

The help request is harmless. A real change to a root qdisc is not: it changes packet scheduling for the interface and can disturb connectivity. Keep a console or out-of-band route to the machine while testing.

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 in this guide removes the temporary root qdisc; it does not recreate an earlier custom configuration. If this is 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

The command uses the documented defaults explicitly for the two settings most useful to recognise. limit caps the queue at 10240 packets, flows creates 1024 hash buckets, and target tells PIE to aim for a 15 ms queue delay. FQ-PIE hashes the source and destination addresses, ports and IP protocol into buckets, so hash collisions are possible.

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

Checkpoint: ask tc what is now attached:

# 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 displays 16.0 ms in its sample output. Treat the live output as authoritative for the host you are operating.

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 includes packets discarded by the queue or its limit, while overmemory reports memory-limit events. A non-zero backlog means packets are currently queued, not necessarily that the qdisc is broken.

5. Choose ECN and memory controls deliberately

ECN marking is off unless you enable it. 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 have its intended effect. bytemode is also off by default; enabling it scales drop probability with packet size:

# tc qdisc replace dev eth0 root fq_pie ecn bytemode

These replace commands are state-changing and can reset the qdisc's counters and queues. Use them only when replacing the current root qdisc is acceptable. Verify each result with tc -s qdisc show dev eth0.

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

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

# 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 infer that this option improves every workload. Compare the counters and observed latency for your traffic, and remember that replacing the qdisc changes the live path.

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

This is a service-disrupting action and may restore a kernel default rather than your previous custom qdisc. If the interface belongs to a network manager or provisioning system, restore configuration through that system instead of leaving an unmanaged change.