Documentation

mod_cband configuration

Configuration is very simple, you must write only several lines. First, you must add the following command to the main config file to load the mod_cband module:

1
LoadModule cband_module      modules/mod_cband.so

Configuration Directives

New commands from 0.9.7.0 version:

  • CBandDefaultExceededCode - the http code sent to the user when the quota is exceeded

Units accepted in various directives:

* transfer speeds:


  * **kbps, Mbps, Gbps** - multiples of "bits per second", respectively: 1024, 1024*1024 and 1024*1024*1024 bps


  * **kb/s, Mb/s, Gb/s** - multiples of "bytes per second", respectively: 1024, 1024*1024 and 1024*1024*1024 b/s


  * defaults to** kbps**










* transfer quotas:


  * **K, M, G** - multiples of bytes, respectively: 1000, 1000*1000 and 1000*1000*1000 bytes


  * **Ki, Mi, Gi** - multiples of bytes, respectively: 1024, 1024*1024 and 1024*1024*1024 bytes


  * defaults to** K**
  • time periods:

    • S, M, H, D, W - multiples of seconds: Seconds, Minutes, Hours, Days, Weeks; respectively: 1, 60, 3600, 86400, 604800 seconds

    • defaults to S

Name **CBandDefaultExceededURL**
Description Default URL where mod_cband should redirect all requests to the virtualhost or user when the configured transfer limit is exceeded **NOTE** : If you don’t specify the exceeded URL location then standard 503 Service Unavailable will be sent
Context Server config
Syntax CBandDefaultExceededURL**_ URL_**
Name **CBandDefaultExceededCode**
Description The http code sent to the user when the configured transfer is exceeded
Context Server config
Syntax CBandDefaultExceededCode**_ HTTP_CODE_**
Example CBandDefaultExceededCode 509
Name **CBandScoreFlushPeriod**
Description Specifies a period after which the score for the virtualhost or user is written to the scoreboard file. Use this to improve mod_cband’s performance
Default 1
Context Server config
Syntax CBandScoreFlushPeriod**_ number_of_requests_**
Example CBandScoreFlushPeriod 100 Any virtualhost’s or user’s scoreboard will be saved after 100 requests
Name **CBandSpeed**
Description Specifies a maximal speed for a virtualhost
Context
Syntax CBandSpeed**_ kbps_ _rps_ _max_conn_** kbps - maximal transfer speed in [kMG]bps or [kMG]B/s rps - maximal requests per second max_conn - maximal number of simultaneous connections
Example CBandSpeed 1024 10 30Specifies maximal speed 1024kbps (1024 * 1024 bits per second), maximal 10 requests per second and with a maximum of 30 open connections **NOTE:** This feature is available from version** 0.9.6.0**
Name **CBandRemoteSpeed**
Description Specifies maximal speed for any remote client
Context
Syntax CBandRemoteSpeed**_ kbps_ _rps_ _max_conn_** kbps - maximal transfer speed in [kMG]bps or [kMG]B/s rps - maximal requests per second max_conn - maximal number of simultaneous connections
Example CBandRemoteSpeed 20kb/s 3 3Specifies maximal speed 20kB/s (20 * 1024 bytes per second), maximal 3 requests per second and 3 open connections for any remote client **NOTE:** This feature is available from version** 0.9.6.1-rc2**
Name **CBandClassRemoteSpeed**
Description Specifies maximal speed for any remote client from some destination class
Context
Syntax CBandClassRemoteSpeed**_ class_name_ _kbps_ _rps_** class_name - name of defined destination class kbps - maximal transfer speed in kbps or kB/s rps - maximal requests per second max_conn - maximal number of simultaneous connections
Example CBandClassDst 66.249.64/24 CBandClassDst 66.249.65/24 CBandClassDst 66.249.79/24CBandClassRemoteSpeed googlebot_class 20kb/s 2 3 -Specifies maximal speed 20kB/s (20 * 1024 bytes per second), maximal 2 requests per second and 3 open connections for any remote client from class googlebot_class **NOTE:** This feature is available from version** 0.9.6.1-rc2**
Name **CBandRandomPulse**
Description Turns On or Off the random pulse generator for data sending Random pulse generator is a part of the speed-limiting implementation of mod_cband. This directive changes the way a connection’s speed is determined and enforced. The connections’ speeds are measured within some time period and then provided for in that period. When r.p.g. is enabled this period is chosen randomly, providing for a statisticaly saner load distribution. Disabling this causes spikes both in bandwidth and cpu usages
Context Global
Syntax CBandRandomPulse**_ On/Off_**
Name **CBandLimit**
Description Specifies bandwidth limit for virtualhost
Context
Syntax CBandLimit**_ limit_** limit - bandwidth quota size, available units:** K (kilo), M (mega), G (giga), Ki (kibi), Mi (mebi), Gi (gibi)**
Example CBandLimit 10M Specifies 10 * 1000 * 1000 bytes bandwidth quota CBandLimit 10Mi Specifies 10 * 1024 * 1024 bytes bandwidth quota **IMPORTANT NOTE** : the meaning of K, M and G changed with version 0.9.6.0. Check your config
Name **CBandClassLimit**
Description Specifies bandwidth limit for virtualhost’s destination class
Context
Syntax CBandClassLimit**_ class_name_ _limit_** class_name - the name of defined class limit - bandwidth quota size, available units:** K (kilo), M (mega), G (giga), Ki (kibi), Mi (mebi), Gi (gibi)** **IMPORTANT NOTE** : the meaning of K, M and G changed with version 0.9.6.0. Check your config
Name **CBandExceededURL**
Description Specifies a URL where mod_cband should redirect all requests to a virtualhost when the configured transfer limit is exceeded **NOTE** : If you don’t specify the exceeded URL location then standard 503 Service Unavailable will be sent
Context
Syntax CBandExceededURL**_ URL_**
Name **CBandExceededSpeed**
Description Specifies maximal speed to which mod_cband slows down a virtualhost when the configured transfer limit is exceeded
Context
Syntax CBandExceededSpeed**_ kbps_ _rps_ _max_conn_** kbps - maximal transfer speed in kbps or kB/s rps - maximal requests per second max_conn - maximal number of simultaneous connections **NOTE:** This feature is available from version** 0.9.6.0**
Name **CBandScoreboard**
Description Specifies virtualhost’s scoreboard file
Context
Syntax BandScoreboard**_ path_** **NOTE:** The path must be writeable for the apache-user
Name **CBandPeriod**
Description Specifies a period after which a virtualhost’s usages are cleared
Context
Syntax CBandPeriod**_ period_** period - available units:** S (seconds), M (minutes), H (hours), D (days), W (weeks)**
Example CBandPeriod 1W CBandPeriod 14D CBandPeriod 60M
Name **CBandPeriodSlice**
Description Specifies the period slice length
Default slice_len = limit
Context
Syntax CBandPeriodSlice**_ slice_length_**
Example CBandLimit 100G CBandPeriod 4W CBandPeriodSlice 1WA period will be divided into 4 small slices (4W/1W = 4). Each slice has 100G/4=25G bandwidth limit. After 1W slice limit will be 50G, after 2W will be 75G …
Name
Description Define a new cband user
Context Server config
Syntax <**_CBandUser user_name_**>
Name **CBandUserSpeed**
Description Specifies maximal speed for a cband user
Context
Syntax CBandUserSpeed**_ kbps_ _rps_ _max_conn_** kbps - maximal transfer speed in kbps or kB/s rps - maximal requests per second max_conn - maximal number of simultaneous connections
Example CBandUserSpeed 100kb/s 10 5 Specifies maximal speed 100 kB/s (100 * 1024 bytes per second), maximal 10 requests per second and 5 open connections **NOTE:** This feature is available from version** 0.9.6.0**
Name **CBandUserLimit**
Description Specifies bandwidth limit for a cband user
Context
Syntax CBandUserLimit**_ limit_** limit - bandwidth quota size, available units:** K (kilo), M (mega), G (giga), Ki (kibi), Mi (mebi), Gi (gibi)**
Example CBandUserLimit 10M Specifies 10 * 1000 * 1000 bytes bandwidth quota CBandUserLimit 10Mi Specifies 10 * 1024 * 1024 bytes bandwidth quota **IMPORTANT NOTE** : the meaning of K, M and G changed with version 0.9.6.0. Check your config
Name **CBandUserClassLimit**
Description Specifies bandwidth limit for a cband user’s destination class
Context
Syntax CBandUserClassLimit**_ class_name_ _limit_** class_name - the name of defined class limit - bandwidth quota size, available units:** K (kilo), M (mega), G (giga), Ki (kibi), Mi (mebi), Gi (gibi)** **IMPORTANT NOTE** : the meaning of K, M and G changed with version 0.9.6.0. Check your config
Name **CBandUserExceededURL**
Description Specifies a URL where mod_cband should redirect all requests to user’s virtualhost when the configured transfer limit is exceeded **NOTE** : If you don’t specify the exceeded URL location then standard 503 Service Unavailable will be sent
Context
Syntax CBandUserExceededURL**_ URL_**
Name **CBandUserExceededSpeed**
Description Specifies maximal speed to which mod_cband slows down user when the configured transfer limit is exceeded **NOTE:** CBandUserExceededURL must not be used if you want to only slow down user’s pages with CBandUserExceededSpeed directive
Context
Syntax CBandUserExceededSpeed**_ kbps_ _rps_ _max_conn_** kbps - maximal transfer speed in kbps or kB/s rps - maximal requests per second max_conn - maximal number of simultaneous connections **NOTE:** This feature is available from version** 0.9.6.0**
Name **CBandUserScoreboard**
Description Specifies a user’s scoreboard file
Context
Syntax CBandUserScoreboard**_ path_** **NOTE:** The path must be writeable for the apache-user
Name **CBandUserPeriod**
Description Specifies a period after which a user’s usages are cleared
Context
Syntax CBandUserPeriod**_ period_** period - available units:** S (seconds), M (minutes), H (hours), D (days), W (weeks)**
Example CBandUserPeriod 1W CBandUserPeriod 14D CBandUserPeriod 60M
Name **CBandUserPeriodSlice**
Description Specifies a period slice length
Default slice_len = limit
Context
Syntax CBandUserPeriodSlice**_ slice_length_**
Example CBandUserLimit 100G CBandUserPeriod 4W CBandUserPeriodSlice 1W A period will be divided into 4 small slices (4W/1W = 4). Each slice has 100G/4=25G bandwidth limit. After 1W slice limit will be 50G, after 2W will be 75G …

