1MOD_QOS(1)                          mod_qos                         MOD_QOS(1)
2
3
4

NAME

6       mod_qos - quality of service module for the Apache Web server
7

DESCRIPTION

9       mod_qos is a quality of service module for the Apache web server imple‐
10       menting control mechanisms that can provide different levels of  prior‐
11       ity to different HTTP requests.
12

OPTIONS

14       QS_LocRequestLimitDefault   <number>,   defines  the  default  for  the
15       QS_LocRequestLimit and QS_LocRequestLimitMatch directive.
16
17       QS_LocRequestLimit <location> <number>, defines the maximum  number  of
18       concurrent  requests  allowed to access the specified location. Default
19       is defined by the QS_LocRequestLimitDefault directive.
20
21       QS_LocRequestPerSecLimit <location> <number>, defines the allowed  num‐
22       ber  of  requests  per  second  to  a location. Requests are limited by
23       adding a delay to each requests. This directive should be used in  con‐
24       junction with QS_LocRequestLimit only.
25
26       QS_LocKBytesPerSecLimit  <location> <kbytes>, defines the allowed down‐
27       load bandwidth to the defined kbytes per second. Responses areslowed by
28       adding  a  delay  to each response (non-linear, bigger files get longer
29       delay than smaller ones). This directive should be used in  conjunction
30       with QS_LocRequestLimit only.
31
32       QS_LocRequestLimitMatch <regex> <number>, defines the number of concur‐
33       rent requests to the uri (path and query) pattern. Default  is  defined
34       by the QS_LocRequestLimitDefault directive.
35
36       QS_LocRequestPerSecLimitMatch  <regex>  <number>,  defines  the allowed
37       number of requests per second to the uri (path and query) pattern.  Re‐
38       quests  are  limited by adding a delay to each requests. This directive
39       should be used in conjunction with QS_LocRequestLimitMatch only.
40
41       QS_LocKBytesPerSecLimitMatch  <regex>  <kbytes>,  defines  the  allowed
42       download  bandwidth  to the location matching the defined URL (path and
43       query) pattern. Responses are slowed down by adding a delay to each re‐
44       sponse  (non-linear,  bigger files get longer delay than smaller ones).
45       This directive should be used in conjunction  with  QS_LocRequestLimit‐
46       Match only.
47
48       QS_CondLocRequestLimitMatch  <regex>  <number>  <pattern>,  defines the
49       number of concurrent requests to the uri (path and query)  regex.  Rule
50       is  only enforced if the QS_Cond variable matches the specified pattern
51       (regex).
52
53       QS_EventRequestLimit <variable>[=<regex>] <number>, defines the  number
54       of  concurrent  events.  Directive works similar to QS_LocRequestLimit,
55       but counts the requests having the same environment variable  (and  op‐
56       tionally  matching its value, too) rather than those that have the same
57       URL pattern.
58
59       QS_EventPerSecLimit [!]<variable> <number>, defines how often  requests
60       may have the defined environment variable (literal string) set. It mea‐
61       sures the occurrences of the defined environment variable on a  request
62       per  seconds  level  and  tries to limit this occurrence to the defined
63       number. It works similar to  as  QS_LocRequestPerSecLimit,  but  counts
64       only  the  requests  with  the specified variable (or without it if the
65       variable name is prefixed by a '!').  If  a  request  matches  multiple
66       events,  the rule with the lowest bandwidth is applied. Events are lim‐
67       ited by adding a delay to each request causing an  event.
68
69       QS_EventKBytesPerSecLimit [!]<variable> <kbytes>, throttles  the  down‐
70       load  bandwidth  of all requests having the defined variable set to the
71       defined kbytes per second. Responses are slowed by adding  a  delay  to
72       each  response  (non-linear, bigger files get longer delay than smaller
73       ones). By default, no limitation is active. This  directive  should  be
74       used  in  conjunction  with QS_EventRequestLimit only (you must use the
75       same variable name for both directives).
76
77       QS_EventLimitCount <env-variable> <number> <seconds>, defines the maxi‐
78       mum  number of events allowed within the defined time. Requests are de‐
79       nied when reaching this limitation for the specified time  (blocked  at
80       request level).
81
82       QS_CondEventLimitCount  <env-variable>  <number>  <seconds>  <pattern>,
83       same as QS_EventLimitCount but blocks  requests  only  if  the  QS_Cond
84       variable matches the specified pattern (regex).
85
86       QS_SrvMaxConn  <number>,  defines  the maximum number of concurrent TCP
87       connections for this server (virtual host).
88
89       QS_SrvMaxConnClose <number>[%], defines the maximum number  of  concur‐
90       rent  TCP  connections  until  the  server disables keep-alive for this
91       server (closes the connection after each requests. You may specify  the
92       number  of connections as a percentage of MaxClients if adding the suf‐
93       fix '%' to the specified value.
94
95       QS_SrvMaxConnPerIP <number> [<connections>], defines the maximum number
96       of  connections  per  source IP address for this server (virtual host).
97       'connections' defines the number of busy connections of the server (all
98       virtual hosts) to enable this limitation, default is 0.
99
100       QS_SrvMaxConnExcludeIP  <addr>, excludes an IP address or address range
101       from being limited.
102
103       QS_SrvMinDataRateIgnoreVIP tells the  QS_SrvMaxConnPerIP  directive  to
104       ignore  (if  set  to "on") the VIP status of clients. Default is "off",
105       which means that QS_SrvMaxConnPerIP is disabled for VIPs.
106
107       QS_SrvSerialize 'on'|'off' [<seconds>], ensures that not more than  one
108       request  having  the  QS_SrvSerialize  variable set is processed at the
109       same time by serializing them (process one after each other).
110
111       QS_SrvDataRateOff, disables the QS_SrvRequestRate and QS_SrvMinDataRate
112       enforcement  for  a  virtual  host (only port/address based but not for
113       name based virtual hosts).
114
115       QS_SrvRequestRate <bytes per seconds> [<max bytes per second>], defines
116       the  minimum upload throughput a client must generate. See also QS_Srv‐
117       MinDataRate.
118
119       QS_SrvMinDataRate <bytes per seconds> [<max bytes per second> [<connec‐
120       tions>]],  defines the minimum upload/download throughput a client must
121       generate (the bytes send/received by  the  client  per  seconds).  This
122       bandwidth is measured while transmitting the data (request line, header
123       fields, request body, or response  data).  The  client  connection  get
124       closed if the client does not fulfill the required data rate and the IP
125       address of the causing client get marked in order to  be  handled  with
126       low  priority  (see  the QS_ClientPrefer directive). The "max bytes per
127       second" activates dynamic minimum throughput control: The required min‐
128       imal  throughput  is  increased in parallel to the number of concurrent
129       clients sending/receiving data. The "max bytes per second"  setting  is
130       reached  when  the  number of sending/receiving clients is equal to the
131       MaxClients setting. The "connections" argument is used to  specify  the
132       number  of  busy TCP connections a server must have to enable this fea‐
133       ture (0 by default). No limitation is set by default.
134
135       QS_SrvMinDataRateOffEvent  '+'|'-'<env-variable>, disables the  minimal
136       data  rate  enfocement  (QS_SrvMinDataRate) for a certain connection if
137       the defined environment variable has been set. The '+' prefix  is  used
138       to  add a variable to the configuration while the '-' prefix is used to
139       remove a variable.
140
141       QS_SrvMinDataRateIgnoreVIP tells the QS_SrvMinDataRate directive to ig‐
142       nore  (if  set  to  "on")  the VIP status of clients. Default is "off",
143       which means that QS_SrvMinDataRate is disabled for VIPs.
144
145       QS_SrvSampleRate <seconds>, defines  the  sampling  rate  used  by  the
146       QS_SrvMinDataRate directive to measure the throughput of a connection.
147
148       QS_DenyRequestLine  '+'|'-'<id>  'log'|'deny'  <pcre>,  generic request
149       line (method, path, query and protocol) filter used to deny access  for
150       requests  matching  the  defined expression (pcre). '+' adds a new rule
151       while '-' removes a rule for a location. The  action  is  either  'log'
152       (access  is  granted but rule match is logged) or 'deny' (access is de‐
153       nied).
154
155       QS_DenyPath, same as QS_DenyRequestLine but applied to the path only.
156
157       QS_DenyQuery, same as QS_DenyRequestLine but applied to the query only.
158
159       QS_DenyEvent '+'|'-'<id> 'log'|'deny' [!]<variable>,  matches  requests
160       having the defined process environment variable set (or NOT set if pre‐
161       fixed by a '!'). The action taken for matching rules  is  either  'log'
162       (access  is  granted but the rule match is logged) or 'deny' (access is
163       denied).
164
165       QS_PermitUri, '+'|'-'<id> 'log'|'deny' <pcre>, generic  request  filter
166       applied  to the request uri (path and query). Only requests matching at
167       least one QS_PermitUri pattern are allowed. If a  QS_PermitUri  pattern
168       has been defined an the request does not match any rule, the request is
169       denied albeit of any server resource  availability  (allow  list).  All
170       rules must define the same action. pcre is case sensitive.
171
172       QS_DenyBody 'on'|'off', enabled body data filter (obsolete).
173
174       QS_DenyQueryBody 'on'|'off', enabled body data filter for QS_DenyQuery.
175
176       QS_PermitUriBody 'on'|'off', enabled body data filter for QS_PermitUri‐
177       Body.
178
179       QS_InvalidUrlEncoding 'log'|'deny'|'off', enforces correct URL decoding
180       in  conjunction  with the QS_DenyRequestLine, QS_DenyPath, and QS_Deny‐
181       Query directives. Default is "off".
182
183       QS_LimitRequestBody <bytes>, limits the allowed size of an HTTP request
184       message body.
185
186       QS_DenyDecoding  'uni',  enabled  additional  string decoding functions
187       which are applied before matching QS_Deny* and  QS_Permit*  directives.
188       Default is URL decoding (%xx, , '+').
189
190       QS_DenyInheritanceOff,  disable  inheritance of QS_Deny* and QS_Permit*
191       directives to a location.
192
193       QS_RequestHeaderFilter 'on'|'off'|'size', filters  request  headers  by
194       allowing  only  these  headers which match the request header rules de‐
195       fined by mod_qos. Request headers which do not  conform  these  defini‐
196       tions are either dropped or the whole request is denied. Custom request
197       headers may be added by the QS_RequestHeaderFilterRule directive. Using
198       the 'size' option, the header field max. size is verified only (similar
199       to LimitRequestFieldsize but using individual values  for  each  header
200       type) while the pattern is ignored.
201
202       QS_ResponseHeaderFilter  'on'|'off', filters response headers by allow‐
203       ing only these headers which match the request header rules defined  by
204       mod_qos.  Request  headers  which  do not conform these definitions are
205       dropped.
206
207       QS_RequestHeaderFilterRule <header name> 'drop'|'deny' <pcre>   <size>,
208       used  to  add custom request header filter rules which override the in‐
209       ternal filter rules of mod_qos. Directive is allowed in  global  server
210       context only.
211
212       QS_ResponseHeaderFilterRule  <header  name>  <pcre> <size>, used to add
213       custom response header filter rules which override the internal  filter
214       rules of mod_qos. Directive is allowed in global server context only.
215
216       QS_MileStone 'log'|'deny' <pattern> [<thinktime>], defines request line
217       patterns a client must access in the defined order as they are  defined
218       in the configuration file.
219
220       QS_MileStoneTimeout  <seconds>,  defines  the  time in seconds within a
221       client must reach the next milestone. Default are 3600 seconds.
222
223       QS_SessionCookieName <name>, defines a custom session cookie name,  de‐
224       fault is MODQOS.
225
226       QS_SessionCookiePath <path>, defines the cookie path, default is "/".
227
228       QS_SessionTimeout  <seconds>,  defines the session life time for a VIP.
229       It is only used for session based (cookie) VIP identification (not  for
230       IP based). Default is 3600 seconds.
231
232       QS_SessionKey  <string>,  secret  key  used for cookie encryption. Used
233       when using the same session cookie for multiple web servers (load  bal‐
234       ancing) or sessions should survive a server restart. By default, a ran‐
235       dom key is used which changes every server restart.
236
237       QS_VipHeaderName <name>[=<regex>]  [drop],  defines  an  HTTP  response
238       header  which marks a user as a VIP. mod_qos creates a session for this
239       user by setting a cookie, e.g., after successful  user  authentication.
240       Tests  optionally  its  value  against the provided regular expression.
241       Specify the action 'drop' if you want mod_qos to  remove  this  control
242       header from the HTTP response.
243
244       QS_VipIPHeaderName  <name>[=<regex>]  [drop],  defines an HTTP response
245       header which marks a client source IP address as a VIP.  Tests  option‐
246       ally its value against the provided regular expression. Specify the ac‐
247       tion 'drop' if you want mod_qos to remove this control header from  the
248       HTTP response.
249
250       QS_VipUser,  creates  a VIP session for users which have been authenti‐
251       cated by the Apache server, e.g., by the standard mod_auth* modules. It
252       works similar to the QS_VipHeaderName directive.
253
254       QS_VipIpUser,  marks  a source IP address as a VIP if the user has been
255       authenticated by the Apache server, e.g. by the standard mod_auth* mod‐
256       ules. It works similar to the QS_VipIPHeaderName directive.
257
258       QS_UserTrackingCookieName   <name>   [<path>]   [<domain>]  ['session']
259       ['jsredirect'], enables the user tracking cookie by defining  a  cookie
260       name. The "path" parameter is an option cookie check page which is used
261       to ensure the client accepts cookies. The "domain" option  defines  the
262       Domain attriibute for the Set-Cookie header. The option "session" indi‐
263       cates that the cookie shall be a session cookie expiring when the  user
264       closes it's browser. User tracking requires mod_unique_id. This feature
265       is disabled by default. Ignores QS_LogOnly.
266
267       QS_SetEnvIf   [!]<variable1>[=<regex>]    [[!]<variable2>]    [!]<vari‐
268       able=value>,  sets (or unsets) the 'variable=value' (literal string) if
269       variable1 (literal string) AND variable2 (literal string)  are  set  in
270       the  request  environment  variable  list (not case sensitive). This is
271       used to combine multiple variables to a new event type.  Alternatively,
272       a  regular  expression can be specified for variable1's value and vari‐
273       able2 must be omitted in order to simply set a new variable if the reg‐
274       ular expression matches.
275
276       QS_SetEnvIfCmpP     <env-variable1>     eq|ne|gt|lt     <env-variable2>
277       [!]<env-variable>[=<value>], sets the specified environment variable if
278       the specified env-variables are alphabetically or numerical equal (eq),
279       not equal (ne), greater (gt), less (lt).
280
281       QS_SetEnvIfQuery <regex> [!]<variable>[=value], directive  works  quite
282       similar  to  the  SetEnvIf directive of the Apache module mod_setenvif,
283       but the specified regex is applied against the query string portion  of
284       the  request  line.  The directive recognizes the occurrences of $1..$9
285       within value and replaces them by the sub-expressions  of  the  defined
286       regex pattern.
287
288       QS_SetEnvIfParp  <regex>  [!]<variable>[=value],  directive parsing the
289       request payload using the Apache module mod_parp. It  matches  the  re‐
290       quest URL query and the HTTP request message body data as well ('appli‐
291       cation/x-www-form-urlencoded',   'multipart/form-data',   and   'multi‐
292       part/mixed')  and  sets  the defined process variable (quite similar to
293       the QS_SetEnvIfQuery directive). The directive  recognizes  the  occur‐
294       rences  of $1..$9 within value and replaces them by the sub-expressions
295       of the defined regex pattern. This directive activates mod_parp for ev‐
296       ery  request  to  the virtual host. You may deactivate mod_parp for se‐
297       lected requests using the SetEnvIf directive: unset the variable 'parp'
298       to  do so. Important: request message body processing requires that the
299       server loads the whole request into its  memory  (at  least  twice  the
300       length  of  the message). You should limit the allowed size of the HTTP
301       request message body using the QS_LimitRequestBody directive when using
302       QS_SetEnvIfParp!
303
304       QS_SetEnvIfBody  <regex> [!]<variable>[=value], parses the request body
305       using the Apache module mod_parp. Specify the content types to  process
306       using  the mod_parp directive PARP_BodyData and ensure that mod_parp is
307       enabled using the SetEnvIf directive of the Apache module mod_setenvif.
308       You  should  limit the allowed size of HTTP requests message body using
309       the QS_LimitRequestBody directive when using  mod_parp.  The  directive
310       recognizes  the occurrence of $1 within the variable value and replaces
311       it by the sub-expressions of the defined regex pattern.
312
313       QS_SetEnvStatus (deprecated, use QS_SetEnvIfStatus)
314
315       QS_SetEnvIfStatus <status code> <variable>, adds  the  defined  request
316       environment variable if the HTTP status code matches the defined value.
317       The value 'QS_SrvMinDataRate' may be used as a special status  code  to
318       set  a QS_Block event in order to handle connection close events caused
319       by QS_SrvMinDataRate rules while the  status  'NullConnection'  may  be
320       used  to  mark connections which are closed before any HTTP request has
321       ever been received. The 'QS_SrvMaxConnPerIP' value may be used to count
322       QS_Block events for connections closed by the QS_SrvMaxConnPerIP direc‐
323       tive. The 'BrokenConnection' value may be  used  to  mark  clients  not
324       reading the full HTTP response.
325
326       QS_SetEnvResBody (deprecated, use QS_SetEnvIfResBody)
327
328       QS_SetEnvIfResBody <string> [!]<variable>, adds the defined request en‐
329       vironment variable (e.g. QS_Block) if the HTTP response  body  contains
330       the defined literal string. Supports only one pattern per location.
331
332       QS_SetEnv  <variable> <value>, sets the defined variable with the value
333       where the value string may contain  other  environment  variables  sur‐
334       rounded  by "${" and "}". The variable is only set if all defined vari‐
335       ables within the value can be resolved.
336
337       QS_SetReqHeader [!]<header name> <variable> ['late'], sets the  defined
338       HTTP  request  header to the request if the specified environment vari‐
339       able is set.
340
341       QS_UnsetReqHeader <header name>, Removes the specified header from  the
342       request.
343
344       QS_UnsetResHeader  <header name>, Removes the specified header from the
345       response.
346
347       QS_SetEnvResHeader <header name> [drop], sets the defined HTTP response
348       header  to the request environment variables. Deletes the header if the
349       action 'drop' has been specified.
350
351       QS_SetEnvResHeaderMatch <header name> <regex>, sets  the  defined  HTTP
352       response  header  to the request environment variables if the specified
353       regular expression (pcre) matches the header value.
354
355       QS_SetEnvRes <variable> <regex> <variable2>[=<value>], sets  the  envi‐
356       ronment  variable2  if the regular expression matches against the value
357       of the environment variable. Occurrences of $1..$9 within the value and
358       replace them by parenthesized subexpressions of the regular expression.
359
360       QS_RedirectIf  <variable>  <regex> [<code>:]<url>, redirects the client
361       to the configured url if the regular expression matches  the  value  of
362       the the environment variable.
363
364       QS_ClientEntries  <number>,  defines  the  number of individual clients
365       managed by mod_qos. Default is 50000. Directive is  allowed  in  global
366       server context only.
367
368       QS_ClientPrefer  [<percent>], prefers known VIP clients when server has
369       less than 80% (or the configured value) of free TCP  connections.  Pre‐
370       ferred  clients  are  VIP clients (or those without any negative penal‐
371       ties), see QS_VipHeaderName directive. Directive is allowed  in  global
372       server context only.
373
374       QS_ClientTolerance <percent>, defines the allowed tolerance (variation)
375       from a "normal" client (average) in percent. Default is 20%.  Directive
376       is allowed in global server context only.
377
378       QS_ClientContentTypes  <html>  <css/js> <images> <other> <304>, defines
379       the distribution of HTTP response content types a client  normally  re‐
380       ceives  when  accessing the server. mod_qos normally learns the average
381       behavior automatically by default but you may specify a static configu‐
382       ration  in  order  to  avoid  influences  by  a high number of abnormal
383       clients.
384
385       QS_ClientEventBlockCount <number> [<seconds>], defines the maximum num‐
386       ber  of  QS_Block  allowed within the defined time (default are 10 min‐
387       utes). Directive is allowed in global server context only.
388
389       QS_ClientEventBlockExcludeIP <addr>, excludes an IP address or  address
390       range from being limited by QS_ClientEventBlockCount.
391
392       QS_ClientEventLimitCount <number> [<seconds> [<variable>]], defines the
393       maximum number of the specified environment variable (QS_Limit  by  de‐
394       fault) allowed within the defined time (default are 10 minutes). Direc‐
395       tive is allowed in global server context only.
396
397       QS_CondClientEventLimitCount <number> <seconds>  <variable>  <pattern>,
398       defines  the  maximum  number of the specified environment variable al‐
399       lowed within the defined time. Directive  works  similar  as  QS_Clien‐
400       tEventLimitCount  but requests are only blocked if the QS_Cond variable
401       matches the defined pattern (regex). Directive  is  allowed  in  global
402       server context only.
403
404       QS_ClientEventPerSecLimit  <number>, defines the number events pro sec‐
405       onds on a per client (source IP) basis. Events are  identified  by  re‐
406       quests having the QS_Event variable set. Directive is allowed in global
407       server context only.
408
409       QS_ClientEventRequestLimit <number>, defines the allowed number of con‐
410       current  requests  coming from the same client source IP address having
411       the QS_EventRequest variable set. Directive is allowed in global server
412       context only.
413
414       QS_ClientSerialize,  serializes  requests having the QS_Serialize vari‐
415       able set if they are coming from the same IP address.
416
417       QS_ClientIpFromHeader <header>, defines a HTTP request header  to  read
418       the  client's  source IP address from (instead of taking the IP address
419       of the client opening the TCP connection). This may  be  used  for  the
420       QS_ClientEventLimitCount directive and QS_Country variable.
421
422       QS_ClientGeoCountryDB <path>, path to the geograpical database file.
423
424       QS_ClientGeoCountryPriv  <list>  <connections>  ['excludeUnknown'], de‐
425       fines a comma separated list of country codes for origin client IP  ad‐
426       dress  which are allowed to access the server if the number of busy TCP
427       connections reaches the defined number of connections while others  are
428       denied  access.  Clients whose IP can't be mapped to a country code can
429       be excluded from the limitation by configuring the 'excludeUnknown' ar‐
430       gument.
431
432       QS_ErrorPage <url>, defines a custom error page.
433
434       QS_ErrorResponseCode  <code>,  defines  the HTTP response code which is
435       used when a request is denied, default is 500.
436
437       QS_ForcedClose 'on'|'off', defines if mod_qos connection handler  shall
438       exit  with  an error code (on) or not. Default is on (except for Apache
439       2.4.49).
440
441       QS_LogOnly 'on'|'off', enables the log only mode of the module where no
442       limitations  are  enforced.  Default  is  off.  Directive is allowed in
443       global server context only.
444
445       QS_LogEnv 'on'|'off', enables logging of environment variables.
446
447       QS_SupportIPv6 'on'|'off', enables IPv6 address support. Default is on.
448
449       QS_SemMemFile <path>, optional path to a directory or file which  shall
450       be  used  for  file  based  samaphores/shared  memory usage. Default is
451       /var/tmp/.
452
453       QS_MaxClients  <number>,   optional   override   for   mod_qos's   Max‐
454       Clients/MaxRequestWorkers  calculation which defines the maximum number
455       of TCP connections the server can handle.
456
457       QS_DisableHandler 'on'|'off', disables the qos-viewer  and  qos-console
458       for a virtual host
459
460       QS_Chroot <path>, change root directory.
461
462       QS_Status 'on'|'off', writes a log message containing server statistics
463       once every minute. Default is off.
464
465       QS_EventCount 'on'|'off', enables error event  counting  (counters  are
466       shown in the machine-readable version of the status viewer). Default is
467       off.
468
469       QSLog <arg>, used to configure a global (per Apache  instance)  'qslog'
470       logger.
471

AUTHOR

473       Pascal Buchbinder, http://mod-qos.sourceforge.net/
474
475
476
477mod_qos Apache Module            November 2021                      MOD_QOS(1)
Impressum