SHOREWALL-TCCLASSES(5)

✨ SHOREWALL-TCCLASSES ✨

okay bestie, welcome to shorewall-tcclasses, section 5 of the Shorewall config-file girlies 🎀 this is the file where you define your HTB and HFSC classes. it's giving traffic shaping main character energy, and honestly? we're obsessed 💅

---

📛 NAME

tcclasses — the Shorewall file that defines HTB and HFSC classes ✨

---

🦋 SYNOPSIS

/etc/shorewall[6]/tcclasses

---

💖 DESCRIPTION

first things first, bestie, a little note on the rate/bandwidth definitions used in this file, because the syntax WILL humble you if you're not paying attention 😭

• do not put a space between the integer value and the unit: 30kbit is valid while 30 kbit is NOT 🚫
• you can use one of the following units:
  • kpbs — Kilobytes per second.
  • mbps — Megabytes per second.
  • kbit — Kilobits per second.
  • mbit — Megabits per second.
  • bps or number — Bytes per second.
• if you want the values to be calculated for you depending on the output bandwidth setting defined for an interface in tcdevices, you can use expressions like the following:
  • full/3 — causes the bandwidth to be calculated as 1/3 of the full outgoing speed that is defined.
  • full*9/10 — will set this bandwidth to 9/10 of the full bandwidth.

🌸 Note that in a sub-class (a class that has a specified parent class), full refers to the RATE or CEIL of the parent class rather than to the OUT-BANDWIDTH of the device.

🔥 DO NOT add a unit to the rate if it is calculated !

The columns in the file are as follows, bestie. buckle up, there's a lot of them 💖

---

🧚 INTERFACE - interface[[:parent]:class]

Name of interface.

You may specify the interface number rather than the interface name. If the classify option is given for the interface in shorewall-tcdevices[1](5), then you must also specify an interface class (an integer that must be unique within classes associated with this interface). If the classify option is not given, you may still specify a class or you may have Shorewall generate a class number from the MARK value. Interface numbers and class numbers are always assumed to be specified in hex and class number 1 is reserved as the root class of the queuing discipline.

You may NOT specify wildcards here, e.g. if you have multiple ppp interfaces, you need to put them all in here! 😤

Please note that you can only use interface names in here that have a bandwidth defined in the shorewall-tcdevices[1](5) file.

Normally, all classes defined here are sub-classes of a root class that is implicitly defined from the entry in shorewall-tcdevices[1](5). You can establish a class hierarchy by specifying a parent class — the number of a class that you have previously defined. The sub-class may borrow unused bandwidth from its parent. slay, sharing is caring 🫶

---

🎀 MARK - {-|value[:priority]}

The mark value which is an integer in the range 1-255. You set mark values in the shorewall-mangle[2](5) file, marking the traffic you want to fit in the classes defined in here. You can use the same marks for different interfaces.

The priority, if specified, is an integer in the range 1-65535 and determines the relative order in which the tc mark classification filter for this class is to be applied to packets being sent on the interface. Filters are applied in ascending numerical order. If not supplied, the value is derived from the class priority (PRIORITY column value below): (class priority << 8) | 20.

---

🌸 RATE - {-|rate[:dmax[:umax]]}

The minimum bandwidth this class should get, when the traffic load rises. If the sum of the rates in this column exceeds the INTERFACE's OUT-BANDWIDTH, then the OUT-BANDWIDTH limit may not be honored. Similarly, if the sum of the rates of sub-classes of a class exceed the CEIL of the parent class, things don't work well. 😭 math is math-ing and it's not math-ing in your favor.

When using the HFSC queuing discipline, this column specify the real-time (RT) service curve. leaf classes may specify dmax, the maximum delay in milliseconds that the first queued packet for this class should experience. May be expressed as an integer, optionally followed by 'ms' with no intervening white-space (e.g., 10ms).

HFSC leaf classes may also specify umax, the largest packet expected in this class. May be expressed as an integer. The unit of measure is bytes and the integer may be optionally followed by 'b' with no intervening white-space (e.g., 800b). umax may only be given if dmax is also given. bestie they're a package deal, no solo careers 💅

