DUALPI2(8)

💖 DUALPI2 💖

okay bestie, so this one is dualpi2 from section 8 of the Linux manual pages — the big-kid sysadmin section — and it's literally one of the coolest queue disciplines in the whole tc lineup. buckle up. 🎀

---

✨ NAME ✨

DUALPI2 — Dual Queue Proportional Integral Controller AQM — Improved with a square 💅

---

🌸 SYNOPSIS 🌸

tc qdisc ... dualpi2
        [ limit PACKETS ]
        [ memlimit BYTES ]
        [ coupling_factor NUMBER ]
        [ step_thresh TIME|PACKETS ]
        [ min_qlen_step PACKETS ]
        [ drop_on_overload | overflow ]
        [ drop_enqueue | drop_dequeue ]
        [ l4s_ect | any_ect ]
        [ classic_protection PERCENTAGE ]
        [ max_rtt TIME  [ typical_rtt TIME ]]
        [ target TIME ]
        [ tupdate TIME ]
        [ alpha float ]
        [ beta float ]
        [ split_gso | no_split_gso ]

---

🦋 DESCRIPTION 🦋

So, DUALPI2 AQM is a combo meal: it's the DUALQ Coupled-AQM glued onto a PI2 base-AQM. And PI2 itself? It's both an extension and a simplification of the PIE AQM (iykyk). PI2 makes a whole bunch of PIE heuristics just... unnecessary, while still being able to control scalable congestion controls like TCP-Prague. And with PI2, both Reno/Cubic can run in parallel with Prague, maintaining window fairness. 🫶

DUALQ is what gives you the latency separation between the low-latency Prague flows and the Reno/Cubic flows that need a bigger queue.

The main design goals, no cap:

• L4S — Low Loss, Low Latency and Scalable congestion control support ✨
• DualQ option to separate the L4S traffic in a low latency queue (L-queue), without harming the remaining traffic scheduled in the classic queue (C-queue), thanks to congestion-coupling
• Configurable overload strategies
• Use of sojourn time to reliably estimate queue delay
• Simple implementation
• Guaranteed stability and fast responsiveness

The detailed PI2 parameters — alpha, beta, and tupdate — of DualPI2 are genuinely hard to get right, and they typically give bad results if you just try them or guess at them. 😭 These parameters need to be calculated into a coherent set with a typical objective in mind. DualPI2 ships with a set of default parameters usable for the general Internet, where the max RTT is around 100ms and the typical RTT is around 15ms.

It is highly recommended to use max_rtt and typical_rtt (or target) helper parameters if your deployment deviates from those objectives (e.g. in a data center). These helpers are used to provide the theoretically optimal PI2 parameters (alpha, beta, and tupdate) for those objectives, and they can be used as a basis for further finetuning, experimentation, and testing if desired. 💅

---

👑 ALGORITHM 👑

DUALPI2 is designed to provide low loss and low latency to L4S traffic, without harming classic traffic. Every update interval, a new internal base probability is calculated based on queue delay. The base probability gets updated with a delta based on the difference between the current queue delay and the target delay, plus the queue growth compared with the queuing delay during the previous tupdate interval.

The integral gain factor alpha is used to correct slowly enough any persistent standing queue error to the user-specified target delay, while the proportional gain factor beta is used to quickly compensate for queue changes (growth or shrink).

The updated base probability is used as input to decide to mark and drop packets. DUALPI2 scales the calculated probability for each of the two queues accordingly. For the L-queue, the probability is multiplied by a coupling_factor, while for the C-queue, it is squared to compensate the squareroot rate equation of Reno/Cubic. The ECT identifier (l4s_ect|any_ect) is what classifies traffic into the respective queues.

If DUALPI2 AQM has detected overload (when excessive non-responsive traffic is sent), it can signal congestion solely using drop, irrespective of the ECN field — or alternatively limit the drop probability and let the queue grow and eventually overflow (like tail-drop). 🙈

Additional details can be found in the RFC cited below.

---

💜 PARAMETERS 💜

• limit PACKETS — Limit the number of packets that can be enqueued. Incoming packets will be dropped once this limit is reached. This limit is common for the L-queue and C-queue. Defaults to 10000 packets. That's about 125ms delay on a 1Gbps link, bestie. 😌
• memlimit BYTES — Limit the total amount of memory that can be used. Incoming packets will be dropped once this memlimit is reached. This memlimit is common for the L-queue and C-queue. Defaults to 10000 * interface MTU bytes.
• coupling_factor NUMBER — Set the coupling rate factor between Classic and L4S. Defaults to 2.
• l4s_ect|any_ect — Configures the ECT classifier. Packets whose ECT codepoint matches this are sent to the L-queue, where they receive a scalable marking. Defaults to l4s_ect, i.e. the L4S identifier ECT(1). Setting this to any_ect causes all packets whose ECN field is not zero to be sent to the L-queue. This makes it backward compatible with, e.g., DCTCP.

⚠️ Note: DCTCP should only be used for intra-DC traffic with very low RTTs and AQM delay targets bigger than those RTTs, separated from Internet traffic (also if Prague compliant CC), as it does not support all Prague requirements that make sure that a congestion control can work well with the range of RTTs on the Internet. 💀

