The Linux Blog UNIX, LINUX, BSD, OSX

Htb-Tools Tutorial – Traffic shaping

HTB-tools was started by Ionut Spirlea ionut.spirlea[at]rdsnet.ro, Manuel Subredu diablo[at]infoiasi.ro, Vasile Laurentiu Stanimir stanimir[at]cr.nivis.com. Over the time, they couldn't dedicate more resources to this project.

Needing a tool to manage the bandwidth for a wireless network, HTB-tools came across. As it was unmaintained, the author of this site decided to take over the project. Meanwhile, other great people contributed to this project, please see the Credits list. Thanks, guys! You were great!

HTB-tools is a software suite with several tools that help simplify the difficult process of bandwidth allocation, for both upload and download traffic: generate and check configuration files, real time traffic overview for each separate client.

Features:
* bandwidth limitation using public IP addresses, using the two configuration files for upload and download
* bandwidth limitation using private IP addresses (SNAT), using a single configuration file
* match mark
* match mark in u32
* metropolitan/external limitation
* menu based management software for configuration and administration of HTB-tools (starting with version 0.3.0)

How To use HTB-tools

Hierarchical Token Bucket ( HTB ) successfully replaces Class Based Queueing ( CBQ ) due to the precise and easy to understand way it operates. The difference from CBQ is that the bandwidth is allocated to one (or more) classes, and when the class's allocated bandwidth is exceeded, it can (temporarily) borrow unused bandwidth from another class. Moreover, unlike CBQ, you can allocate several clients to one class. Using HTB-tools all classes and all clients can be defined in a configuration file.

To better understand how it works, let's suppose that we have a bandwidth of 256kbps shared by 4 clients (with routable IP addresses), each client having a guaranteed minimum of 48kbps and a guaranteed maximum of 64kbps upload/download.

After HTB-tools is installed, you can proceed to editing the configuration files.
Assuming that eth0 is the interface to your provider and eth1 the interface to your clients, on the eth0 interface you can only limit the upload (only if you use public IP addresses) and on eth1 only the download, because you can only control the debit of the packages that leave the router ( the information that enters the router is imposed by the external environment ).
For upload limitations/guarantees you have to edit the file /etc/htb/eth0-qos.cfg and for download limitations/guarantees you have to edit the file /etc/htb/eth1-qos.cfg

Configuration files for HTB-tools

Remarks:
- the format of the configuration files resembles the format of bind's configuration files;
- the bandwidth users are divided into classes;
- these classes can not share the bandwidth among themselves;
- the members of a class (clients) can share the same bandwidth according to the parameters specified in the configuration file;
- a class may contain one or more clients;
- a special class is the default class, that defines the bandwidth allocated to those which are not included in any class;
- the transfer rate is specified in kbit;
- the lines having # as the first character are considered comments.
- you can NOT specify the fields src and dst for a class; these fields are only defined for clients.

The class syntax:
bandwidth 192; - the guaranteed minimum for the class; represents the minimum total sum guaranteed for the clients of the class;
limit 256; - the maximum transfer rate for the class;
burst 2; - the maximum number of kbits sent at once by the class;

!!! NOTE:
If you don't set the burst value properly, the limits might not work
correctly. Eg: for the limit 10000kbit you must use a burst of 12 kbit.
THIS IS AVAILABLE ONLY IF YOU USE PUBLIC IPs !

burst 0; - ONLY for HTB-tools beta4 - if burst is set to 0 then HTB-tools will calculate the burst value automatically. This is valid for clients side too.
priority 1; - priority of the class; there are 8 priority levels: from 0 to 7. The packets are served in ascending order of priority. For example, if the priority is 0 then the packets will first be served to this class, on the other hand if the priority is 4 then the packets will first be sent to the class having priority 0 and only then to the class having priority 4;
que sfq; - we can specify the qdisc for a class, if not specified the default is pfifo limit 5.
(or esfq;)
For more details about esfq, please see [link]

As specified above, we have a bandwidth of 256kbps that we want to allocate to 4 clients, both for upload and for download. For this, we first define the class:

class class_1 {

bandwidth 192;

limit 256;

burst 2;

priority 1;

que sfq;

The clients syntax:
bandwidth 48; - guaranteed minimum for the client;
limit 64; - maximum transfer rate for the client;
burst 2; - maximum number of kbits sent to the client at once;
mark 20; - if only mark is specified, without dst/src, then fw will be used; if the source/destination is specified, then u32 will be used with the possibility to mark (match_in_u32);
dst or src can be used together in the configuration file only for clients; if you wish to limit the upload then you must use src, and if you wish to limit the download then you must use dst; in our example above we have used limitation/allocation for download and the configuration file will be eth1-qos.cfg;
priority 1; - client priority;
- in the case of a single IP, the representation looks like this: 192.168.1.10/32;
- in the case of a class, the representation looks like this: 192.168.1.0/24;
- if you wish to apply the limitation to a particular port for a single IP:
192.168.1.10/32 80; - limits the traffic to port 80 (http)
- if you wish to apply the limitation to a particular port for an IP class:
192.168.1.0/24 21; - limits the traffic to port 21 (ftp)

The next step is to define the 4 clients. For each client a minimum of 48kbit and a maximum of 64kbit will be allocated.

client client1 {

bandwidth 48;

limit 64;

burst 2;

priority 1;

mark 20;

dst {

192.168.100.4/32;

};

};

client client2{

bandwidth 48;

limit 64;

burst 2;

priority 1;

mark 20;

dst {

192.168.100.5/32;

};

};

client client3 {

bandwidth 48;

limit 64;

burst 2;

priority 1;

mark 20;

dst {

192.168.100.8/32;

};

};

client clien4 {

bandwidth 48;

limit 64;

burst 2;

priority 1;

mark 20;

dst {

192.168.100.10/32;

};

};

class default { bandwidth 8; };
};
};

