1MOD_QOS(1) mod_qos MOD_QOS(1)
2
6 mod_qos - quality of service module for the Apache Web server
7
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
14 QS_LocRequestLimitDefault <number>, defines the default for the
15 QS_LocRequestLimit and QS_LocRequestLimitMatch directive.
16 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 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 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 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 QS_LocRequestPerSecLimitMatch <regex> <number>, defines the allowed
37 number of requests per second to the uri (path and query) pattern.
38 Requests are limited by adding a delay to each requests. This directive
39 should be used in conjunction with QS_LocRequestLimitMatch only.
40 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
44 response (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 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 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
56 optionally matching its value, too) rather than those that have the
57 same URL pattern.
58 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 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 QS_EventLimitCount <env-variable> <number> <seconds>, defines the maxi‐
78 mum number of events allowed within the defined time. Requests are
79 denied when reaching this limitation for the specified time (blocked at
80 request level).
81 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 QS_SrvMaxConn <number>, defines the maximum number of concurrent TCP
87 connections for this server (virtual host).
88 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 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 QS_SrvMaxConnExcludeIP <addr>, excludes an IP address or address range
101 from beeing limited.
102 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 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 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 QS_SrvRequestRate <bytes per seconds> [<max bytes per second>], defines
116 the minumum upload throughput a client must generate. See also QS_Srv‐
117 MinDataRate.
118 QS_SrvMinDataRate <bytes per seconds> [<max bytes per second> [<connec‐
120 tions>]], defines the minumum 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 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 QS_SrvMinDataRateIgnoreVIP tells the QS_SrvMinDataRate directive to
142 ignore (if set to "on") the VIP status of clients. Default is "off",
143 which means that QS_SrvMinDataRate is disabled for VIPs.
144 QS_SrvSampleRate <seconds>, defines the sampling rate used by the
146 QS_SrvMinDataRate directive to measure the throughput of a connection.
147 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
153 denied).
154 QS_DenyPath, same as QS_DenyRequestLine but applied to the path only.
156 QS_DenyQuery, same as QS_DenyRequestLine but applied to the query only.
158 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 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 (white list). All
170 rules must define the same action. pcre is case sensitve.
171 QS_DenyBody 'on'|'off', enabled body data filter (obsolete).
173 QS_DenyQueryBody 'on'|'off', enabled body data filter for QS_DenyQuery.
175 QS_PermitUriBody 'on'|'off', enabled body data filter for QS_PermitUri‐
177 Body.
178 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 QS_LimitRequestBody <bytes>, limits the allowed size of an HTTP request
184 message body.
185 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 QS_DenyInheritanceOff, disable inheritance of QS_Deny* and QS_Permit*
191 directives to a location.
192 QS_RequestHeaderFilter 'on'|'off'|'size', filters request headers by
194 allowing only these headers which match the request header rules
195 defined 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 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 QS_RequestHeaderFilterRule <header name> 'drop'|'deny' <pcre> <size>,
208 used to add custom request header filter rules which override the
209 internal filter rules of mod_qos. Directive is allowed in global server
210 context only.
211 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 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 QS_MileStoneTimeout <seconds>, defines the time in seconds within a
221 client must reach the next milestone. Default are 3600 seconds.
222 QS_SessionCookieName <name>, defines a custom session cookie name,
224 default is MODQOS.
225 QS_SessionCookiePath <path>, defines the cookie path, default is "/".
227 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 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 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 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
247 action 'drop' if you want mod_qos to remove this control header from
248 the HTTP response.
249 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 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 QS_UserTrackingCookieName <name> [<path>] [<domain>] ['session'],
259 enables the user tracking cookie by defining a cookie name. The "path"
260 parameter is an option cookie check page which is used to ensure the
261 client accepts cookies. The "domain" option defines the Domain attri‐
262 ibute for the Set-Cookie header. The option "session" indicates that
263 the cookie shall be a session cookie expiring when the user closes it's
264 browser. User tracking requires mod_unique_id. This feature is disabled
265 by default. Ignores QS_LogOnly.
266 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 specifed 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 QS_SetEnvIfQuery <regex> [!]<variable>[=value], directive works quite
277 similar to the SetEnvIf directive of the Apache module mod_setenvif,
278 but the specified regex is applied against the query string portion of
279 the request line. The directive recognizes the occurrences of $1..$9
280 within value and replaces them by the sub-expressions of the defined
281 regex pattern.
282 QS_SetEnvIfParp <regex> [!]<variable>[=value], directive parsing the
284 request payload using the Apache module mod_parp. It matches the
285 request URL query and the HTTP request message body data as well
286 ('application/x-www-form-urlencoded', 'multipart/form-data', and 'mul‐
287 tipart/mixed') and sets the defined process variable (quite similar to
288 the QS_SetEnvIfQuery directive). The directive recognizes the occur‐
289 rences of $1..$9 within value and replaces them by the sub-expressions
290 of the defined regex pattern. This directive activates mod_parp for
291 every request to the virtual host. You may deactivate mod_parp for
292 selected requests using the SetEnvIf directive: unset the variable
293 'parp' to do so. Important: request message body processing requires
294 that the server loads the whole request into its memory (at least twice
295 the length of the message). You should limit the allowed size of the
296 HTTP request message body using the QS_LimitRequestBody directive when
297 using QS_SetEnvIfParp!
298 QS_SetEnvIfBody <regex> [!]<variable>[=value], parses the request body
300 using the Apache module mod_parp. Specify the content types to process
301 using the mod_parp directive PARP_BodyData and ensure that mod_parp is
302 enabled using the SetEnvIf directive of the Apache module mod_setenvif.
303 You should limit the allowed size of HTTP requests message body using
304 the QS_LimitRequestBody directive when using mod_parp. The directive
305 recognizes the occurrence of $1 within the variable value and replaces
306 it by the sub-expressions of the defined regex pattern.
307 QS_SetEnvStatus (deprecated, use QS_SetEnvIfStatus)
309 QS_SetEnvIfStatus <status code> <variable>, adds the defined request
311 environment variable if the HTTP status code matches the defined value.
312 The value 'QS_SrvMinDataRate' may be used as a special status code to
313 set a QS_Block event in order to handle connection close events caused
314 by QS_SrvMinDataRate rules while the status 'NullConnection' may be
315 used to mark connections which are closed before any HTTP request has
316 ever been received. The 'QS_SrvMaxConnPerIP' value may be used to count
317 QS_Block events for connections closed by the QS_SrvMaxConnPerIP direc‐
318 tive. The 'BrokenConnection' value may be used to mark clients not
319 reading the full HTTP response.
320 QS_SetEnvResBody (deprecated, use QS_SetEnvIfResBody)
322 QS_SetEnvIfResBody <string> [!]<variable>, adds the defined request
324 environment variable (e.g. QS_Block) if the HTTP response body contains
325 the defined literal string. Supports only one pattern per location.
326 QS_SetEnv <variable> <value>, sets the defined variable with the value
328 where the value string may contain other environment variables sur‐
329 rounded by "${" and "}". The variable is only set if all defined vari‐
330 ables within the value can be resolved.
331 QS_SetReqHeader [!]<header name> <variable> ['late'], sets the defined
333 HTTP request header to the request if the specified environment vari‐
334 able is set.
335 QS_UnsetResHeader <header name>, Removes the specified response header.
337 QS_SetEnvResHeader <header name> [drop], sets the defined HTTP response
339 header to the request environment variables. Deletes the header if the
340 action 'drop' has been specified.
341 QS_SetEnvResHeaderMatch <header name> <regex>, sets the defined HTTP
343 response header to the request environment variables if the specified
344 regular expression (pcre) matches the header value.
345 QS_SetEnvRes <variable> <regex> <variable2>[=<value>], sets the envi‐
347 ronmet variable2 if the regular expression matches against the value of
348 the environment variable. Occurrences of $1..$9 within the value and
349 replace them by parenthesized subexpressions of the regular expression.
350 QS_RedirectIf <variable> <regex> [<code>:]<url>, redirects the client
352 to the configured url if the regular expression matches the value of
353 the the environment variable.
354 QS_ClientEntries <number>, defines the number of individual clients
356 managed by mod_qos. Default is 50000. Directive is allowed in global
357 server context only.
358 QS_ClientPrefer [<percent>], prefers known VIP clients when server has
360 less than 80% (or the configured value) of free TCP connections. Pre‐
361 ferred clients are VIP clients (or those without any negative penal‐
362 ties), see QS_VipHeaderName directive. Directive is allowed in global
363 server context only.
364 QS_ClientTolerance <percent>, defines the allowed tolerance (variation)
366 from a "normal" client (average) in percent. Default is 20%. Directive
367 is allowed in global server context only.
368 QS_ClientContentTypes <html> <css/js> <images> <other> <304>, defines
370 the distribution of HTTP response content types a client normaly
371 receives when accessing the server. mod_qos normally learns the average
372 behavior automatically by default but you may specify a static configu‐
373 ration in order to avoid influences by a high number of abnormal
374 clients.
375 QS_ClientEventBlockCount <number> [<seconds>], defines the maximum num‐
377 ber of QS_Block allowed within the defined time (default are 10 min‐
378 utes). Directive is allowed in global server context only.
379 QS_ClientEventBlockExcludeIP <addr>, excludes an IP address or address
381 range from beeing limited by QS_ClientEventBlockCount.
382 QS_ClientEventLimitCount <number> [<seconds> [<variable>]], defines the
384 maximum number of the specified environment variable (QS_Limit by
385 default) allowed within the defined time (default are 10 minutes).
386 Directive is allowed in global server context only.
387 QS_CondClientEventLimitCount <number> <seconds> <variable> <pattern>,
389 defines the maximum number of the specified environment variable
390 allowed within the defined time. Directive works similar as QS_Clien‐
391 tEventLimitCount but requests are only blocked if the QS_Cond variable
392 matches the defined pattern (regex). Directive is allowed in global
393 server context only.
394 QS_ClientEventPerSecLimit <number>, defines the number events pro sec‐
396 onds on a per client (source IP) basis. Events are identified by
397 requests having the QS_Event variable set. Directive is allowed in
398 global server context only.
399 QS_ClientEventRequestLimit <number>, defines the allowed number of con‐
401 current requests comming from the same client source IP address having
402 the QS_EventRequest variable set. Directive is allowed in global server
403 context only.
404 QS_ClientSerialize, serializes requests having the QS_Serialize vari‐
406 able set if they are comming from the same IP address.
407 QS_ClientIpFromHeader <header>, defines a HTTP request header to read
409 the client's source IP address from (instead of taking the IP address
410 of the client opening the TCP connection). This may be used for the
411 QS_ClientEventLimitCount directive and QS_Country variable.
412 QS_ClientGeoCountryDB <path>, path to the geograpical database file.
414 QS_ClientGeoCountryPriv <list> <connections>, defines a comma separated
416 list of country codes for origin client IP address which are allowed to
417 access the server if the number of busy TCP connections reaches the
418 defined number of connections.
419 QS_ErrorPage <url>, defines a custom error page.
421 QS_ErrorResponseCode <code>, defines the HTTP response code which is
423 used when a request is denied, default is 500.
424 QS_LogOnly 'on'|'off', enables the log only mode of the module where no
426 limitations are enforced. Default is off. Directive is allowed in
427 global server context only.
428 QS_SupportIPv6 'on'|'off', enables IPv6 address support. Default is on.
430 QS_SemMemFile <path>, optional path to a directory or file which shall
432 be used for file based samaphores/shared memory usage. Default is
433 /var/tmp/.
434 QS_DisableHandler 'on'|'off', disables the qos-viewer and qos-console
436 for a virtual host
437 QS_Chroot <path>, change root directory.
439 QS_Status 'on'|'off', writes a log message containing server statistics
441 once every minute. Default is off.
442 QS_EventCount 'on'|'off', enables error event counting (counters are
444 shown in the machine-readable version of the status viewer). Default is
445 off.
446 QSLog <arg>, used to configure a global (per Apache instance) 'qslog'
448 logger.
449
451 Pascal Buchbinder, http://mod-qos.sourceforge.net/
452mod_qos Apache Module June 2018 MOD_QOS(1)