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' <regular expression>,
149 generic request line (method, path, query and protocol) filter used to
150 deny access for requests matching the defined regular expression. '+'
151 adds a new rule while '-' removes a rule for a location. The action is
152 either 'log' (access is granted but rule match is logged) or 'deny'
153 (access is 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' <regular expression>, generic
166 request filter applied to the request uri (path and query). Only re‐
167 quests matching at least one QS_PermitUri pattern are allowed. If a
168 QS_PermitUri pattern has been defined an the request does not match any
169 rule, the request is denied albeit of any server resource availability
170 (allow list). All rules must define the same action. Regular expression
171 is case sensitive.
172 QS_DenyBody 'on'|'off', enabled body data filter (obsolete).
174 QS_DenyQueryBody 'on'|'off', enabled body data filter for QS_DenyQuery.
176 QS_PermitUriBody 'on'|'off', enabled body data filter for QS_PermitUri‐
178 Body.
179 QS_InvalidUrlEncoding 'log'|'deny'|'off', enforces correct URL decoding
181 in conjunction with the QS_DenyRequestLine, QS_DenyPath, and QS_Deny‐
182 Query directives. Default is "off".
183 QS_LimitRequestBody <bytes>, limits the allowed size of an HTTP request
185 message body.
186 QS_DenyDecoding 'uni', enabled additional string decoding functions
188 which are applied before matching QS_Deny* and QS_Permit* directives.
189 Default is URL decoding (%xx, , '+').
190 QS_DenyInheritanceOff, disable inheritance of QS_Deny* and QS_Permit*
192 directives to a location.
193 QS_RequestHeaderFilter 'on'|'off'|'size', filters request headers by
195 allowing only these headers which match the request header rules de‐
196 fined by mod_qos. Request headers which do not conform these defini‐
197 tions are either dropped or the whole request is denied. Custom request
198 headers may be added by the QS_RequestHeaderFilterRule directive. Using
199 the 'size' option, the header field max. size is verified only (similar
200 to LimitRequestFieldsize but using individual values for each header
201 type) while the pattern is ignored.
202 QS_ResponseHeaderFilter 'on'|'off', filters response headers by allow‐
204 ing only these headers which match the response header rules defined by
205 mod_qos. Response headers which do not conform these definitions are
206 dropped.
207 QS_RequestHeaderFilterRule <header name> 'drop'|'deny' <regular expres‐
209 sion> <size>, used to add custom request header filter rules which
210 override the internal filter rules of mod_qos. Directive is allowed in
211 global server context only.
212 QS_ResponseHeaderFilterRule <header name> <regular expression> <size>,
214 used to add custom response header filter rules which override the in‐
215 ternal filter rules of mod_qos. Directive is allowed in global server
216 context only.
217 QS_MileStone 'log'|'deny' <pattern> [<thinktime>], defines request line
219 patterns a client must access in the defined order as they are defined
220 in the configuration file.
221 QS_MileStoneTimeout <seconds>, defines the time in seconds within a
223 client must reach the next milestone. Default are 3600 seconds.
224 QS_SessionCookieName <name>, defines a custom session cookie name, de‐
226 fault is MODQOS.
227 QS_SessionCookiePath <path>, defines the cookie path, default is "/".
229 QS_SessionTimeout <seconds>, defines the session life time for a VIP.
231 It is only used for session based (cookie) VIP identification (not for
232 IP based). Default is 3600 seconds.
233 QS_SessionKey <string>, secret key used for cookie encryption. Used
235 when using the same session cookie for multiple web servers (load bal‐
236 ancing) or sessions should survive a server restart. By default, a ran‐
237 dom key is used which changes every server restart.
238 QS_VipHeaderName <name>[=<regex>] [drop], defines an HTTP response
240 header which marks a user as a VIP. mod_qos creates a session for this
241 user by setting a cookie, e.g., after successful user authentication.
242 Tests optionally its value against the provided regular expression.
243 Specify the action 'drop' if you want mod_qos to remove this control
244 header from the HTTP response.
245 QS_VipIPHeaderName <name>[=<regex>] [drop], defines an HTTP response
247 header which marks a client source IP address as a VIP. Tests option‐
248 ally its value against the provided regular expression. Specify the ac‐
249 tion 'drop' if you want mod_qos to remove this control header from the
250 HTTP response.
251 QS_VipUser, creates a VIP session for users which have been authenti‐
253 cated by the Apache server, e.g., by the standard mod_auth* modules. It
254 works similar to the QS_VipHeaderName directive.
255 QS_VipIpUser, marks a source IP address as a VIP if the user has been
257 authenticated by the Apache server, e.g. by the standard mod_auth* mod‐
258 ules. It works similar to the QS_VipIPHeaderName directive.
259 QS_UserTrackingCookieName <name> [<path>] [<domain>] ['session']
261 ['jsredirect'], enables the user tracking cookie by defining a cookie
262 name. The "path" parameter is an option cookie check page which is used
263 to ensure the client accepts cookies. The "domain" option defines the
264 Domain attriibute for the Set-Cookie header. The option "session" indi‐
265 cates that the cookie shall be a session cookie expiring when the user
266 closes it's browser. User tracking requires mod_unique_id. This feature
267 is disabled by default. Ignores QS_LogOnly.
268 QS_SetEnvIf [!]<variable1>[=<regex>] [[!]<variable2>] [!]<vari‐
270 able=value>, sets (or unsets) the 'variable=value' (literal string) if
271 variable1 (literal string) AND variable2 (literal string) are set in
272 the request environment variable list (not case sensitive). This is
273 used to combine multiple variables to a new event type. Alternatively,
274 a regular expression can be specified for variable1's value and vari‐
275 able2 must be omitted in order to simply set a new variable if the reg‐
276 ular expression matches.
277 QS_SetEnvIfCmpP <env-variable1> eq|ne|gt|lt <env-variable2>
279 [!]<env-variable>[=<value>], sets the specified environment variable if
280 the specified env-variables are alphabetically or numerical equal (eq),
281 not equal (ne), greater (gt), less (lt).
282 QS_SetEnvIfQuery <regex> [!]<variable>[=value], directive works quite
284 similar to the SetEnvIf directive of the Apache module mod_setenvif,
285 but the specified regex is applied against the query string portion of
286 the request line. The directive recognizes the occurrences of $1..$9
287 within value and replaces them by the sub-expressions of the defined
288 regex pattern.
289 QS_SetEnvIfParp <regex> [!]<variable>[=value], directive parsing the
291 request payload using the Apache module mod_parp. It matches the re‐
292 quest URL query and the HTTP request message body data as well ('appli‐
293 cation/x-www-form-urlencoded', 'multipart/form-data', and 'multi‐
294 part/mixed') and sets the defined process variable (quite similar to
295 the QS_SetEnvIfQuery directive). The directive recognizes the occur‐
296 rences of $1..$9 within value and replaces them by the sub-expressions
297 of the defined regex pattern. This directive activates mod_parp for ev‐
298 ery request to the virtual host. You may deactivate mod_parp for se‐
299 lected requests using the SetEnvIf directive: unset the variable 'parp'
300 to do so. Important: request message body processing requires that the
301 server loads the whole request into its memory (at least twice the
302 length of the message). You should limit the allowed size of the HTTP
303 request message body using the QS_LimitRequestBody directive when using
304 QS_SetEnvIfParp!
305 QS_SetEnvIfBody <regex> [!]<variable>[=value], parses the request body
307 using the Apache module mod_parp. Specify the content types to process
308 using the mod_parp directive PARP_BodyData and ensure that mod_parp is
309 enabled using the SetEnvIf directive of the Apache module mod_setenvif.
310 You should limit the allowed size of HTTP requests message body using
311 the QS_LimitRequestBody directive when using mod_parp. The directive
312 recognizes the occurrence of $1 within the variable value and replaces
313 it by the sub-expressions of the defined regex pattern.
314 QS_SetEnvStatus (deprecated, use QS_SetEnvIfStatus)
316 QS_SetEnvIfStatus <status code> <variable>, adds the defined request
318 environment variable if the HTTP status code matches the defined value.
319 The value 'QS_SrvMinDataRate' may be used as a special status code to
320 set a QS_Block event in order to handle connection close events caused
321 by QS_SrvMinDataRate rules while the status 'NullConnection' may be
322 used to mark connections which are closed before any HTTP request has
323 ever been received. The 'QS_SrvMaxConnPerIP' value may be used to count
324 QS_Block events for connections closed by the QS_SrvMaxConnPerIP direc‐
325 tive. The 'BrokenConnection' value may be used to mark clients not
326 reading the full HTTP response.
327 QS_SetEnvResBody (deprecated, use QS_SetEnvIfResBody)
329 QS_SetEnvIfResBody <string> [!]<variable>, adds the defined request en‐
331 vironment variable (e.g. QS_Block) if the HTTP response body contains
332 the defined literal string. Supports only one pattern per location.
333 QS_SetEnv <variable> <value>, sets the defined variable with the value
335 where the value string may contain other environment variables sur‐
336 rounded by "${" and "}". The variable is only set if all defined vari‐
337 ables within the value can be resolved.
338 QS_SetReqHeader [!]<header name> <variable> ['late'], sets the defined
340 HTTP request header to the request if the specified environment vari‐
341 able is set.
342 QS_UnsetReqHeader <header name>, Removes the specified header from the
344 request.
345 QS_UnsetResHeader <header name>, Removes the specified header from the
347 response.
348 QS_SetEnvResHeader <header name> [drop], sets the defined HTTP response
350 header (name and value) to the request environment variables Deletes
351 the header if the action 'drop' has been specified.
352 QS_SetEnvResHeaderMatch <header name> <regex>, sets the defined HTTP
354 response header (name and value) to the request environment variables
355 if the specified regular expression matches the header value.
356 QS_SetEnvRes <variable> <regex> <variable2>[=<value>], sets the envi‐
358 ronment variable2 if the regular expression matches against the value
359 of the environment variable. Occurrences of $1..$9 within the value and
360 replace them by parenthesized subexpressions of the regular expression.
361 QS_RedirectIf <variable> <regex> [<code>:]<url>, redirects the client
363 to the configured url if the regular expression matches the value of
364 the the environment variable.
365 QS_ClientEntries <number>, defines the number of individual clients
367 managed by mod_qos. Default is 50000. Directive is allowed in global
368 server context only.
369 QS_ClientPrefer [<percent>], prefers known VIP clients when server has
371 less than 80% (or the configured value) of free TCP connections. Pre‐
372 ferred clients are VIP clients (or those without any negative penal‐
373 ties), see QS_VipHeaderName directive. Directive is allowed in global
374 server context only.
375 QS_ClientTolerance <percent>, defines the allowed tolerance (variation)
377 from a "normal" client (average) in percent. Default is 20%. Directive
378 is allowed in global server context only.
379 QS_ClientContentTypes <html> <css/js> <images> <other> <304>, defines
381 the distribution of HTTP response content types a client normally re‐
382 ceives when accessing the server. mod_qos normally learns the average
383 behavior automatically by default but you may specify a static configu‐
384 ration in order to avoid influences by a high number of abnormal
385 clients.
386 QS_ClientEventBlockCount <number> [<seconds>], defines the maximum num‐
388 ber of QS_Block allowed within the defined time (default are 10 min‐
389 utes). Directive is allowed in global server context only.
390 QS_ClientEventBlockExcludeIP <addr>, excludes an IP address or address
392 range from being limited by QS_ClientEventBlockCount.
393 QS_ClientEventLimitCount <number> [<seconds> [<variable>]], defines the
395 maximum number of the specified environment variable (QS_Limit by de‐
396 fault) allowed within the defined time (default are 10 minutes). Direc‐
397 tive is allowed in global server context only.
398 QS_CondClientEventLimitCount <number> <seconds> <variable> <pattern>,
400 defines the maximum number of the specified environment variable al‐
401 lowed within the defined time. Directive works similar as QS_Clien‐
402 tEventLimitCount but requests are only blocked if the QS_Cond variable
403 matches the defined pattern (regex). Directive is allowed in global
404 server context only.
405 QS_ClientEventPerSecLimit <number>, defines the number events pro sec‐
407 onds on a per client (source IP) basis. Events are identified by re‐
408 quests having the QS_Event variable set. Directive is allowed in global
409 server context only.
410 QS_ClientEventRequestLimit <number>, defines the allowed number of con‐
412 current requests coming from the same client source IP address having
413 the QS_EventRequest variable set. Directive is allowed in global server
414 context only.
415 QS_ClientSerialize, serializes requests having the QS_Serialize vari‐
417 able set if they are coming from the same IP address.
418 QS_ClientIpFromHeader <header>, defines a HTTP request header to read
420 the client's source IP address from (instead of taking the IP address
421 of the client opening the TCP connection). This may be used for the
422 QS_ClientEventLimitCount directive and QS_Country variable.
423 QS_ClientGeoCountryDB <path>, path to the geograpical database file.
425 QS_ClientGeoCountryPriv <list> <connections> ['excludeUnknown'], de‐
427 fines a comma separated list of country codes for origin client IP ad‐
428 dress which are allowed to access the server if the number of busy TCP
429 connections reaches the defined number of connections while others are
430 denied access. Clients whose IP can't be mapped to a country code can
431 be excluded from the limitation by configuring the 'excludeUnknown' ar‐
432 gument.
433 QS_ErrorPage <url>, defines a custom error page.
435 QS_ErrorResponseCode <code>, defines the HTTP response code which is
437 used when a request is denied, default is 500.
438 QS_ForcedClose 'on'|'off', defines if mod_qos connection handler shall
440 exit with an error code (on) or not. Default is on (except for Apache
441 2.4.49).
442 QS_LogOnly 'on'|'off', enables the log only mode of the module where no
444 limitations are enforced. Default is off. Directive is allowed in
445 global server context only.
446 QS_LogEnv 'on'|'off', enables logging of environment variables.
448 QS_SupportIPv6 'on'|'off', enables IPv6 address support. Default is on.
450 QS_SemMemFile <path>, optional path to a directory or file which shall
452 be used for file based semaphores/shared memory usage, e.g. /var/tmp.
453 QS_MaxClients <number>, optional override for mod_qos's Max‐
455 Clients/MaxRequestWorkers calculation which defines the maximum number
456 of TCP connections the server can handle.
457 QS_DisableHandler 'on'|'off', disables the qos-viewer and qos-console
459 for a virtual host
460 QS_Status 'on'|'off', writes a log message containing server statistics
462 once every minute. Default is off.
463 QS_EventCount 'on'|'off', enables error event counting (counters are
465 shown in the machine-readable version of the status viewer). Default is
466 off.
467 QSLog <arg>, used to configure a global (per Apache instance) 'qslog'
469 logger.
470
472 Pascal Buchbinder, http://mod-qos.sourceforge.net/
473mod_qos Apache Module May 2023 MOD_QOS(1)