Status Handler Configuration Example

To view actual bandwidth limits, usages, users, scoreboards, add the following lines into the config file:

1
2
3
4
5
6
<Location /cband-status>
SetHandler cband-status
</Location>
<Location /cband-status-me>
SetHandler cband-status-me
</Location>

Then you can access the status page with a URL like:

http://server_name/cband-status http://server_name/cband-status-me

In versions >=0.9.5-rc1 you can also view /cband-status handler in the XML format :

http://server_name/cband-status?xml http://server_name/cband-status-me?xml

Bandwidth Speed Configuration Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<VirtualHost *:80>
    DocumentRoot /var/www/xyz.org/
    ServerName xyz.org
    CustomLog /var/log/apache2/xyz.org.access combined
    ErrorLog /var/log/apache2/xyz.org.access.error
    RewriteEngine On
    RewriteOptions inherit

  # Maximal 1024kbps speed for this virtualhost
  # Maximal 10 requests per second for this virtualhost
  # Maximal 30 open connections for this virtualhost

  **CBandSpeed 1024 10 30**

  # Maximal 10kB/s speed, 3 requests/s and 2 open connections for any remote client
  **CBandRemoteSpeed 10kb/s 3 2**

  # Maximal 20kB/s speed, 2 requests/s and 3 open connections for remote
  # clients from class googlebot_class :P
  **CBandClassRemoteSpeed googlebot_class 20kb/s 2 3**
