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. 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 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 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 op‐
56 tionally matching its value, too) rather than those that have the same
57 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 de‐
79 nied 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 being 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 minimum 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 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 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 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 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 de‐
153 nied).
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 (allow list). All
170 rules must define the same action. pcre is case sensitive.
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 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 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 in‐
209 ternal 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, de‐
224 fault 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 ac‐
247 tion 'drop' if you want mod_qos to remove this control header from the
248 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 ['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 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 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 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 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 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 QS_SetEnvStatus (deprecated, use QS_SetEnvIfStatus)
314 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 QS_SetEnvResBody (deprecated, use QS_SetEnvIfResBody)
327 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 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 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 QS_UnsetReqHeader <header name>, Removes the specified header from the
342 request.
343 QS_UnsetResHeader <header name>, Removes the specified header from the
345 response.
346 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 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 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 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 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 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 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 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 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 QS_ClientEventBlockExcludeIP <addr>, excludes an IP address or address
390 range from being limited by QS_ClientEventBlockCount.
391 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 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 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 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 QS_ClientSerialize, serializes requests having the QS_Serialize vari‐
415 able set if they are coming from the same IP address.
416 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 QS_ClientGeoCountryDB <path>, path to the geograpical database file.
423 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 QS_ErrorPage <url>, defines a custom error page.
433 QS_ErrorResponseCode <code>, defines the HTTP response code which is
435 used when a request is denied, default is 500.
436 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 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 QS_LogEnv 'on'|'off', enables logging of environment variables.
446 QS_SupportIPv6 'on'|'off', enables IPv6 address support. Default is on.
448 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 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 QS_DisableHandler 'on'|'off', disables the qos-viewer and qos-console
458 for a virtual host
459 QS_Chroot <path>, change root directory.
461 QS_Status 'on'|'off', writes a log message containing server statistics
463 once every minute. Default is off.
464 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 QSLog <arg>, used to configure a global (per Apache instance) 'qslog'
470 logger.
471
473 Pascal Buchbinder, http://mod-qos.sourceforge.net/
474mod_qos Apache Module November 2021 MOD_QOS(1)