1SHOREWALL-TCCLASSES(5)        Configuration Files       SHOREWALL-TCCLASSES(5)
2
3
4

NAME

6       tcclasses - Shorewall file to define HTB and HFSC classes
7

SYNOPSIS

9       /etc/shorewall[6]/tcclasses
10

DESCRIPTION

12       A note on the rate/bandwidth definitions used in this file:
13
14       •   don't use a space between the integer value and the unit: 30kbit is
15           valid while 30 kbit is NOT.
16
17       •   you can use one of the following units:
18
19           kpbs
20               Kilobytes per second.
21
22           mbps
23               Megabytes per second.
24
25           kbit
26               Kilobits per second.
27
28           mbit
29               Megabits per second.
30
31           bps or number
32               Bytes per second.
33
34       •   if you want the values to be calculated for you depending on the
35           output bandwidth setting defined for an interface in tcdevices, you
36           can use expressions like the following:
37
38           full/3
39               causes the bandwidth to be calculated as 1/3 of the full
40               outgoing speed that is defined.
41
42           full*9/10
43               will set this bandwidth to 9/10 of the full bandwidth
44
45           Note that in a sub-class (a class that has a specified parent
46           class), full refers to the RATE or CEIL of the parent class rather
47           than to the OUT-BANDWIDTH of the device.
48
49           DO NOT add a unit to the rate if it is calculated !
50
51       The columns in the file are as follows.
52
53       INTERFACE - interface[[:parent]:class]
54           Name of interface.
55
56           You may specify the interface number rather than the interface
57           name. If the classify option is given for the interface in
58           shorewall-tcdevices[1](5), then you must also specify an interface
59           class (an integer that must be unique within classes associated
60           with this interface). If the classify option is not given, you may
61           still specify a class or you may have Shorewall generate a class
62           number from the MARK value. Interface numbers and class numbers are
63           always assumed to be specified in hex and class number 1 is
64           reserved as the root class of the queuing discipline.
65
66           You may NOT specify wildcards here, e.g. if you have multiple ppp
67           interfaces, you need to put them all in here!
68
69           Please note that you can only use interface names in here that have
70           a bandwidth defined in the shorewall-tcdevices[1](5) file.
71
72           Normally, all classes defined here are sub-classes of a root class
73           that is implicitly defined from the entry in
74           shorewall-tcdevices[1](5). You can establish a class hierarchy by
75           specifying a parent class -- the number of a class that you have
76           previously defined. The sub-class may borrow unused bandwidth from
77           its parent.
78
79       MARK - {-|value[:priority]}
80           The mark value which is an integer in the range 1-255. You set mark
81           values in the shorewall-mangle[2](5) file, marking the traffic you
82           want to fit in the classes defined in here. You can use the same
83           marks for different interfaces.
84
85           The priority, if specified, is an integer in the range 1-65535 and
86           determines the relative order in which the tc mark classification
87           filter for this class is to be applied to packets being sent on the
88           interface. Filters are applied in ascending numerical order. If not
89           supplied, the value is derived from the class priority (PRIORITY
90           column value below): (class priority << 8) | 20.
91
92       RATE - {-|rate[:dmax[:umax]]}
93           The minimum bandwidth this class should get, when the traffic load
94           rises. If the sum of the rates in this column exceeds the
95           INTERFACE's OUT-BANDWIDTH, then the OUT-BANDWIDTH limit may not be
96           honored. Similarly, if the sum of the rates of sub-classes of a
97           class exceed the CEIL of the parent class, things don't work well.
98
99           When using the HFSC queuing discipline, this column specify the
100           real-time (RT) service curve. leaf classes may specify dmax, the
101           maximum delay in milliseconds that the first queued packet for this
102           class should experience. May be expressed as an integer, optionally
103           followed by 'ms' with no intervening white-space (e.g., 10ms).
104
105           HFSC leaf classes may also specify umax, the largest packet
106           expected in this class. May be expressed as an integer. The unit of
107           measure is bytes and the integer may be optionally followed by 'b'
108           with no intervening white-space (e.g., 800b).  umax may only be
109           given if dmax is also given.
110
111           Beginning with Shorewall 4.5.6, HFSC classes may omit this column
112           (e.g, '-' in the column), provided that an lsrate is specified (see
113           CEIL below). These rates are used to arbitrate between classes of
114           the same priority.
115
116       CEIL - [lsrate:]rate
117           The maximum bandwidth this class is allowed to use when the link is
118           idle. Useful if you have traffic which can get full speed when more
119           needed services (e.g. ssh) are not used.
120
121           You can use the value full in here for setting the maximum
122           bandwidth to the RATE of the parent class, or the OUT-BANDWIDTH of
123           the device if there is no parent class.
124
125           Beginning with Shorewall 4.5.6, you can also specify an lsrate
126           (link sharing rate).
127
128       PRIORITY - priority
129           For HTB: The priority in which classes will be serviced by the
130           packet shaping scheduler and also the priority in which bandwidth
131           in excess of the rate will be given to each class.
132
133           Higher priority classes will experience less delay since they are
134           serviced first. Priority values are serviced in ascending order
135           (e.g. 0 is higher priority than 1).
136
137           Classes may be set to the same priority, in which case they will be
138           serviced as equals.  For both HTB and HFSC, the priority is used to
139           calculate the priority of following Shorewall-generated
140           classification filters that refer to the class:
141
142           •   Packet MARK
143
144tcp-ack and the tos options (see below)
145
146           The rules for classes with lower numeric priorities will appear
147           before those with higher numeric priorities.
148
149           Beginning with Shorewall 4.5.8, the PRIORITY may be omitted from an
150           HFSC class if you do not use the MARK column or the tcp-ack or tos
151           options. If you use any of those features and omit the PRIORITY,
152           then you must specify a priority along with the MARK or option.
153
154       OPTIONS (Optional) - [option[,option]...]
155           A comma-separated list of options including the following:
156
157           default
158               This is the default class for that interface where all traffic
159               should go, that is not classified otherwise.
160
161
162                   Note
163                   You must define default for exactly one class per
164                   interface.
165
166           tos=0xvalue[/0xmask][:priority] (mask defaults to 0xff)
167               This lets you define a classifier for the given value/mask
168               combination of the IP packet's TOS/Precedence/DiffSrv octet
169               (aka the TOS byte).
170
171               Beginning with Shorewall 4.5.8, the value/mask may be followed
172               by a colon (":") and a priority. This priority determines the
173               order in which filter rules are processed during packet
174               classification. If not specified, the value (class priority <<
175               8) | 15) is used.
176
177           tos-tosname[:priority]
178               Aliases for the following TOS octet value and mask encodings.
179               TOS encodings of the "TOS byte" have been deprecated in favor
180               of diffserve classes, but programs like ssh, rlogin, and ftp
181               still use them.
182
183               Beginning with Shorewall 4.5.8, the tos-name may be followed by
184               a colon (":") and a priority. This priority determines the
185               order in which filter rules are processed during packet
186               classification. If not specified, the value (class priority <<
187               8) | 15) is used.
188
189                           tos-minimize-delay       0x10/0x10
190                           tos-maximize-throughput  0x08/0x08
191                           tos-maximize-reliability 0x04/0x04
192                           tos-minimize-cost        0x02/0x02
193                           tos-normal-service       0x00/0x1e
194
195                   Note
196                   Each of these options is only valid for ONE class per
197                   interface.
198
199           tcp-ack[:priority]
200               If defined, causes a tc filter to be created that puts all tcp
201               ack packets on that interface that have a size of <=64 Bytes to
202               go in this class. This is useful for speeding up downloads.
203               Please note that the size of the ack packets is limited to 64
204               bytes because we want only packets WITHOUT payload to match.
205
206               Beginning with Shorewall 4.5.8, the tcp-ack may be followed by
207               a colon (":") and a priority. This priority determines the
208               order in which filter rules are processed during packet
209               classification. If not specified, the value (class priority <<
210               8) | 10) is used.
211
212                   Note
213                   This option is only valid for ONE class per interface.
214
215           occurs=number
216               Typically used with an IPMARK entry in tcrules. Causes the rule
217               to be replicated for a total of number rules. Each rule has a
218               successively class number and mark value.
219
220               When 'occurs' is used:
221
222               •   The associated device may not have the 'classify' option.
223
224               •   The class may not be the default class.
225
226               •   The class may not have any 'tos=' options (including
227                   'tcp-ack').
228
229               •   The class should not specify a MARK value. If one is
230                   specified, it will be ignored with a warning message.
231
232               The 'RATE' and 'CEIL' parameters apply to each instance of the
233               class. So the total RATE represented by an entry with 'occurs'
234               will be the listed RATE multiplied by number. For additional
235               information, see shorewall-tcrules[3] (5).
236
237           flow=keys
238               Shorewall attaches an SFQ queuing discipline to each leaf HTB
239               class. SFQ ensures that each flow gets equal access to the
240               interface. The default definition of a flow corresponds roughly
241               to a Netfilter connection. So if one internal system is running
242               BitTorrent, for example, it can have lots of 'flows' and can
243               thus take up a larger share of the bandwidth than a system
244               having only a single active connection. The flow classifier
245               (module cls_flow) works around this by letting you define what
246               a 'flow' is. The classifier must be used carefully or it can
247               block off all traffic on an interface! The flow option can be
248               specified for an HTB leaf class (one that has no sub-classes).
249               We recommend that you use the following:
250                   Shaping internet-bound traffic:
251                                     flow=nfct-src
252                   Shaping traffic bound for your local net:
253                                     flow=dst
254               These will cause a 'flow' to consists of the traffic to/from
255               each internal system.
256
257               When more than one key is give, they must be enclosed in
258               parenthesis and separated by commas.
259
260               To see a list of the possible flow keys, run this command: tc
261               filter add flow help Those that begin with "nfct-" are
262               Netfilter connection tracking fields. As shown above, we
263               recommend flow=nfct-src; that means that we want to use the
264               source IP address before NAT as the key.
265
266           pfifo
267               When specified for a leaf class, the pfifo queuing discipline
268               is applied to the class rather than the sfq queuing discipline.
269
270           limit=number
271               Added in Shorewall 4.4.3. When specified for a leaf class,
272               determines the maximum number of packets that may be queued
273               within the class. The number must be > 2 and <=128. If not
274               specified, the value 127 is assumed.
275
276           red=(redoption=value, ...)
277               Added in Shorewall 4.5.6. When specified on a leaf class,
278               causes the class to use the RED (Random Early Detection)
279               queuing discipline rather than SFQ. See tc-red (8) for
280               additional information.
281
282               Allowable redoptions are:
283
284               min min
285                   Average queue size at which marking becomes a possibility.
286
287               max max
288                   At this average queue size, the marking probability is
289                   maximal. Must be at least twice min to prevent synchronous
290                   retransmits, higher for low min.
291
292               probability probability
293                   Maximum probability for marking, specified as a floating
294                   point number from 0.0 to 1.0. Suggested values are 0.01 or
295                   0.02 (1 or 2%, respectively).
296
297               limit limit
298                   Hard limit on the real (not average) queue size in bytes.
299                   Further packets are dropped. Should be set higher than
300                   max+burst. It is advised to set this a few times higher
301                   than max. Shorewall requires that limit be at least twice
302                   min.
303
304               burst burst
305                   Used for determining how fast the average queue size is
306                   influenced by the real queue size. Larger values make the
307                   calculation more sluggish, allowing longer bursts of
308                   traffic before marking starts. Real life experiments
309                   support the following guide‐line: (min+min+max)/(3*avpkt).
310
311               avpkt avpkt
312                   Optional. Specified in bytes. Used with burst to determine
313                   the time constant for average queue size calculations. 1000
314                   is a good value and is the Shorewall default.
315
316               bandwidth bandwidth
317                   Optional. This rate is used for calculating the average
318                   queue size after some idle time. Should be set to the
319                   bandwidth of your interface. Does not mean that RED will
320                   shape for you!
321
322               ecn
323                   RED can either 'mark' or 'drop'. Explicit Congestion
324                   Notification allows RED to notify remote hosts that their
325                   rate exceeds the amount of bandwidth available. Non-ECN
326                   capable hosts can only be notified by dropping a packet. If
327                   this parameter is specified, packets which indicate that
328                   their hosts honor ECN will only be marked and not dropped,
329                   unless the queue size hits limit bytes. Recommended.
330
331           fq_codel[=(codeloption=value, ...)]
332               Added in Shorewall 4.5.12. When specified for a leaf class,
333               causes the class to use the FQ_CODEL (Fair-queuing Controlled
334               Delay) queuing discipline rather than SFQ. See tc-fq_codel (8)
335               for additional information.
336
337               Allowable codeloptions are:
338
339               limit
340                   hard limit on the real queue size. When this limit is
341                   reached, incoming packets are dropped. If the value is
342                   lowered, packets are dropped so that the new limit is met.
343                   Default is 1000 packets.
344
345               flows
346                   is the number of flows into which the incoming packets are
347                   classified. Due to the stochastic nature of hashing,
348                   multiple flows may end up being hashed into the same slot.
349                   Newer flows have priority over older ones. This parameter
350                   can be set only at load time since memory has to be
351                   allocated for the hash table. Default value is 1024.
352
353               target
354                   is the acceptable minimum standing/persistent queue delay.
355                   This minimum delay is identified by tracking the local
356                   minimum queue delay that packets experience. Default and
357                   recommended value is 5ms.
358
359               interval
360                   is used to ensure that the measured minimum delay does not
361                   become too stale. The minimum delay must be experienced in
362                   the last epoch of length interval. It should be set on the
363                   order of the worst-case RTT through the bottleneck to give
364                   endpoints sufficient time to react. Default value is 100ms.
365
366               quantum
367                   is the number of bytes used as 'deficit' in the fair
368                   queuing algorithm. Default is set to 1514 bytes which
369                   corresponds to the Ethernet MTU plus the hardware header
370                   length of 14 bytes.
371
372               ecn | noecn
373                   can be used to mark packets instead of dropping them. If
374                   ecn has been enabled, noecn can be used to turn it off and
375                   vice-versa. By default, ecn is enabled.
376