Beginning with Shorewall 4.5.6, HFSC classes may omit this column (e.g, '-' in the column), provided that an lsrate is specified (see CEIL below). These rates are used to arbitrate between classes of the same priority.

---

💜 CEIL - [lsrate:]rate

The maximum bandwidth this class is allowed to use when the link is idle. Useful if you have traffic which can get full speed when more needed services (e.g. ssh) are not used.

You can use the value full in here for setting the maximum bandwidth to the RATE of the parent class, or the OUT-BANDWIDTH of the device if there is no parent class.

Beginning with Shorewall 4.5.6, you can also specify an lsrate (link sharing rate).

---

👑 PRIORITY - priority

For HTB: The priority in which classes will be serviced by the packet shaping scheduler and also the priority in which bandwidth in excess of the rate will be given to each class.

Higher priority classes will experience less delay since they are serviced first. Priority values are serviced in ascending order (e.g. 0 is higher priority than 1). yes queen 0, we see you ✨

Classes may be set to the same priority, in which case they will be serviced as equals. For both HTB and HFSC, the priority is used to calculate the priority of following Shorewall-generated classification filters that refer to the class:

• Packet MARK
• tcp-ack and the tos options (see below)

The rules for classes with lower numeric priorities will appear before those with higher numeric priorities.

Beginning with Shorewall 4.5.8, the PRIORITY may be omitted from an HFSC class if you do not use the MARK column or the tcp-ack or tos options. If you use any of those features and omit the PRIORITY, then you must specify a priority along with the MARK or option.

---

🌈 OPTIONS (Optional) - [option[,option]...]

A comma-separated list of options including the following:

• default — This is the default class for that interface where all traffic should go, that is not classified otherwise.

💖 Note: You must define default for exactly one class per interface.

• tos=0xvalue[/0xmask][:priority] (mask defaults to 0xff) — This lets you define a classifier for the given value/mask combination of the IP packet's TOS/Precedence/DiffSrv octet (aka the TOS byte).

Beginning with Shorewall 4.5.8, the value/mask may be followed by a colon (":") and a priority. This priority determines the order in which filter rules are processed during packet classification. If not specified, the value (class priority << 8) | 15 is used.

• tos-tosname[:priority] — Aliases for the following TOS octet value and mask encodings. TOS encodings of the "TOS byte" have been deprecated in favor of diffserve classes, but programs like ssh, rlogin, and ftp still use them. iykyk 💀

Beginning with Shorewall 4.5.8, the tos-name may be followed by a colon (":") and a priority. This priority determines the order in which filter rules are processed during packet classification. If not specified, the value (class priority << 8) | 15 is used.

• tos-minimize-delay — 0x10/0x10
• tos-maximize-throughput — 0x08/0x08
• tos-maximize-reliability — 0x04/0x04
• tos-minimize-cost — 0x02/0x02
• tos-normal-service — 0x00/0x1e

🎀 Note: Each of these options is only valid for ONE class per interface.

• tcp-ack[:priority] — If defined, causes a tc filter to be created that puts all tcp ack packets on that interface that have a size of <=64 Bytes to go in this class. This is useful for speeding up downloads. Please note that the size of the ack packets is limited to 64 bytes because we want only packets WITHOUT payload to match. no payload, no entry, periodt 💅

Beginning with Shorewall 4.5.8, the tcp-ack may be followed by a colon (":") and a priority. This priority determines the order in which filter rules are processed during packet classification. If not specified, the value (class priority << 8) | 10 is used.

💜 Note: This option is only valid for ONE class per interface.

• occurs=number — Typically used with an IPMARK entry in tcrules. Causes the rule to be replicated for a total of number rules. Each rule has a successively class number and mark value.

When 'occurs' is used:

• The associated device may not have the 'classify' option.
• The class may not be the default class.
• The class may not have any 'tos=' options (including 'tcp-ack').
• The class should not specify a MARK value. If one is specified, it will be ignored with a warning message.