Only for HTB-tools beta4
Another new feature is the "upload" function, which would assist in managing the
upload, if you use SNAT (non-routeable IP addresses). This can be done using the same configuration file that you would use to manage the download.
WARNING: this type of shaping (ingress) drops the packets that are over the
limit, which generates additional traffic when entering the interface. For this reason it is
recommended to have the shaping machine in the same LAN with the shaped machines.
The "upload" option uses dst but don't work with mark.

Configuration examples (client side):

client client {

bandwidth 350;

limit 1200;

burst 0; # new

priority 1;

upload 300; #( in kbits) <- new

dst {

192.168.100.5/32;

};

};

client client {

bandwidth 350;

limit 1200;

burst 0; # new

priority 1;

upload 300; #( in kbits) <- new

dst {

192.168.100.30/32;

};

};

UPLOAD option available from 0.3.0-beta4 works only with dst.
You can specify mark or src but this options will NOT
affect outgoing trafic.

The next step is checking the configuration file using the q_checkcfg command:

q_checkcfg /etc/htb/eth1-qos.cfg

Default bandwidth: 8
Class class_1, CIR: 192, MIR: 256
** 4 clients, CIR2: 192, MIR2: 256
1 classes; CIR / MIR = 192 / 256; CIR2 / MIR2 = 192 / 256

- the configuratin files are syntactically correct.

The rc.htb init script
------------------------
With this script you can start/stop/monitor/generate/restart the limitations/guarantees for upload/download or for both together.

To start at boot the bandwidth policies for upload and download you must add to /etc/rc.d/rc.local the line:

/etc/rc.d/rc.htb start

If you wish to limit/guarantee the bandwidth only for download then you must use the command:(this example is works on Slackware linux)

/etc/rc.d/rc.htb start_eth1

If you wish to limit/guarantee the bandwidth only for upload then you must use the command:

/etc/rc.d/rc.htb start_eth0

If you wish to generate the traffic rules script you can use:
for eth0

[center]/etc/rc.d/rc.htb gen_eth0[/center]

for eth1

[center]/etc/rc.d/rc.htb gen_eth1[/center]

q_show allows you to see in real-time the traffic and bandwidth usage for each client (download). In order to see realtime trafic run:

/etc/rc.d/rc.htb show_eth1

...and the result is:

class_1

224.80

2

192

256

client_1

62.25

1

48

64

client_2

51.05

1

48

64

client_3

48.25

1

48

64

client_4

63.25

1

48

64

_default_

0

0

0

0

If you like to pass some options to q_show , please see the q_show(8) man page.

rc.htb complete options and usage
----------------------------------------
/etc/rc.d/rc.htb start | stop | restart |
start_eth0 | stop_eth0 | restart_eth0 |
start_eth1 | stop_eth1 | restart_eth1 |
start_eth2 | stop_eth2 | restart_eth2 |
show_eth0 | show_eth1 | show_eth2 |
gen_eth0 | gen_eth1 |

Web q_show
---------------
Web q_show is a tool that displays in a webpage the traffic status and allocated bandwidth for each class/client according to the configuration file.
A cron job collects the traffic data in a .log file, namely q_show.log. From here on it is the job of .php script (q_show.php) that parses the file and displays the content in a webpage.

Configuration
----------------
Before starting anything, you must have php installed and a working
web server (apache). Let's assume that you have domain.ro and the
default directory for the webpages is /var/www/htdocs/. The default
directory specified at the install time (with "make install_web") will
have a folder called webhtb with q_show.php script.

Before adding the line to crontab, set:
- the time interval (*/1 every minute or */5 every 5 minutes etc) at which to generate the traffic logs in the file;
- the correct path to the configuration file
- the interface, ethx where x = 0, 1, 2 ... etc, the interface you want to monitor;
- ethx-qos.cfg the configuration file for the monitored interface;
- the path to the webhtb directory;

Add to crontab (crontab -e):

*/1 * * * * /sbin/q_show -i eth1 -f /etc/htb/eth1-qos.cfg -1 > /var/www/htdocs/webhtb/q_show.log

You can see the traffic at the address [link] .

Web HTB-tools configuration files generator
---------------------------------------------------
The web q_show install will get you whtbcfg in the same directory as webhtb (i.e.: /var/www/htdocs/whtbcfg). You will need a functional httpd (apache) with php support to be able to use it.

php.ini settings
------------------
Please set register_globals to ON in php.ini and disable error_reporting like
this:

register_globals = on<br>#error_reporting = E_ALL & ~E_NOTICE

After modifying php.ini, please restart the httpd server and point your browser to [link] to be able to generate configuration files.

Possible configurations in HTB-tools beta 4
--------------------------------------------------
Please see the file cfg/possible_configs