"SfR Fresh" - the SfR Freeware/Shareware Archive 
Member "mod-cband-0.9.7.5/doc/documentation.txt" of archive mod-cband-0.9.7.5.tgz:
As a special service "SfR Fresh" has tried to format the requested source page into HTML format using source code syntax highlighting with prefixed line numbers.
Alternatively you can here view or download the uninterpreted source code file.
That can be also achieved for any archive member file by clicking within an archive contents listing on the first character of the file(path) respectively on the according byte size field.
1
2 mod_cband - A per-user, per-virtualhost and per-destination bandwidth
3 limiter for the Apache HTTP Server Version 2
4
5
6 Documentation
7 =============
8
9
10 1. Units accepted in various directives:
11
12 * transfer speeds:
13 o kbps, Mbps, Gbps - multiples of "bits per second", respectively: 1024, 1024*1024 and 1024*1024*1024 bps
14 o kb/s, Mb/s, Gb/s - multiples of "bytes per second", respectively: 1024, 1024*1024 and 1024*1024*1024 b/s
15 o defaults to kbps
16
17 * transfer quotas:
18 o K, M, G - multiples of bytes, respectively: 1000, 1000*1000 and 1000*1000*1000 bytes
19 o Ki, Mi, Gi - multiples of bytes, respectively: 1024, 1024*1024 and 1024*1024*1024 bytes
20 o defaults to K
21
22 * time periods:
23 o S, M, H, D, W - multiples of seconds: Seconds, Minutes, Hours, Days, Weeks; respectively: 1, 60, 3600, 86400, 604800 seconds
24 o defaults to S
25
26
27 2. Directives
28
29 Name CBandDefaultExceededURL
30 Description Default URL where mod_cband should redirect all requests to the virtualhost or
31 user when the configured transfer limit is exceeded
32 NOTE: If you don't specify the exceeded URL location then standard 503 Service Unavailable
33 will be sent
34 Context Server config
35 Syntax CBandDefaultExceededURL URL
36
37
38 Name CBandDefaultExceededCode
39 Description The http code sent to the user when the configured transfer is exceeded
40 Context Server config
41 Syntax CBandDefaultExceededCode HTTP_CODE
42 Example CBandDefaultExceededCode 509
43
44
45 Name CBandScoreFlushPeriod
46 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
47 Default 1
48 Context Server config
49 Syntax CBandScoreFlushPeriod number_of_requests
50 Example CBandScoreFlushPeriod 100
51 Any virtualhost's or user's scoreboard will be saved after 100 requests
52
53
54 Name CBandSpeed
55 Description Specifies a maximal speed for a virtualhost
56 Context <Virtualhost>
57 Syntax CBandSpeed kbps rps max_conn
58 kbps - maximal transfer speed in [kMG]bps or [kMG]B/s
59 rps - maximal requests per second
60 max_conn - maximal number of simultaneous connections
61 Example CBandSpeed 1024 10 30
62 Specifies maximal speed 1024kbps (1024 * 1024 bits per second),
63 maximal 10 requests per second and with a maximum of 30 open connections
64 NOTE: This feature is available from version 0.9.6.0
65
66
67 Name CBandRemoteSpeed
68 Description Specifies maximal speed for any remote client
69 Context <Virtualhost>
70 Syntax CBandRemoteSpeed kbps rps max_conn
71 kbps - maximal transfer speed in [kMG]bps or [kMG]B/s
72 rps - maximal requests per second
73 max_conn - maximal number of simultaneous connections
74 Example CBandRemoteSpeed 20kb/s 3 3
75 Specifies maximal speed 20kB/s (20 * 1024 bytes per second),
76 maximal 3 requests per second and 3 open connections for any remote client
77 NOTE: This feature is available from version 0.9.6.1-rc2
78
79
80 Name CBandClassRemoteSpeed
81 Description Specifies maximal speed for any remote client from some destination class
82 Context <Virtualhost>
83 Syntax CBandClassRemoteSpeed class_name kbps rps
84 class_name - name of defined destination class
85 kbps - maximal transfer speed in kbps or kB/s
86 rps - maximal requests per second
87 max_conn - maximal number of simultaneous connections
88 Example <CBandClass googlebot_class>
89 CBandClassDst 66.249.64/24
90 CBandClassDst 66.249.65/24
91 CBandClassDst 66.249.79/24
92 </CBandClass>
93 CBandClassRemoteSpeed googlebot_class 20kb/s 2 3
94
95 Specifies maximal speed 20kB/s (20 * 1024 bytes per second),
96 maximal 2 requests per second and 3 open connections for any remote client from
97 class googlebot_class
98 NOTE: This feature is available from version 0.9.6.1-rc2
99
100
101 Name CBandRandomPulse
102 Description Turns On or Off the random pulse generator for data sending
103 Random pulse generator is a part of the speed-limiting implementation of mod_cband.
104 This directive changes the way a connection's speed is determined and enforced.
105 The connections' speeds are measured within some time period and then provided for in
106 that period. When r.p.g. is enabled this period is chosen randomly,
107 providing for a statisticaly saner load distribution. Disabling this causes spikes both in
108 bandwidth and cpu usages
109 Context Global
110 Syntax CBandRandomPulse On/Off
111
112
113 Name CBandLimit
114 Description Specifies bandwidth limit for virtualhost
115 Context <Virtualhost>
116 Syntax CBandLimit limit
117 limit - bandwidth quota size, available units: K (kilo), M (mega), G (giga), Ki (kibi),
118 Mi (mebi), Gi (gibi)
119 Example CBandLimit 10M
120 Specifies 10 * 1000 * 1000 bytes bandwidth quota
121
122 CBandLimit 10Mi
123 Specifies 10 * 1024 * 1024 bytes bandwidth quota
124
125
126 Name CBandClassLimit
127 Description Specifies bandwidth limit for virtualhost's destination class
128 Context <Virtualhost>
129 Syntax CBandClassLimit class_name limit
130 class_name - the name of defined class
131 limit - bandwidth quota size, available units: K (kilo), M (mega), G (giga), Ki (kibi),
132 Mi (mebi), Gi (gibi)
133
134
135 Name CBandExceededURL
136 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
137 Context <Virtualhost>
138 Syntax CBandExceededURL URL
139
140
141 Name CBandExceededSpeed
142 Description Specifies maximal speed to which mod_cband slows down a virtualhost when the configured transfer limit is exceeded
143 Context <Virtualhost>
144 Syntax CBandExceededSpeed kbps rps max_conn
145 kbps - maximal transfer speed in kbps or kB/s
146 rps - maximal requests per second
147 max_conn - maximal number of simultaneous connections
148 NOTE: This feature is available from version 0.9.6.0
149
150
151 Name CBandScoreboard
152 Description Specifies virtualhost's scoreboard file
153 Context <Virtualhost>
154 Syntax CBandScoreboard path
155 NOTE: The path must be writeable for the apache-user
156
157
158 Name CBandPeriod
159 Description Specifies a period after which a virtualhost's usages are cleared
160 Context <Virtualhost>
161 Syntax CBandPeriod period
162 period - available units: S (seconds), M (minutes), H (hours), D (days), W (weeks)
163 Example CBandPeriod 1W
164 CBandPeriod 14D
165 CBandPeriod 60M
166
167
168 Name CBandPeriodSlice
169 Description Specifies the period slice length
170 Default slice_len = limit
171 Context <Virtualhost>
172 Syntax CBandPeriodSlice slice_length
173 Example CBandLimit 100G
174 CBandPeriod 4W
175 CBandPeriodSlice 1W
176 A period will be divided into 4 small slices (4W/1W = 4). Each slice has 100G/4=25G
177 bandwidth limit. After 1W slice limit will be 50G, after 2W will be 75G ...
178
179
180 Name <CBandUser>
181 Description Define a new cband user
182 Context Server config
183 Syntax <CBandUser user_name>
184
185
186 Name CBandUserSpeed
187 Description Specifies maximal speed for a cband user
188 Context <CBandUser>
189 Syntax CBandUserSpeed kbps rps max_conn
190 kbps - maximal transfer speed in kbps or kB/s
191 rps - maximal requests per second
192 max_conn - maximal number of simultaneous connections
193 Example CBandUserSpeed 100kb/s 10 5
194 Specifies maximal speed 100 kB/s (100 * 1024 bytes per second),
195 maximal 10 requests per second and 5 open connections
196 NOTE: This feature is available from version 0.9.6.0
197
198
199 Name CBandUserLimit
200 Description Specifies bandwidth limit for a cband user
201 Context <CBandUser>
202 Syntax CBandUserLimit limit
203 limit - bandwidth quota size, available units: K (kilo), M (mega), G (giga), Ki (kibi),
204 Mi (mebi), Gi (gibi)
205 Example CBandUserLimit 10M
206 Specifies 10 * 1000 * 1000 bytes bandwidth quota
207
208 CBandUserLimit 10Mi
209 Specifies 10 * 1024 * 1024 bytes bandwidth quota
210
211
212 Name CBandUserClassLimit
213 Description Specifies bandwidth limit for a cband user's destination class
214 Context <CBandUser>
215 Syntax CBandUserClassLimit class_name limit
216 class_name - the name of defined class
217 limit - bandwidth quota size, available units: K (kilo), M (mega), G (giga), Ki (kibi),
218 Mi (mebi), Gi (gibi)
219
220
221 Name CBandUserExceededURL
222 Description Specifies a URL where mod_cband should redirect all requests to user's virtualhost when the configured transfer limit is exceeded
223 NOTE: If you don't specify the exceeded URL location then standard 503 Service Unavailable will be sent
224 Context <CBandUser>
225 Syntax CBandUserExceededURL URL
226
227
228 Name CBandUserExceededSpeed
229 Description Specifies maximal speed to which mod_cband slows down user when the configured transfer limit is exceeded
230 NOTE: CBandUserExceededURL must not be used if you want to only slow down user's pages with
231 CBandUserExceededSpeed directive
232 Context <CBandUser>
233 Syntax CBandUserExceededSpeed kbps rps max_conn
234 kbps - maximal transfer speed in kbps or kB/s
235 rps - maximal requests per second
236 max_conn - maximal number of simultaneous connections
237 NOTE: This feature is available from version 0.9.6.0
238
239
240 Name CBandUserScoreboard
241 Description Specifies a user's scoreboard file
242 Context <CBandUser>
243 Syntax CBandUserScoreboard path
244 NOTE: The path must be writeable for the apache-user
245
246
247 Name CBandUserPeriod
248 Description Specifies a period after which a user's usages are cleared
249 Context <CBandUser>
250 Syntax CBandUserPeriod period
251 period - available units: S (seconds), M (minutes), H (hours), D (days), W (weeks)
252 Example CBandUserPeriod 1W
253 CBandUserPeriod 14D
254 CBandUserPeriod 60M
255
256
257 Name CBandUserPeriodSlice
258 Description Specifies a period slice length
259 Default slice_len = limit
260 Context <CBandUser>
261 Syntax CBandUserPeriodSlice slice_length
262 Example CBandUserLimit 100G
263 CBandUserPeriod 4W
264 CBandUserPeriodSlice 1W
265 A period will be divided into 4 small slices (4W/1W = 4). Each slice has 100G/4=25G
266 bandwidth limit. After 1W slice limit will be 50G, after 2W will be 75G ...
267
268
269 3. Status Handler Configuration Example
270 To view actual bandwidth limits, usages, users, scoreboards, add the following lines into the config file:
271
272 <Location /cband-status>
273 SetHandler cband-status
274 </Location>
275
276 <Location /cband-status-me>
277 SetHandler cband-status-me
278 </Location>
279
280 Then you can access the status page with a URL like:
281 http://server_name/cband-status
282 http://server_name/cband-status-me
283
284 An example of the cband-status is available here
285 An example of the cband-status-me is available here
286
287 In versions >=0.9.5-rc1 you can also view /cband-status handler in the XML format:
288
289 http://server_name/cband-status?xml
290 http://server_name/cband-status-me?xml
291
292 An example of the cband-status in the XML format is available here
293 An example of the cband-status-me in the XML format is available here
294
295
296 4. Bandwidth Speed Configuration Example
297
298 <VirtualHost *:80>
299 DocumentRoot /var/www/xyz.org/
300 ServerName xyz.org
301 CustomLog /var/log/apache2/xyz.org.access combined
302 ErrorLog /var/log/apache2/xyz.org.access.error
303 RewriteEngine On
304 RewriteOptions inherit
305
306 # Maximal 1024kbps speed for this virtualhost
307 # Maximal 10 requests per second for this virtualhost
308 # Maximal 30 open connections for this virtualhost
309 CBandSpeed 1024 10 30
310
311 # Maximal 10kB/s speed, 3 requests/s and 2 open connections for any remote client
312 CBandRemoteSpeed 10kb/s 3 2
313
314 # Maximal 20kB/s speed, 2 requests/s and 3 open connections for remote
315 # clients from class googlebot_class :P
316 CBandClassRemoteSpeed googlebot_class 20kb/s 2 3
317 </VirtualHost>
318
319 5. Bandwidth Quota Configuration Example
320 per-virtualhost bandwidth limiting configuration
321 Next, you may define virtualhost's bandwidth limits, URL location and the path to scoreboard files for individual virtualhosts:
322
323 # specify default 'bandwidth exceeded' location
324 CBandDefaultExceededURL http://haha.org/bandwidth_exceeded.html
325
326 <VirtualHost *:80>
327 DocumentRoot /var/www/xyz.org/
328 ServerName xyz.org
329 CustomLog /var/log/apache2/xyz.org.access combined
330 ErrorLog /var/log/apache2/xyz.org.access.error
331 RewriteEngine On
332 RewriteOptions inherit
333
334 # 100MB virtualhost bandwidth limit
335 CBandLimit 100000
336
337 # redirect to http://abc.org/bandwidth_exceeded.html
338 # when the limit has been reached
339 CBandExceededURL http://abc.org/bandwidth_exceeded.html
340
341 # virtualhost's scoreboard file
342 CBandScoreboard /var/run/apache2/xyz.org.scoreboard
343
344 # a period of time after which the scoreboard will be cleared (30 minutes)
345 # (only in >=0.9.5-rc2)
346 CBandPeriod 30M
347 </VirtualHost>
348
349
350 per-user bandwidth limiting configuration (only in versions >=0.9.1)
351 In versions >=0.9.1 you can define limits for users and assign virtualhosts to them
352
353 # define user 'dembol'
354 <CBandUser dembol>
355 # 200MB bandwidth limit for user 'dembol'
356 CBandUserLimit 200000
357
358 # redirect to http://abc.org/bandwidth_exceeded.html
359 # when the limit has been reached
360 CBandUserExceededURL http://abc.org/bandwidth_exceeded.html
361
362 # user's scoreboard file
363 CBandUserScoreboard /var/run/apache2/dembol.scoreboard
364
365 # a period of time after which the scoreboard will be cleared (5 weeks)
366 # (only in >=0.9.5-rc2)
367 CBandUserPeriod 5W
368 </CBandUser>
369
370 # assign virtualhost 'xyz.org' to user 'dembol'
371 <VirtualHost *:80>
372 ServerName xyz.org
373 # Specify virtualhost's owner
374 CBandUser dembol
375 </VirtualHost>
376
377 # assign virtualhost 'aga.org' to user 'dembol'
378 <VirtualHost *:80>
379 ServerName aga.org
380 # Specify virtualhost's owner
381 CBandUser dembol
382 </VirtualHost>
383
384
385 per-user and per-virtualhost bandwidth limiting configuration (only in versions >=0.9.1)
386 In versions >=0.9.1 you can also mix per-user and per-virtualhost bandwidth limiting techniques
387
388 # define user 'dembol'
389 <CBandUser dembol>
390 # 200MB bandwidth limit for user 'dembol'
391 CBandUserLimit 200000
392
393 # redirect to http://abc.org/bandwidth_exceeded.html
394 # when the limit has been reached
395 CBandUserExceededURL http://abc.org/bandwidth_exceeded.html
396
397 # user's scoreboard file
398 CBandUserScoreboard /var/run/apache2/dembol.scoreboard
399
400 # a period of time after which the scoreboard will be cleared (4 days)
401 # (only in >=0.9.5-rc2)
402 CBandUserPeriod 4D
403 </CBandUser>
404
405 # assign virtualhost 'xyz.org' to user 'dembol'
406 <VirtualHost *:80>
407 ServerName xyz.org
408 # Specify virtualhost's owner
409 CBandUser dembol
410
411 # 100MB virtualhost bandwidth limit
412 CBandLimit 100000
413
414 # redirect to http://abc.org/bandwidth_exceeded.html
415 # when the limit has been reached
416 CBandExceededURL http://abc.org/bandwidth_exceeded.html
417
418 # virtualhost's scoreboard file
419 CBandScoreboard /var/run/apache2/xyz.org.scoreboard
420
421 # a period of time after which the scoreboard will be cleared (50 minutes)
422 # (only in >=0.9.5-rc2)
423 CBandPeriod 50M
424 </VirtualHost>
425
426 # assign virtualhost 'aga.org' to user 'dembol'
427 <VirtualHost *:80>
428 ServerName aga.org
429 # Specify virtualhost's owner
430 CBandUser dembol
431 </VirtualHost>
432
433
434 per-destination bandwidth limiting configuration (only in >=0.9.5-rc1 versions)
435 In >= 0.9.5-rc1 you can limit traffic to some destination classes. The destination classes are defined by <CBandClass class_name> section. The limits for the classes are specified by CBandClassLimit and CBandUserClassLimit commands
436
437 # define 'class_1'
438 <CBandClass class_1>
439 CBandClassDst 217.172.231.67
440 CBandClassDst 127/8
441 CBandClassDst 192.168.0.0/24
442 CBandClassDst 10.0.0.20
443 </CBandClass>
444
445 # define 'class_2'
446 <CBandClass class_2>
447 CBandClassDst 192.168.100.100
448 CBandClassDst 153.19/16
449 </CBandClass>
450
451 <CBandUser dembol>
452 CBandUserLimit 1000000
453 CBandUserExceededURL http://edns.pl/bandwidth_exceeded.html
454 CBandUserScoreboard /home/dembol/write/user.dembol.scoreboard
455
456 # 500MB limit for 'class_2'
457 CBandUserClassLimit class_2 500000
458 </CBandUser>
459
460 <VirtualHost *:80>
461 ...
462 CBandUser dembol
463
464 # 1GB limit for 'class_1'
465 CBandClassLimit class_1 1000000
466
467 # a period of time after which the scoreboard will be cleared (120 seconds)
468 # (only in >=0.9.5-rc2)
469 CBandPeriod 120S
470 </VirtualHost>
471