</VirtualHost>

Bandwidth Quota Configuration Example

per-virtualhost bandwidth limiting configuration

Next, you may define virtualhost’s bandwidth limits, URL location and the path to scoreboard files for individual virtualhosts:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# specify default 'bandwidth exceeded' location
**CBandDefaultExceededURL http://haha.org/bandwidth_exceeded.html**

<VirtualHost *:80>
    DocumentRoot /var/www/xyz.org/
    ServerName xyz.org
    CustomLog /var/log/apache2/xyz.org.access combined
    ErrorLog /var/log/apache2/xyz.org.access.error
    RewriteEngine On
    RewriteOptions inherit

    # 100MB virtualhost bandwidth limit
    **CBandLimit 100000**

    # redirect to http://abc.org/bandwidth_exceeded.html
    # when the limit has been reached
    **CBandExceededURL http://abc.org/bandwidth_exceeded.html**

    # virtualhost's scoreboard file
    **CBandScoreboard /var/run/apache2/xyz.org.scoreboard**

    # a period of time after which the scoreboard will be cleared (30 minutes)
    # (only in >=0.9.5-rc2)
    **CBandPeriod 30M**
</VirtualHost>

per-user bandwidth limiting configuration (only in versions >=0.9.1)

In versions >=0.9.1 you can define limits for users and assign virtualhosts to them


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
**# define user 'dembol'**
<CBandUser dembol>
    # 200MB bandwidth limit for user 'dembol'
    **CBandUserLimit 200000**

    # redirect to http://abc.org/bandwidth_exceeded.html
    # when the limit has been reached
    **CBandUserExceededURL http://abc.org/bandwidth_exceeded.html**

    # user's scoreboard file
    **CBandUserScoreboard /var/run/apache2/dembol.scoreboard**

    # a period of time after which the scoreboard will be cleared (5 weeks)
    # (only in >=0.9.5-rc2)
    **CBandUserPeriod 5W**