The 'RATE' and 'CEIL' parameters apply to each instance of the class. So the total RATE represented by an entry with 'occurs' will be the listed RATE multiplied by number. For additional information, see shorewall-tcrules[3](5).

• flow=keys — Shorewall attaches an SFQ queuing discipline to each leaf HTB class. SFQ ensures that each flow gets equal access to the interface. The default definition of a flow corresponds roughly to a Netfilter connection. So if one internal system is running BitTorrent, for example, it can have lots of 'flows' and can thus take up a larger share of the bandwidth than a system having only a single active connection. The flow classifier (module cls_flow) works around this by letting you define what a 'flow' is. The classifier must be used carefully or it can block off all traffic on an interface! The flow option can be specified for an HTB leaf class (one that has no sub-classes). We recommend that you use the following:

Shaping internet-bound traffic:
                  flow=nfct-src
Shaping traffic bound for your local net:
                  flow=dst

These will cause a 'flow' to consists of the traffic to/from each internal system. 🌈✨

---

and that's part 1 bestie!! there's more coming, don't go anywhere 💖

When you hand over more than one key, wrap them in parentheses and separate them with commas, okay?

Wanna see every flow key that exists? Just run this:

tc filter add flow help

Anything that starts with nfct- is a Netfilter connection tracking field. And like we said up there, we're obsessed with flow=nfct-src — that means we're using the source IP address before NAT as the key. 💅

• pfifo — slap this on a leaf class and the class gets the pfifo queuing discipline instead of sfq.
• limit=number — added in Shorewall 4.4.3. On a leaf class, this sets the max number of packets that can sit queued up inside the class. The number has to be > 2 and <=128. Don't specify it and 127 is just assumed.
• red=(redoption=value, ...) — added in Shorewall 4.5.6. On a leaf class, this makes the class use the RED (Random Early Detection) queuing discipline instead of SFQ. Peep tc-red (8) for the extra lore.

The redoptions you're allowed to use:

