Problem:
	I am a web hoster and want to set speed and volume limit for each host. Is it possible ? mod_cband can be used by hosting companies, which would like to limit data transfer for their users, such as "10 GB of traffic per month" or "max 10 Mbit per second" ...

In the first two chapters I will show how to install mod_cband on Debian Sarge and on Fedora Core 5 (the 64-bit version), and in the third chapter I will describe how to configure Apache for mod_cband which is independent from the distribution you're using.

Please note: mod_cband is an Apache2 module, it does not work with Apache 1.3.x!

I want to say first that this is not the only way of setting up such a system. There are many ways of achieving this goal but this is the way I take. I do not issue any guarantee that this will work for you!

1 Installation On Debian Sarge

In order to compile mod_cband, we must have apxs2 installed. We can achieve that by doing this:

apt-get install apache2-prefork-dev

Next we download and install mod_cband like this:

cd /tmp
wget http://cband.linux.pl/download/mod-cband-0.9.7.4.tgz
tar xzvf mod-cband-0.9.7.4.tgz
cd mod-cband-0.9.7.4
./configure
make
make install

The make install command should have added the mod_cband module to /etc/apache2/httpd.conf. Run

vi /etc/apache2/httpd.conf

and check if you find a line like this:

LoadModule cband_module       /usr/lib/apache2/modules/mod_cband.so

