Master Linux Traffic Control (TC): Shape Bandwidth with HTB, Classes, and Filters

Overview of TC

TC (Traffic Control) is a Linux kernel subsystem that shapes, schedules and limits network traffic. By attaching a queueing discipline (qdisc) to a network interface, administrators can control upload/download rates, assign priorities, and prevent a single host from monopolising the link.

Key Building Blocks

Queueing Discipline (qdisc) – the top‑level scheduler that buffers packets and decides when they are transmitted.

Class – a traffic‑shaping policy (rate, ceil, priority, burst, etc.). Classes can be nested to form a hierarchy.

Filter – a classifier that maps packets to a specific class based on criteria such as IP address, port, or netfilter mark.

Queueing Disciplines

The simplest qdisc is pfifo, which queues packets FIFO without any shaping. More sophisticated qdiscs include: sfq (Stochastic Fair Queue) – provides per‑flow fairness. tbf (Token Bucket Filter) – enforces a strict rate limit with burst capability. htb (Hierarchical Token Bucket) – the modern replacement for CBQ, allowing hierarchical bandwidth allocation with separate rate (guaranteed) and ceil (maximum) values.

Filters and Classification

Filters are attached to a qdisc and operate inside the qdisc hierarchy. Common filter types are: fwmark – matches packets marked by the netfilter/iptables MARK target. u32 – matches arbitrary header fields using a flexible mask.

Routing‑based and RSVP classifiers – used for IPv4/IPv6 specific scenarios.

Typical workflow: iptables marks packets → TC filter matches the mark → packet is placed into the corresponding class.

Typical HTB Configuration

Assume eth0 is the external interface. The following steps create a root HTB qdisc, a parent class that limits the interface, a child class for a specific IP or application, attach an sfq qdisc to the child, and finally add a filter that directs marked packets to the child class.

Add a root HTB qdisc with a default class:

tc qdisc add dev eth0 root handle 1: htb default 1

Create the top‑level class that defines the overall bandwidth envelope:

tc class add dev eth0 parent 1:0 classid 1:30 htb rate 2mbit ceil 4mbit prio 2

Create a child class for a particular flow or IP address:

tc class add dev eth0 parent 1:30 classid 1:31 htb rate 0.5mbit ceil 2mbit prio 3

Attach an sfq qdisc to the child class to avoid a single flow hogging the bandwidth:

tc qdisc add dev eth0 parent 1:31 handle 31: sfq perturb 10

Add a filter that matches the mark set by iptables and directs traffic to the child class:

tc filter add dev eth0 parent 1: protocol ip prio 31 handle 31 fw flowid 1:31

Mark the desired packets with iptables (or use a u32 filter):

iptables -t mangle -I FORWARD -i !eth1 -p tcp --sport 80 -s xxx.xxx.xxx.xxx -j MARK --set-mark 31

Parameters: rate, ceil, burst, cburst

rate – guaranteed bandwidth for a class. The sum of child rates must not exceed the parent rate.

ceil – maximum bandwidth a class may borrow. It must be at least equal to the class’s rate and not lower than any child’s ceil.

burst – amount of data that can be sent at the interface’s line rate before the token bucket limits apply. It smooths short‑term spikes.

cburst – similar to burst but used for the ceiling rate. Both values should be at least as large as the corresponding values of any child class.

Command Reference

tc qdisc add|change|replace|link dev DEV [parent qdisc-id|root] [handle qdisc-id] qdisc [qdisc‑specific parameters]

tc class add|change|replace dev DEV parent qdisc-id [classid class-id] qdisc [qdisc‑specific parameters]

tc filter add|change|replace dev DEV [parent qdisc-id|root] protocol PROTO prio PRIORITY filtertype [filter‑specific parameters] flowid FLOW-ID

Show configuration: tc -s -d qdisc show dev eth0 and tc -s -d class show dev eth0 Delete a qdisc:

tc qdisc del dev eth0 root

Example: Limit a Single Host

To cap the download speed of host 192.168.1.2 to 30 Mbit with a ceiling of 60 Mbit:

tc qdisc add dev eth0 root handle 1: htb r2q 1

tc class add dev eth0 parent 1: classid 1:1 htb rate 30mbit ceil 60mbit

tc filter add dev eth0 parent 1: protocol ip prio 16 u32 match ip dst 192.168.1.2 flowid 1:1

The same pattern can be used to limit an entire subnet or to attach an sfq qdisc under the class for fair sharing among multiple hosts.

Verification and Cleanup

Display the current configuration with:

tc -s -d qdisc show dev eth0
tc -s -d class show dev eth0

Remove all TC rules on the interface with:

tc qdisc del dev eth0 root

Illustration