</CBandUser>

1
2
3
4
5
6
7
8
9
10
11
12
13
**# assign virtualhost 'xyz.org' to user 'dembol'**
<VirtualHost *:80>
    ServerName xyz.org
    # Specify virtualhost's owner
    **CBandUser dembol**
</VirtualHost>

**# assign virtualhost 'aga.org' to user 'dembol'**
<VirtualHost *:80>
    ServerName aga.org
    # Specify virtualhost's owner
    **CBandUser dembol**
</VirtualHost>

per-user and per-virtualhost bandwidth limiting configuration (only in versions >=0.9.1)

In versions >=0.9.1 you can also mix per-user and per-virtualhost bandwidth limiting techniques


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
**# define user 'dembol'**
**CBandUser dembol**
    # 200MB bandwidth limit for user 'dembol'
    **CBandUserLimit 200000**

    # redirect to http://abc.org/bandwidth_exceeded.html
    # when the limit has been reached
    **CBandUserExceededURL http://abc.org/bandwidth_exceeded.html**

    # user's scoreboard file
    **CBandUserScoreboard /var/run/apache2/dembol.scoreboard**

    # a period of time after which the scoreboard will be cleared (4 days)
    # (only in >=0.9.5-rc2)
    **CBandUserPeriod 4D**
</CBandUser>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
**# assign virtualhost 'xyz.org' to user 'dembol'**
<VirtualHost *:80>
    ServerName xyz.org
    # Specify virtualhost's owner
    **CBandUser dembol**

    # 100MB virtualhost bandwidth limit
    **CBandLimit 100000**

    # redirect to http://abc.org/bandwidth_exceeded.html
    # when the limit has been reached
    **CBandExceededURL http://abc.org/bandwidth_exceeded.html**

    # virtualhost's scoreboard file
    **CBandUserScoreboard /var/run/apache2/dembol.scoreboard**

    # a period of time after which the scoreboard will be cleared (50 minutes)
    # (only in >=0.9.5-rc2)
    **CBandPeriod 50M**
</VirtualHost>

**# assign virtualhost 'aga.org' to user 'dembol'**
<VirtualHost *:80>
    ServerName aga.org
    # Specify virtualhost's owner
    **CBandUser dembol**
</VirtualHost>

per-destination bandwidth limiting configuration (only in >=0.9.5-rc1 versions)

In >= 0.9.5-rc1 you can limit traffic to some destination classes. The destination classes are defined by section. The limits for the classes are specified by CBandClassLimit and CBandUserClassLimit commands


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
# define 'class_1'

<CBandClass class_1>
    CBandClassDst 217.172.231.67
    CBandClassDst 127/8
    CBandClassDst 192.168.0.0/24
    CBandClassDst 10.0.0.20
</CBandClass>

# define 'class_2'
<CBandClass class_2>
    CBandClassDst 192.168.100.100
    CBandClassDst 153.19/16
</CBandClass>

<CBandUser dembol>

    CBandUserLimit 1000000
    CBandUserExceededURL http://edns.pl/bandwidth_exceeded.html
    CBandUserScoreboard /home/dembol/write/user.dembol.scoreboard

    # 500MB limit for 'class_2'
    CBandUserClassLimit class_2 500000
</CBandUser>

<VirtualHost *:80>
    ...
    CBandUser dembol

    # 1GB limit for 'class_1'
    CBandClassLimit class_1 1000000

    # a period of time after which the scoreboard will be cleared (120 seconds)
    # (only in >=0.9.5-rc2)
    **CBandPeriod 120S**
</VirtualHost>

Configuration file example

An example of the Apache 2 vhosts.conf file for the mod_cband is available  here

Comments