EXAMPLES

378       Example 1:
379           Suppose you are using PPP over Ethernet (DSL) and ppp0 is the
380           interface for this. You have 4 classes here, the first you can use
381           for voice over IP traffic, the second interactive traffic (e.g.
382           ssh/telnet but not scp), the third will be for all unclassified
383           traffic, and the forth is for low priority traffic (e.g.
384           peer-to-peer).
385
386           The voice traffic in the first class will be guaranteed a minimum
387           of 100kbps and always be serviced first (because of the low
388           priority number, giving less delay) and will be granted excess
389           bandwidth (up to 180kbps, the class ceiling) first, before any
390           other traffic. A single VoIP stream, depending upon codecs, after
391           encapsulation, can take up to 80kbps on a PPPoE/DSL link, so we pad
392           a little bit just in case. (TOS byte values 0xb8 and 0x68 are
393           DiffServ classes EF and AFF3-1 respectively and are often used by
394           VOIP devices).
395
396           Interactive traffic (tos-minimum-delay) and TCP acks (and ICMP echo
397           traffic if you use the example in tcrules) and any packet with a
398           mark of 2 will be guaranteed 1/4 of the link bandwidth, and may
399           extend up to full speed of the link.
400
401           Unclassified traffic and packets marked as 3 will be guaranteed
402           1/4th of the link bandwidth, and may extend to the full speed of
403           the link.
404
405           Packets marked with 4 will be treated as low priority packets. (The
406           tcrules example marks p2p traffic as such.) If the link is
407           congested, they're only guaranteed 1/8th of the speed, and even if
408           the link is empty, can only expand to 80% of link bandwidth just as
409           a precaution in case there are upstream queues we didn't account
410           for. This is the last class to get additional bandwidth and the
411           last to get serviced by the scheduler because of the low priority.
412
413                       #INTERFACE  MARK  RATE    CEIL      PRIORITY    OPTIONS
414                       ppp0        1     100kbit 180kbit   1           tos=0x68/0xfc,tos=0xb8/0xfc
415                       ppp0        2     full/4  full      2           tcp-ack,tos-minimize-delay
416                       ppp0        3     full/4  full      3           default
417                       ppp0        4     full/8  full*8/10 4
418

FILES

420       /etc/shorewall/tcclasses
421
422       /etc/shorewall6/tcclasses
423

SEE ALSO

425       https://shorewall.org/traffic_shaping.htm[4]
426
427       https://shorewall.org/configuration_file_basics.htm#Pairs[5]
428
429       tc-hfsc(7)
430
431       tc-red(8)
432
433       shorewall(8)
434

NOTES

436        1. shorewall-tcdevices
437           https://shorewall.org/manpages/shorewall-tcdevices.html
438
439        2. shorewall-mangle
440           https://shorewall.org/manpages/shorewall-mangle.html
441
442        3. shorewall-tcrules
443           https://shorewall.org/manpages/shorewall-tcrules.html
444
445        4. https://shorewall.org/traffic_shaping.htm
446           https://shorewall.org/traffic_shaping.htm
447
448        5. https://shorewall.org/configuration_file_basics.htm#Pairs
449           https://shorewall.org/configuration_file_basics.htm#Pairs
450
451
452
453Configuration Files               09/24/2020            SHOREWALL-TCCLASSES(5)
Impressum