• min min — the average queue size where marking first becomes a possibility.
• max max — at this average queue size, the marking probability is at its max. It has to be at least twice min so you don't get synchronous retransmits — go higher if your min is low.
• probability probability — the max probability for marking, written as a floating point number from 0.0 to 1.0. Suggested values are 0.01 or 0.02 (that's 1% or 2% respectively).
• limit limit — hard cap on the real (not average!!) queue size, in bytes. Anything past it gets dropped. Set it higher than max+burst, and honestly a few times higher than max. Shorewall needs limit to be at least twice min.
• burst burst — controls how fast the average queue size gets influenced by the real queue size. Bigger values = more sluggish math = longer bursts of traffic before marking kicks in. Real-life experiments back this guide-line: (min+min+max)/(3*avpkt).
• avpkt avpkt — optional. In bytes. Used with burst to figure out the time constant for average queue size calculations. 1000 is a good value and it's the Shorewall default.
• bandwidth bandwidth — optional. This rate gets used to calculate the average queue size after some idle time. Should be your interface's bandwidth. And no, this does not mean RED will shape for you!
• ecn — RED can either 'mark' or 'drop'. Explicit Congestion Notification lets RED tell remote hosts their rate is over the bandwidth available. Hosts that can't do ECN can only be told by dropping a packet. If you set this parameter, packets whose hosts honor ECN get marked and not dropped — unless the queue size hits limit bytes. Recommended.

• fq_codel[=(codeloption=value, ...)] — added in Shorewall 4.5.12. On a leaf class, this makes the class use the FQ_CODEL (Fair-queuing Controlled Delay) queuing discipline instead of SFQ. Peep tc-fq_codel (8) for more.

The codeloptions you're allowed to use:

• limit — hard limit on the real queue size. Hit this limit and incoming packets get dropped. Lower the value and packets get dropped so the new limit is met. Default is 1000 packets.
• flows — the number of flows the incoming packets get classified into. Hashing is stochastic, so multiple flows can end up hashed into the same slot, and newer flows get priority over older ones. This one can only be set at load time, since memory has to be allocated for the hash table. Default is 1024.
• target — the acceptable minimum standing/persistent queue delay. This minimum delay is identified by tracking the local minimum queue delay that packets experience. Default and recommended value is 5ms.
• interval — keeps the measured minimum delay from going too stale. The minimum delay has to be experienced in the last epoch of length interval. Set it on the order of the worst-case RTT through the bottleneck, so endpoints get enough time to react. Default value is 100ms.
• quantum — the number of bytes used as 'deficit' in the fair queuing algorithm. Default is 1514 bytes, which is the Ethernet MTU plus the hardware header length of 14 bytes.
• ecn | noecn — mark packets instead of dropping them. If ecn is enabled, noecn turns it off, and vice-versa. By default, ecn is enabled.

---

🌈 EXAMPLES 🌈

Example 1:

Okay so picture this: you're on PPP over Ethernet (DSL) and ppp0 is the interface for it. You've got 4 classes. The first is for voice over IP traffic, the second is for interactive traffic (think ssh/telnet but not scp), the third is for all your unclassified traffic, and the fourth is for low priority stuff (peer-to-peer, iykyk).

The voice traffic in class one gets a guaranteed minimum of 100kbps and always gets serviced first (low priority number = less delay), and it gets excess bandwidth (up to 180kbps, the class ceiling) before any other traffic. One single VoIP stream, depending on codecs, can take up to 80kbps on a PPPoE/DSL link after encapsulation, so we pad it a lil bit just in case. (TOS byte values 0xb8 and 0x68 are DiffServ classes EF and AFF3-1 respectively, and VoIP devices use them a lot.)

Interactive traffic (tos-minimum-delay) and TCP acks (and ICMP echo traffic if you use the example in tcrules) plus any packet with a mark of 2 get a guaranteed 1/4 of the link bandwidth, and can stretch up to the full speed of the link.

Unclassified traffic and packets marked as 3 get a guaranteed 1/4th of the link bandwidth, and can extend to the full speed of the link.

Packets marked with 4 get treated as low priority packets. (The tcrules example marks p2p traffic as such.) If the link is congested, they're only guaranteed 1/8th of the speed, and even if the link is empty, they can only expand to 80% of link bandwidth — just as a precaution in case there are upstream queues we didn't account for. This is the last class to get additional bandwidth and the last to get serviced by the scheduler, because of the low priority.

#INTERFACE  MARK  RATE    CEIL      PRIORITY    OPTIONS
ppp0        1     100kbit 180kbit   1           tos=0x68/0xfc,tos=0xb8/0xfc
ppp0        2     full/4  full      2           tcp-ack,tos-minimize-delay
ppp0        3     full/4  full      3           default
ppp0        4     full/8  full*8/10 4

---

📁 FILES 📁

• /etc/shorewall/tcclasses
• /etc/shorewall6/tcclasses

---

👀 SEE ALSO 👀

• https://shorewall.org/traffic_shaping.htm[4]
• https://shorewall.org/configuration_file_basics.htm#Pairs[5]
• tc-hfsc(7)
• tc-red(8)
• shorewall(8)

---

📝 NOTES 📝

1. shorewall-tcdevices https://shorewall.org/manpages/shorewall-tcdevices.html
2. shorewall-mangle https://shorewall.org/manpages/shorewall-mangle.html
3. shorewall-tcrules https://shorewall.org/manpages/shorewall-tcrules.html
4. https://shorewall.org/traffic_shaping.htm https://shorewall.org/traffic_shaping.htm
5. https://shorewall.org/configuration_file_basics.htm#Pairs https://shorewall.org/configuration_file_basics.htm#Pairs

---

And that's a wrap on the whole page, bestie 🎀 This one lives in the Configuration Files section, it's dated 09/24/2020, and it answers to the name SHOREWALL-TCCLASSES(5). Now go shape some traffic like the main character you are 💖✨