tc-htb

tc qdisc add dev <DEV> root | parent <CLASSID> [handle <QDISC_HANDLE>:] htb [default <CLASSID>] [r2q <VALUE>]
tc class add dev <DEV> parent <PARENT_CLASSID> [classid <CLASSID>] htb [rate <RATE>] [ceil <CEIL>] [burst <BURST>] [cburst <CBURST>] [prio <PRIORITY>] [quantum <QUANTUM>]

dev <DEV>
    Specifies the network device (e.g., eth0) to which the qdisc or class applies.

root | parent <CLASSID>
    Indicates whether the HTB qdisc is attached to the root of the device (root) or as a child of an existing class (parent <CLASSID>).

handle <QDISC_HANDLE>:
    Unique identifier for the HTB qdisc, often in MAJOR:0 format. Required for root qdiscs.

default <CLASSID>
    For an HTB qdisc, specifies the default class to which unclassified packets are sent. Packets not matched by any filter will go here.

r2q <VALUE>
    Rate to quantum ratio. Influences the scheduling precision and fairness between classes, particularly when using inner queuing disciplines like SFQ. A higher value means HTB tries to dequeue more bytes from a class per round.

classid <CLASSID>
    Unique identifier for the specific HTB class, often in MAJOR:MINOR format. Must be unique under its parent.

rate <RATE>
    The guaranteed minimum bandwidth for this class. Specified in various units (e.g., 100kbit, 1mbit, 10mbit). HTB ensures this class receives at least this much bandwidth if it has data to send.

ceil <CEIL>
    The maximum bandwidth this class can consume, including borrowed bandwidth from its parent or siblings. Specified in units similar to rate. A class can never exceed its ceil.

burst <BURST>
    The maximum amount of bytes that can be sent at rate above the average for a short period. This defines the token bucket size for the rate limit.

cburst <CBURST>
    The maximum amount of bytes that can be sent at ceil above the average for a short period. This defines the token bucket size for the ceil limit.

prio <PRIORITY>
    Priority level for sharing bandwidth among siblings when they are below their rate but could still borrow. Lower numerical value means higher priority (e.g., 0 is highest priority).

quantum <QUANTUM>
    The number of bytes the HTB scheduler will try to dequeue from this class in one turn. Automatically calculated based on rate if not specified, usually rate / r2q.

tc-htb refers to the Hierarchical Token Bucket (HTB) queuing discipline, a powerful component of the Linux traffic control system. HTB is designed to provide robust and flexible bandwidth management for network interfaces. It allows administrators to create a hierarchical structure of traffic classes, enabling precise control over bandwidth allocation, sharing, and prioritization for different types of network traffic. Unlike simpler queuing disciplines, HTB can guarantee minimum bandwidths (rate) while also allowing classes to borrow unused bandwidth up to a specified maximum (ceil). This makes it ideal for scenarios requiring intricate bandwidth partitioning, such as prioritizing VoIP traffic over bulk downloads, or sharing a limited internet connection among multiple users or applications fairly, yet with defined limits. It's a key tool for ensuring quality of service (QoS) on Linux systems.

HTB configuration can be complex and requires a good understanding of its hierarchical model, token bucket mechanism, and interaction with other queuing disciplines and filters. Incorrect configuration can lead to unintended traffic shaping, poor performance, or even traffic drops. Performance can be impacted by a very deep hierarchy or an excessively large number of classes. Kernel support for HTB is required, which is standard in modern Linux kernels. The actual rates and ceilings achieved can vary slightly based on packet size distribution and burst traffic.

HTB organizes traffic into a tree-like structure. The root qdisc distributes bandwidth to its direct children, which can in turn distribute to their children. Each class can have a guaranteed minimum bandwidth (rate) and a maximum (ceil). If a class is not using its full rate, the unused bandwidth can be borrowed by its siblings (if they are below their ceil) or its parent. This borrowing mechanism is controlled by priorities (prio) among siblings, ensuring that higher-priority classes get bandwidth first from the shared pool.

HTB implements traffic shaping using a token bucket mechanism for both rate and ceil. Imagine two virtual buckets for each class: one for the rate and one for the ceil. Tokens are added to these buckets at a steady rate corresponding to their respective bandwidths. To send data, a class must 'pay' with tokens from these buckets. If a bucket is empty, the class must wait until more tokens arrive, thus enforcing the specified bandwidth limit. burst and cburst parameters define the maximum number of tokens that can accumulate in these buckets, allowing for short bursts of traffic above the average rate.

HTB was developed as a more efficient and simpler alternative to the earlier Class-Based Queuing (CBQ) discipline, which often suffered from configuration complexity and performance issues. Created by Martin Devera, HTB aimed to provide robust hierarchical bandwidth management with clear guarantees and fair sharing, becoming a staple for QoS implementation in Linux environments. Its design emphasizes performance and predictability, making it a widely adopted solution for various traffic shaping needs since its introduction into the Linux kernel.

tc(8), tc-qdisc(8), tc-class(8), tc-filter(8), tc-hfsc(8), tc-prio(8), tc-sfq(8)