Debian Codegraph @

upstream/debian-unstable/man8/tc-dualpi2.8

raw
1 .TH DUALPI2 8 "29 Oct 2024" "iproute2" "Linux"
2
3 .SH NAME
4 DUALPI2 \- Dual Queue Proportional Integral Controller AQM - Improved with a square
5 .SH SYNOPSIS
6 .sp
7 .ad l
8 .in +8
9 .ti -8
10 .BR tc " " qdisc " ... " dualpi2
11 .br
12 .RB "[ " limit
13 .IR PACKETS " ]"
14 .br
15 .RB "[ " memlimit
16 .IR BYTES " ]"
17 .br
18 .RB "[ " coupling_factor
19 .IR NUMBER " ]"
20 .br
21 .RB "[ " step_thresh
22 .IR TIME | PACKETS " ]"
23 .br
24 .RB "[ " min_qlen_step
25 .IR PACKETS " ]"
26 .br
27 .RB "[ " drop_on_overload " | " overflow " ]"
28 .br
29 .RB "[ " drop_enqueue " | " drop_dequeue " ]"
30 .br
31 .RB "[ " l4s_ect " | " any_ect " ]"
32 .br
33 .RB "[ " classic_protection
34 .IR PERCENTAGE " ] "
35 .br
36 .RB "[ " max_rtt
37 .IR TIME
38 .RB " [ " typical_rtt
39 .IR TIME " ]] "
40 .br
41 .RB "[ " target
42 .IR TIME " ]"
43 .br
44 .RB "[ " tupdate
45 .IR TIME " ]"
46 .br
47 .RB "[ " alpha
48 .IR float " ]"
49 .br
50 .RB "[ " beta
51 .IR float " ] "
52 .br
53 .RB "[ " split_gso " | " no_split_gso " ]"
54
55 .SH DESCRIPTION
56 DUALPI2 AQM is a combination of the DUALQ Coupled-AQM with a PI2 base-AQM. The PI2 AQM (details can be found in the paper cited below) is in turn both an extension and a simplification of the PIE AQM. PI2 makes quite some PIE heuristics unnecessary, while being able to control scalable congestion controls like TCP-Prague. With PI2, both Reno/Cubic can be used in parallel with Prague, maintaining window fairness. DUALQ provides latency separation between low latency Prague flows and Reno/Cubic flows that need a bigger queue. The main design goals are:
57 .PD 0
58 .IP \(bu 4
59 L4S - Low Loss, Low Latency and Scalable congestion control support
60 .IP \(bu 4
61 DualQ option to separate the L4S traffic in a low latency queue (L-queue), without harming remaining traffic that is scheduled in classic queue (C-queue) due to congestion-coupling
62 .IP \(bu 4
63 Configurable overload strategies
64 .IP \(bu 4
65 Use of sojourn time to reliably estimate queue delay
66 .IP \(bu 4
67 Simple implementation
68 .IP \(bu 4
69 Guaranteed stability and fast responsiveness
70
71 .PP
72 The detailed PI2 parameters (alpha, beta, and tupdate) of DualPI2 are hard to get right and typically give bad results if just tried or guessed. These parameters need to be calculated to a coherent set with a typical objective in mind. DualPI2 has a set of default parameters that can be used for the general Internet, where the maximum RTT is around 100ms and the typical RTT is around 15ms. It is highly recommended to use
73 .I "" max_rtt
74 and
75 .I "" typical_rtt
76 (or target) helper parameters if your deployment is deviating from the above 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 that can be used as a basis for further finetuning, experimentation, and testing if desired.
77
78 .SH ALGORITHM
79 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 is updated with a delta based on the difference between the current queue delay and the
80 .I "" target
81 delay, and the queue growth compared with the queuing delay during the previous
82 .I "" tupdate
83 interval. The integral gain factor
84 .RB "" alpha
85 is used to correct slowly enough any persistent standing queue error to the user specified target delay, while the proportional gain factor
86 .RB "" beta
87 is used to quickly compensate for queue changes (growth or shrink).
88
89 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
90 .RB "" coupling_factor
91 , while for the C-queue, it is squared to compensate the squareroot rate equation of Reno/Cubic. The ECT identifier (
92 .RB "" l4s_ect | any_ect
93 ) is used to classify traffic into respective queues.
94
95 If DUALPI2 AQM has detected overload (when excessive non-responsive traffic is sent), it can signal congestion solely using
96 .RB "" drop
97 , irrespective of the ECN field, or alternatively limit the drop probability and let the queue grow and eventually
98 .RB "" overflow
99 (like tail-drop).
100
101 Additional details can be found in the RFC cited below.
102
103 .SH PARAMETERS
104 .TP
105 .BI limit " PACKETS"
106 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
107 .I 10000
108 packets. This is about 125ms delay on a 1Gbps link.
109 .PD
110 .TP
111 .BI memlimit " BYTES"
112 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
113 .I 10000 * interface MTU bytes.
114 .PD
115 .TP
116 .BI coupling_factor " NUMBER"
117 Set the coupling rate factor between Classic and L4S. Defaults to
118 .I 2
119 .PD
120 .TP
121 .BI l4s_ect | any_ect
122 Configures the ECT classifier. Packets whose ECT codepoint matches this are sent to the L-queue, where they receive a scalable marking. Defaults to
123 .I l4s_ect
124 , i.e., the L4S identifier ECT(1). Setting this to
125 .I any_ect
126 causes all packets whose ECN field is not zero to be sent to the L-queue. This enables it to be 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.
127 .PD
128 .TP
129 .BI step_thresh " TIME | PACKETS"
130 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
131 .I 1ms
132 .PD
133 .TP
134 .BI min_qlen_step " PACKETS"
135 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
136 .I 0
137 packets. This means that every enqueued packets to the L-queue with a sojourn time exceeds the step threshold will be marked.
138 .PD
139 .TP
140 .B drop_on_overload | overflow
141 Control the overload strategy.
142 .I drop_on_overload
143 preserves the delay in the L-queue by dropping in both queues on overload.
144 .I overflow
145 sacrifices delay to avoid losses, eventually resulting in a taildrop behavior once the
146 .I limit
147 is reached. Defaults to
148 .I drop_on_overload
149 .PD
150 .TP
151 .B drop_enqueue | drop_dequeue
152 Decide when packets are PI-based dropped or marked. The
153 .I step_thresh
154 based L4S marking is always at dequeue. Defaults to
155 .I drop_dequeue
156 .PD
157 .TP
158 .BI classic_protection " PERCENTAGE
159 Protects the C-queue from unresponsive traffic in the L-queue. This bounds the maximal scheduling delay in the C-queue to be
160 .I (100 - PERCENTAGE)
161 times greater than the one in the L-queue. Defaults to
162 .I 10
163 .TP
164 .BI typical_rtt " TIME"
165 .PD 0
166 .TP
167 .PD
168 .BI max_rtt " TIME"
169 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
170 .I max_rtt
171 or
172 .I typical_rtt
173 is not specified, the missing value will be computed from the following relationship:
174 .I max_rtt = typical_rtt * 6.
175 If any of these parameters is given, it will be used to automatically compute suitable values for
176 .I alpha, beta, target, and tupdate,
177 according to the relationship from the 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
178 .I max_rtt = 100ms
179 and
180 .I typical_rtt = 15ms
181 , which is suited to controlling Internet traffic.
182 .TP
183 .BI target " TIME"
184 Set the expected queue delay. Defaults to
185 .I 15
186 ms. A value without units is assumed to be in us.
187 .TP
188 .BI tupdate " TIME"
189 Set the frequency at which the system drop probability is calculated. Defaults to
190 .I 16
191 ms. A value without units is assumed to be in microseconds. This should be less than one-third of the maximum RTT supported.
192 .TP
193 .BI alpha " float"
194 .PD 0
195 .TP
196 .PD
197 .BI beta " float"
198 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
199 .I 0.16
200 and
201 .I 3.2
202 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
203 .I typical_rtt and max_rtt
204 , if one of them or both are provided.
205 .PD
206 .TP
207 .B split_gso | no_split_gso
208 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
209 .I no_split_gso
210 , trading some tail latency for CPU usage, or treat each packet individually (i.e., split them) with
211 .I split_gso
212 to enable fine-grained marking/dropping of packets to control queueing latencies. Defaults to
213 .I split_gso
214
215 .SH EXAMPLES
216 Setting DUALPI2 for the Internet with default parameters:
217 # sudo tc qdisc add dev eth0 root dualpi2
218
219 Setting DUALPI2 for datacenter with legacy DCTCP using ECT(0):
220 # sudo tc qdisc add dev eth0 root dualpi2 any_ect
221
222 .SH FILTERS
223 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.
224 .BR
225 .TP
226 Packets whose priority/classid are set to
227 .I 1
228 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).
229 .BR
230 .TP
231 Packets whose priority/classid are set to
232 .I 2
233 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).
234 .BR
235 .TP
236 Finally, all the other classid/priority map to the C-queue.
237
238 .SH SEE ALSO
239 .BR tc (8),
240 .BR tc-pie (8)
241
242 .SH SOURCES
243 .IP \(bu 4
244 IETF RFC9332 : https://datatracker.ietf.org/doc/html/rfc9332
245 .IP \(bu 4
246 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"
247
248 .SH AUTHORS
249 DUALPI2 was implemented by Koen De Schepper, Olga Albisser, Henrik Steen, Olivier Tilmans, and Chia-Yu Chang, also the authors of this man page. Please report bugs and corrections to the Linux networking development mailing list at <[email protected]>.