• step_thresh TIME | PACKETS — Set the step threshold for the L-queue. This will cause packets with a sojourn time exceeding the threshold to always be marked. This value can either be specified using time units (i.e. us, ms, s), or in packets (p, pkt, packet(s)). A value without units is assumed to be in time (us). If defining the step in packets, be sure to disable GRO on the ingress interfaces. Defaults to 1ms. 🎀
• min_qlen_step PACKETS — Incoming packets enqueued to the L-queue may apply the step threshold when the queue length of the L-queue exceeds this value. Default to 0 packets. This means that every enqueued packet to the L-queue with a sojourn time exceeding the step threshold will be marked. ✨
• drop_on_overload | overflow — Control the overload strategy. drop_on_overload preserves the delay in the L-queue by dropping in both queues on overload. overflow sacrifices delay to avoid losses, eventually resulting in a taildrop behavior once the limit is reached. Defaults to drop_on_overload.
• drop_enqueue | drop_dequeue — Decide when packets are PI-based dropped or marked. The step_thresh based L4S marking is always at dequeue. Defaults to drop_dequeue.
• classic_protection PERCENTAGE — Protects the C-queue from unresponsive traffic in the L-queue. This bounds the maximal scheduling delay in the C-queue to be (100 - PERCENTAGE) times greater than the one in the L-queue. Defaults to 10. 🫶
• typical_rtt TIME and max_rtt TIME — Specify the maximum round trip time (RTT) and/or the typical RTT of the traffic that will be controlled by DUALPI2. These values are specified using time units (i.e. us, ms, s). A value without units is assumed to be in us.

If either max_rtt or typical_rtt is not specified, the missing value will be computed from the following relationship:

max_rtt = typical_rtt * 6

If any of these parameters is given, it will be used to automatically compute suitable values for alpha, beta, target, and tupdate, according to the relationship from appendix A.1 in the IETF RFC cited below, to achieve a stable control. Consequently, those derived values will override their eventual user-provided ones. 😳

The default range of operation for the qdisc uses max_rtt = 100ms and typical_rtt = 15ms, which is suited to controlling Internet traffic.

• target TIME — Set the expected queue delay. Defaults to 15 ms. A value without units is assumed to be in us.
• tupdate TIME — Set the frequency at which the system drop probability is calculated. Defaults to 16 ms. A value without units is assumed to be in microseconds. This should be less than one-third of the maximum RTT supported.
• alpha float and beta float — Set alpha and beta, the integral and proportional gain factors in Hz for the PI controller. These can be calculated based on control theory. Defaults are 0.16 and 3.2 Hz, which provide stable control for RTT's up to 100ms with tupdate of 16ms. Be aware, unlike with PIE, these are the real unscaled gain factors. If not provided, they will be automatically derived from typical_rtt and max_rtt, if one of them or both are provided. 👑
• split_gso | no_split_gso — Decide how to handle aggregated packets. Either treat the aggregate as a single packet (thus all share fate with respect to marks and drops) with no_split_gso, trading some tail latency for CPU usage — or treat each packet individually (i.e. split them) with split_gso to enable fine-grained marking/dropping of packets to control queueing latencies. Defaults to split_gso. 💅

---

🍓 EXAMPLES 🍓

Setting DUALPI2 for the Internet with default parameters:

# sudo tc qdisc add dev eth0 root dualpi2

Setting DUALPI2 for datacenter with legacy DCTCP using ECT(0):

# sudo tc qdisc add dev eth0 root dualpi2 any_ect

---

🧚 FILTERS 🧚

This qdisc can be used in conjunction with tc-filters. More precisely, it will honor filters "stealing packets", as well as accept other classification schemes. ✨

Packets whose priority/classid are set to

• 1 will be enqueued in the L-queue, alongside L4S traffic, and thus subject to the increased marking probability (or drops if they are marked not-ECT).

Packets whose priority/classid are set to

• 2 will also be enqueued in the L-queue, but will never be dropped if they are not-ECT (unless the qdisc is full and thus resorts to taildrop).

Finally, all the other classid/priority map to the C-queue. 💜

---

🌈 SEE ALSO 🌈

tc(8), tc-pie(8)

---

⭐ SOURCES ⭐

• IETF RFC9332: https://datatracker.ietf.org/doc/html/rfc9332
• CoNEXT '16 Proceedings of the 12th International on Conference on emerging Networking Experiments and Technologies: "PI2: A Linearized AQM for both Classic and Scalable TCP"

---

🎀 AUTHORS 🎀

DUALPI2 was implemented by Koen De Schepper, Olga Albisser, Henrik Steen, Olivier Tilmans, and Chia-Yu Chang — who are also the authors of this man page. 💖 Please report bugs and corrections to the Linux networking development mailing list at <netdev@vger.kernel.org>.

---

and that's the whole thing, bestie 🦋 this page came out of the iproute2 crew, dated 29 Oct 2024, and honestly? iconic. go forth and configure your queues, you're doing amazing 💅✨