htb.init is meant to simplify setup of HTB based traffic control.
- v0.8.5- Nathan Shafer <nicodemus at users.sourceforge.net>
- allow symlins to class files
- Seth J. Blank <antifreeze at users.sourceforge.net>
- replace hardcoded ip/tc location with variables
- Mark Davis <mark.davis at gmx.de>
- allow setting of PRIO_{MARK,RULE,REALM} in class file
- Seth J. Blank <antifreeze at users.sourceforge.net>
- v0.8.4- Lubomir Bulej <pallas at kadan.cz>
- fixed small bug in RULE parser to correctly parse
rules with identical source and destination fields
- removed the experimental INJECT keyword
- ignore *~ backup files when looking for classes
- Mike Boyer <boyer at administrative.com>
- fix to allow arguments to be passed to "restart" command
- <face at pos.sk>
- fix to preserve class priority after timecheck
- Mike Boyer <boyer at administrative.com>
- v0.8.3- Lubomir Bulej <pallas at kadan.cz>
- use LC_COLLATE="C" when sorting class files
- Paulo Sedrez
- fix time2abs to allow hours with leading zero in TIME rules
- Paulo Sedrez
- v0.8.2- Lubomir Bulej <pallas at kadan.cz> - thanks to Hasso Tepper for reporting the following problems - allow dots in interface names for use with VLAN interfaces - fixed a thinko resulting from "cosmetic overdosage" :)
- v0.8.1- Lubomir Bulej <pallas at kadan.cz> - added function alternatives for sed/find with less features. To enable them, you need to set HTB_BASIC to nonempty string. - added posibility to refer to RATE/CEIL of parent class when setting RATE/CEIL for child class. Look for "prate" or "pceil" in the documentation. - fixed broken "timecheck" invocation
- v0.8 - Lubomir Bulej <pallas at kadan.cz> - simplified and converted CBQ.init 0.7 into HTB.init - changed configuration file naming conventions - lots of HTB specific changes
This script is a clone of CBQ.init and is meant to simplify setup of HTB based traffic control. HTB setup itself is pretty simple compared to CBQ, so the purpose of this script is to allow the administrator of large HTB configurations to manage individual classes using simple, human readable files.
The "H" in HTB stands for "hierarchical", so while many people did not use (or know about) the possibility to build hierarchical structures using CBQ.init, it should be obvious thing to expect from HTB.init :-)
In HTB.init this is done differently, compared to CBQ.init: the usage of PARENT keyword was dropped and instead, class file naming convetion was introduced. This convention allows the child class to determine ID of its parent class from the filename and also (if not abused :) enforces file ordering so that the parent classes are created before their children.
HTB.init uses simple caching mechanism to speed up "start" invocation if the configuration is unchanged. When invoked for the first time, it compiles the configuration files into simple shell script containing the sequence of "tc" commands required to setup the traffic control. This cache-script is stored in /var/cache/htb.init by default and is invalidated either by presence of younger class config file, or by invoking HTB.init with "start invalidate".
If you want to HTB.init to setup the traffic control directly without the cache, invoke it with "start nocache" parameters. Caching is also disabled if you have logging enabled (ie. HTB_DEBUG is not empty).
If you only want HTB.init to translate your configuration to "tc" commands, invoke it using the "compile" command. Bear in mind that "compile" does not check if the "tc" commands were successful - this is done (in certain places) only when invoked with "start nocache" command. When you are testing your configuration, you should use it to check whether it is completely valid.
In case you are getting strange sed/find errors, try to uncomment line with HTB_BASIC setting, or set the variable to nonempty string. This will enable function alternatives which require less advanced sed/find functionality. As a result, the script will run slower but will probably run. Also the caching will not work as expected and you will have to invalidate the cache manually by invoking HTB.init with "start invalidate".
Every traffic class is described by a single file in placed in $HTB_PATH directory, /etc/sysconfig/htb by default. The naming convention is different compared to CBQ.init. First notable change is missing 'htb-' prefix. This was replaced by interface name to improve human readability and to separate qdisc-only configuration.
Global qdisc options are placed in $HTB_PATH/<ifname>, where <ifname> is (surprisingly) name of the interface, made of characters and numbers. This file must be present if you want to setup HTB on that interface. If you don't have any options to put into it, leave it empty, but present.
Class options belong to files with names matching this expression:
$HTB\_PATH/<ifname>-<clsid>(:<clsid>)*<description>
<clsid> is class ID which is hexadecimal number in range 0x2-0xFFFF, without the "0x" prefix. If a colon-delimited list of class IDs is specified, the last <clsid> in the list represents ID of the class in the config file.
<clsid> preceding the last <clsid> is class ID of the parent class. To keep ordering so that parent classes are always created before their children, it is recommended to include full <clsid> path from root class to the leaf one.
<description> is (almost) arbitrary string where you can put symbolic class names for better readability.
Examples of valid names:
eth0-2 root class with ID 2, on device eth0 eth0-2:3 child class with ID 3 and parent 2, on device eth0 eth0-2:3:4 child class with ID 4 and parent 3, on device eth0 eth1-2.root root class with ID 2, on device eth1
The configuration files may contain the following parameters. For detailed description of HTB parameters see http://luxik.cdi.cz/~devik/qos/htb.
The following parameters apply to HTB root queuening discipline only and are expected to be put into $HTB_PATH/<ifname> files. These files must exist (even empty) if you want to configure HTB on given interface.
DEFAULT=<clsid> optional, default 0 DEFAULT=30
is ID of the default class where UNCLASSIFIED traffic goes. Unlike HTB qdisc, HTB.init uses 0 as default class ID, which is internal FIFO queue that will pass packets along at FULL speed!
If you want to avoid surprises, always define default class and allocate minimal portion of bandwidth to it.
R2Q=<number> optional, default 10 R2Q=100
This allows you to set coefficient for computing DRR (Deficit Round Robin) quanta. The default value of 10 is good for rates from 5-500kbps and should be increased for higher rates.
DCACHE=yes|no optional, default "no"
This parameters turns on "dequeue cache" which results in degraded fairness but allows HTB to be used on very fast network devices. This is turned off by default.
The following are parameters for HTB classes and are expected to be put into $HTB_PATH/<ifname>-<clsid>(:<clsid>). files.
RATE=<speed>|prate|pceil mandatory RATE=5Mbit
Bandwidth allocated to the class. Traffic going through the class is shaped to conform to specified rate. You can use Kbit, Mbit or bps, Kbps and Mbps as suffices. If you don't specify any unit, bits/sec are used. Also note that "bps" means "bytes per second", not bits.
The "prate" or "pceil" values will resolve to RATE or CEIL of parent class. This feature is meant to help humans to keep configuration files consistent.
CEIL=<speed>|prate|pceil optional, default $RATE CEIL=6MBit
The maximum bandwidth that can be used by the class. The difference between CEIL and RATE amounts to bandwidth the class can borrow, if there is unused bandwidth left.
By default, CEIL is equal to RATE so the class cannot borrow bandwidth from its parent. If you want the class to borrow unused bandwidth, you must specify the maximal amount it can use, if available.
When several classes compete for the unused bandwidth, each of the classes is given share proportional to their RATE.
BURST=<bytes> optional, default computed BURST=10Kb
CBURST=<bytes> optional, default computed CBURST=2Kb
BURST and CBURST parameters control the amount of data that can be sent from one class at maximum (hardware) speed before trying to service other class.
If CBURST is small (one packet size) it shapes bursts not to exceed CEIL rate the same way PEAK works for TBF.
PRIO=<number> optional, default 0 PRIO=5
Priority of class traffic. The higher the number, the lesser the priority. Also, classes with higher priority are offered excess bandwidth first.
LEAF=none|sfq|pfifo|bfifo optional, default "none"
Tells the script to attach specified leaf queueing discipline to HTB class. By default, no leaf qdisc is used.
If you want to ensure (approximately) fair sharing of bandwidth among several hosts in the same class, you should specify LEAF=sfq to attach SFQ as leaf queueing discipline to the class.
MTU=<bytes> optional, default "1600"
Maximum packet size HTB creates rate maps for. The default should be sufficient for most cases, it certainly is for Ethernet.
The SFQ queueing discipline is a cheap way to fairly share class bandwidth among several hosts. The fairness is approximate because it is stochastic, but is not CPU intensive and will do the job in most cases. If you desire real fairness, you should probably use WRR (weighted round robin) or WFQ queueing disciplines. Note that SFQ does not do any traffic shaping - the shaping is done by the HTB class the SFQ is attached to.
QUANTUM=<bytes> optional, qdisc default
Amount of data in bytes a stream is allowed to dequeue before next queue gets a turn. Defaults to one MTU-sized packet. Do not set this parameter below the MTU!
PERTURB=<seconds> optional, default "10"
Period of hash function perturbation. If unset, hash reconfiguration will never take place which is what you probably don't want. The default value of 10 seconds is probably a good value.
Those are simple FIFO queueing disciplines. They only have one parameter which determines their length in bytes or packets.
LIMIT=<packets>|<bytes> optional, qdisc default LIMIT=1000
Number of packets/bytes the queue can hold. The unit depends on the type of queue used.
RULE=[[saddr[/prefix]][:port[/mask]],][daddr[/prefix]][:port[/mask]]
These parameters make up "u32" filter rules that select traffic for each of the classes. You can use multiple RULE fields per config.
The optional port mask should only be used by advanced users who understand how the u32 filter works.
Some examples:
RULE=10.1.1.0/24:80
selects traffic going to port 80 in network 10.1.1.0
RULE=10.2.2.5
selects traffic going to any port on single host 10.2.2.5
RULE=10.2.2.5:20/0xfffe
selects traffic going to ports 20 and 21 on host 10.2.2.5
RULE=:25,10.2.2.128/26:5000
selects traffic going from anywhere on port 50 to
port 5000 in network 10.2.2.128
RULE=10.5.5.5:80,
selects traffic going from port 80 of single host 10.5.5.5
REALM=[srealm,][drealm]
These parameters make up "route" filter rules that classify traffic according to packet source/destination realms. For information about realms, see Alexey Kuznetsov's IP Command Reference. This script does not define any realms, it justs builds "tc filter" commands for you if you need to classify traffic this way.
Realm is either a decimal number or a string referencing entry in /etc/iproute2/rt_realms (usually).
Some examples:
REALM=russia,internet
selects traffic going from realm "russia" to realm "internet"
REALM=freenet,
selects traffic going from realm "freenet"
REALM=10
selects traffic going to realm 10
MARK=<mark>
These parameters make up "fw" filter rules that select traffic for each of the classes accoring to firewall "mark". Mark is a decimal number packets are tagged with if firewall rules say so. You can use multiple MARK fields per config.
Note: Rules for different filter types can be combined. Attention must be paid to the priority of filter rules, which can be set below through the PRIO_{RULE,MARK,REALM} variables.
TIME=[<dow><dow>.../]<from>-<till>;<rate>[/<burst>][,<ceil>[/<cburst>]] TIME=60123/18:00-06:00;256Kbit/10Kb,384Kbit TIME=18:00-06:00;256Kbit
This parameter allows you to change class bandwidth during the day or week. You can use multiple TIME rules. If there are several rules with overlapping time periods, the last match is taken. The , , and fields correspond to parameters RATE, BURST, CEIL and CBURST.
is single digit in range 0-6 and represents day of week as returned by date(1). To specify several days, just concatenate the digits together.
Consider the following example: (taken from Linux Advanced Routing & Traffic Control HOWTO)
You have a Linux server with total of 5Mbit available bandwidth. On this machine, you want to limit webserver traffic to 5Mbit, SMTP traffic to 3Mbit and everything else (unclassified traffic) to 1Kbit. In case there is unused bandwidth, you want to share it between SMTP and unclassified traffic.
The "total bandwidth" implies one top-level class with maximum bandwidth of 5Mbit. Under the top-level class, there are three child classes.
First, the class for webserver traffic is allowed to use 5Mbit of bandwidth.
Second, the class for SMTP traffic is allowed to use 3Mbit of bandwidth and if there is unused bandwidth left, it can use it but must not exceed 5Mbit in total.
And finally third, the class for unclassified traffic is allowed to use 1Kbit of bandwidth and borrow unused bandwith, but must not exceed 5Mbit.
If there is demand in all classes, each of them gets share of bandwidth proportional to its default rate. If there unused is bandwidth left, they (again) get share proportional to their default rate.
Configuration files for this scenario:
eth0 eth0-2.root eth0-2:10.www eth0-2:20.smtp eth0-2:30.dfl
---- ----------- ------------- -------------- -------------
DEFAULT=30 RATE=5Mbit RATE=5Mbit RATE=3Mbit RATE=1Kbit
BURST=15k BURST=15k CEIL=5Mbit CEIL=5Mbit
LEAF=sfq BURST=15k BURST=15k
RULE=*:80, LEAF=sfq LEAF=sfq
RULE=*:25
Remember that you can only control traffic going out of your linux machine. If you have a host connected to network and want to control its traffic on the gateway in both directions (with respect to the host), you need to setup traffic control for that host on both (or all) gateway interfaces.
Enjoy.
############################################################################