(If you don't find this line, add it yourself.)

Finallly restart Apache:

/etc/init.d/apache2 restart

The mod_cband installation is now finished.

2 Installation On Fedora Core 5

In order to compile mod_cband, we must have apxs installed. We can achieve that by doing this:

yum install httpd-devel

Next we download and install mod_cband like this:

cd /tmp
wget http://cband.linux.pl/download/mod-cband-0.9.7.4.tgz
tar xzvf mod-cband-0.9.7.4.tgz
cd mod-cband-0.9.7.4
./configure
make
make install

The make install command should have added the mod_cband module to /etc/httpd/conf/httpd.conf. Run

vi /etc/httpd/conf/httpd.conf

and check if you find a line like this:

LoadModule cband_module       /usr/lib64/httpd/modules/mod_cband.so

(If you don't find this line, add it yourself.)

Finallly restart Apache:

/etc/init.d/httpd restart

The mod_cband installation is now finished.

3 Apache Configuration

You can find all configuration directives on mod_cband's documentation page http://cband.linux.pl/documentation; I will describe the most important ones here.

In this chapter I assume we have a web site www.example.com on the IP address 1.2.3.4 with the document root /var/www and the following vhost configuration:

<VirtualHost 1.2.3.4>   
ServerName www.example.com   
ServerAdmin 
 This e-mail address is being protected from spam bots, you need JavaScript enabled to view it
    
DocumentRoot /var/www 
</VirtualHost>

Please note: It is important that your vhost includes the ServerName directive (e.g. ServerName www.example.com) and that your mod_cband directives come after that directive, otherwise you will get a warning like this when you restart Apache:

Starting httpd: [Mon May 29 18:05:33 2006] [warn] 
Invalid command 'CBandSpeed', undefined virtualhost name

You can use the following units in the mod_cband directives:

Transfer speeds:

• kbps: 1024 bits per second
• Mbps: 1024*1024 bits per second
• Gbps: 1024*1024*1024 bits per second
• The default is kbps.

Transfer quotas:

• K: 1000 bytes
• M: 1000*1000 bytes
• G: 1000*1000*1000 bytes
• Ki: 1024 bytes
• Mi: 1024*1024 bytes
• Gi: 1024*1024*1024 bytes
• The default is K.

Time periods:

• S: seconds
• M: minutes
• H: hours
• D: days
• W: weeks
• The default is S.

First we add the following two directives to the global Apache configuration (not to the vhost from above!). They are needed to improve mod_cband's performance.

Debian:

vi /etc/apache2/apache2.conf

Fedora:

vi /etc/httpd/conf/httpd.conf

CBandScoreFlushPeriod 1 CBandRandomPulse On

Now we create the scoreboard directory for our www.example.com vhost, /var/www/scoreboard. The directory must be writeable by the Apache user:

Debian:

mkdir /var/www/scoreboard
chown www-data:www-data /var/www/scoreboard/

Fedora:

mkdir /var/www/scoreboard
chown apache:apache /var/www/scoreboard/

3.1 Configure Download Speed

Now let's say we want to limit the download speed. We can do it like this:

<VirtualHost 1.2.3.4>   
ServerName www.example.com   
ServerAdmin 
 This e-mail address is being protected from spam bots, you need JavaScript enabled to view it
    
DocumentRoot /var/www   
CBandSpeed 1024 10 30   
CBandRemoteSpeed 20kb/s 3 3 
</VirtualHost>

The CBandSpeed directive limits the overall Apache performance for the www.example.com vhost to a speed of 1024kbps, max. 10 requests per second and max. 30 open connections.

The CBandRemoteSpeed is like the CBandSpeed directive, but it sets limits for any individual user (as compared to the overall settings made by CBandSpeed).

After your changes, you must restart Apache:

Debian:

/etc/init.d/apache2 restart

Fedora:

/etc/init.d/httpd restart

3.2 Configure Traffic Limits

In the next example we want to give our vhost www.example.com a traffic limit of 100MB per month, and if that limit is exceeded, we want to limit the download speed to 128kbps, max. 5 requests per second and max. 15 open connections:

<VirtualHost 1.2.3.4>   
ServerName www.example.com   
ServerAdmin 
 This e-mail address is being protected from spam bots, you need JavaScript enabled to view it
    
DocumentRoot /var/www   
CBandLimit 100M   
CBandExceededSpeed 128 5 15   
CBandScoreboard /var/www/scoreboard   
CBandPeriod 4W 
</VirtualHost>

The directives are pretty self-explanatory. The CBandPeriod directive specifies after what time the traffic counter is reset to 0.

The next example is pretty similar, but now we don't want the speed to be limited if the traffic is exceeded, no, we get more restrictive and deliver a 503 status page instead:

<VirtualHost 1.2.3.4>   
ServerName www.example.com   
ServerAdmin 
 This e-mail address is being protected from spam bots, you need JavaScript enabled to view it
    
DocumentRoot /var/www   
CBandLimit 100M   
CBandScoreboard /var/www/scoreboard   
CBandPeriod 4W 
</VirtualHost>

If you want to redirect the user to a URL instead of presenting a 503 error to him, you can do it like this:

<VirtualHost 1.2.3.4>   
ServerName www.example.com   
ServerAdmin 
 This e-mail address is being protected from spam bots, you need JavaScript enabled to view it
    
DocumentRoot /var/www   
CBandLimit 100M   
CBandExceededURL http://www.someisp.com/traffic_exceeded.html   
CBandScoreboard /var/www/scoreboard   
CBandPeriod 4W 
</VirtualHost>

Please note: the CBandExceededSpeed and the CBandExceededURL directives are mutually exclusive. They do not make sense in the same vhost!

After your changes, you must restart Apache:

Debian:

/etc/init.d/apache2 restart

Fedora:

/etc/init.d/httpd restart

Of course, you are free to combine the directives of chapter 3.1 and 3.2 in any way you like.

4 Status Page

To view the current bandwidth limits, usages, users, scoreboards, add the following Location lines to the vhost configuration:

<VirtualHost 1.2.3.4>   
ServerName www.example.com   
ServerAdmin 
 This e-mail address is being protected from spam bots, you need JavaScript enabled to view it
    
DocumentRoot /var/www   
CBandLimit 100M   
CBandExceededSpeed 128 5 15   
CBandScoreboard /var/www/scoreboard   
CBandPeriod 4W    
<Location /cband-status>     
SetHandler cband-status   
</Location>   
<Location /cband-status-me>     
SetHandler cband-status-me   
</Location> 
</VirtualHost>

Restart Apache, and afterwards you can find the status pages under http://www.example.com/cband-status and http://www.example.com/cband-status-me: