Man page - mod_qos(1)

Packages contains this manual

Manual

MOD_QOS

NAME
DESCRIPTION
OPTIONS
AUTHOR

NAME

mod_qos - quality of service module for the Apache Web server

DESCRIPTION

mod_qos is a quality of service module for the Apache web server implementing control mechanisms that can provide different levels of priority to different HTTP requests.

OPTIONS

QS_LocRequestLimitDefault <number>, defines the default for the
QS_LocRequestLimit and QS_LocRequestLimitMatch directive.
QS_LocRequestLimit <location> <number>, defines the maximum number of
concurrent requests allowed to access the specified location. Default
is defined by the QS_LocRequestLimitDefault directive.
QS_LocRequestPerSecLimit <location> <number>, defines the allowed
number of requests per second to a location. Requests are limited by
adding a delay to each requests. This directive should be used in
conjunction with QS_LocRequestLimit only.
QS_LocKBytesPerSecLimit <location> <kbytes>, defines the allowed
download bandwidth to the defined kbytes per second. Responses
areslowed by adding a delay to each response (non-linear, bigger files
get longer delay than smaller ones). This directive should be used in
conjunction with QS_LocRequestLimit only.
QS_LocRequestLimitMatch <regex> <number>, defines the number of
concurrent requests to the uri (path and query) pattern. Default is
defined by the QS_LocRequestLimitDefault directive.
QS_LocRequestPerSecLimitMatch <regex> <number>, defines the allowed
number of requests per second to the uri (path and query) pattern.
Requests are limited by adding a delay to each requests. This directive
should be used in conjunction with QS_LocRequestLimitMatch only.
QS_LocKBytesPerSecLimitMatch <regex> <kbytes>, defines the allowed
download bandwidth to the location matching the defined URL (path and
query) pattern. Responses are slowed down by adding a delay to each
response (non-linear, bigger files get longer delay than smaller ones).
This directive should be used in conjunction with
QS_LocRequestLimitMatch only.
QS_CondLocRequestLimitMatch <regex> <number> <pattern>, defines the
number of concurrent requests to the uri (path and query) regex. Rule
is only enforced if the QS_Cond variable matches the specified pattern
(regex).
QS_EventRequestLimit <variable>[=<regex>] <number>, defines the number
of concurrent events. Directive works similar to QS_LocRequestLimit,
but counts the requests having the same environment variable (and
optionally matching its value, too) rather than those that have the
same URL pattern.
QS_EventPerSecLimit [!]<variable> <number>, defines how often requests
may have the defined environment variable (literal string) set. It
measures the occurrences of the defined environment variable on a
request per seconds level and tries to limit this occurrence to the
defined number. It works similar to as QS_LocRequestPerSecLimit, but
counts only the requests with the specified variable (or without it if
the variable name is prefixed by a ’!’). If a request matches multiple
events, the rule with the lowest bandwidth is applied. Events are
limited by adding a delay to each request causing an event.
QS_EventKBytesPerSecLimit [!]<variable> <kbytes>, throttles the
download bandwidth of all requests having the defined variable set to
the defined kbytes per second. Responses are slowed by adding a delay
to each response (non-linear, bigger files get longer delay than
smaller ones). By default, no limitation is active. This directive
should be used in conjunction with QS_EventRequestLimit only (you must
use the same variable name for both directives).
QS_EventLimitCount <env-variable> <number> <seconds>, defines the
maximum number of events allowed within the defined time. Requests are
denied when reaching this limitation for the specified time (blocked at
request level).
QS_CondEventLimitCount <env-variable> <number> <seconds> <pattern>,
same as QS_EventLimitCount but blocks requests only if the QS_Cond
variable matches the specified pattern (regex).
QS_SrvMaxConn <number>, defines the maximum number of concurrent TCP
connections for this server (virtual host).
QS_SrvMaxConnClose <number>[%], defines the maximum number of
concurrent TCP connections until the server disables keep-alive for
this server (closes the connection after each requests. You may specify
the number of connections as a percentage of MaxClients if adding the
suffix ’%’ to the specified value.
QS_SrvMaxConnPerIP <number> [<connections>], defines the maximum number
of connections per source IP address for this server (virtual host).
’connections’ defines the number of busy connections of the server (all
virtual hosts) to enable this limitation, default is 0.
QS_SrvMaxConnExcludeIP <addr>, excludes an IP address or address range
from being limited.
QS_SrvMinDataRateIgnoreVIP tells the QS_SrvMaxConnPerIP directive to
ignore (if set to "on") the VIP status of clients. Default is "off",
which means that QS_SrvMaxConnPerIP is disabled for VIPs.
QS_SrvSerialize ’on’|’off’ [<seconds>], ensures that not more than one
request having the QS_SrvSerialize variable set is processed at the
same time by serializing them (process one after each other).
QS_SrvDataRateOff, disables the QS_SrvRequestRate and QS_SrvMinDataRate
enforcement for a virtual host (only port/address based but not for
name based virtual hosts).
QS_SrvRequestRate <bytes per seconds> [<max bytes per second>], defines
the minimum upload throughput a client must generate. See also
QS_SrvMinDataRate.
QS_SrvMinDataRate <bytes per seconds> [<max bytes per second>
[<connections>]], defines the minimum upload/download throughput a
client must generate (the bytes send/received by the client per
seconds). This bandwidth is measured while transmitting the data
(request line, header fields, request body, or response data). The
client connection get closed if the client does not fulfill the
required data rate and the IP address of the causing client get marked
in order to be handled with low priority (see the QS_ClientPrefer
directive). The "max bytes per second" activates dynamic minimum
throughput control: The required minimal throughput is increased in
parallel to the number of concurrent clients sending/receiving data.
The "max bytes per second" setting is reached when the number of
sending/receiving clients is equal to the MaxClients setting. The
"connections" argument is used to specify the number of busy TCP
connections a server must have to enable this feature (0 by default).
No limitation is set by default.
QS_SrvMinDataRateOffEvent ’+’|’-’<env-variable>, disables the minimal
data rate enfocement (QS_SrvMinDataRate) for a certain connection if
the defined environment variable has been set. The ’+’ prefix is used
to add a variable to the configuration while the ’-’ prefix is used to
remove a variable.
QS_SrvMinDataRateIgnoreVIP tells the QS_SrvMinDataRate directive to
ignore (if set to "on") the VIP status of clients. Default is "off",
which means that QS_SrvMinDataRate is disabled for VIPs.
QS_SrvSampleRate <seconds>, defines the sampling rate used by the
QS_SrvMinDataRate directive to measure the throughput of a connection.
QS_DenyRequestLine ’+’|’-’<id> ’log’|’deny’ <regular expression>,
generic request line (method, path, query and protocol) filter used to
deny access for requests matching the defined regular expression. ’+’
adds a new rule while ’-’ removes a rule for a location. The action is
either ’log’ (access is granted but rule match is logged) or ’deny’
(access is denied).
QS_DenyPath, same as QS_DenyRequestLine but applied to the path only.
QS_DenyQuery, same as QS_DenyRequestLine but applied to the query only.
QS_DenyEvent ’+’|’-’<id> ’log’|’deny’ [!]<variable>, matches requests
having the defined process environment variable set (or NOT set if
prefixed by a ’!’). The action taken for matching rules is either ’log’
(access is granted but the rule match is logged) or ’deny’ (access is
denied).
QS_PermitUri, ’+’|’-’<id> ’log’|’deny’ <regular expression>, generic
request filter applied to the request uri (path and query). Only
requests matching at least one QS_PermitUri pattern are allowed. If a
QS_PermitUri pattern has been defined an the request does not match any
rule, the request is denied albeit of any server resource availability
(allow list). All rules must define the same action. Regular expression
is case sensitive.
QS_DenyBody ’on’|’off’, enabled body data filter (obsolete).
QS_DenyQueryBody ’on’|’off’, enabled body data filter for QS_DenyQuery.
QS_PermitUriBody ’on’|’off’, enabled body data filter for
QS_PermitUriBody.
QS_InvalidUrlEncoding ’log’|’deny’|’off’, enforces correct URL decoding
in conjunction with the QS_DenyRequestLine, QS_DenyPath, and
QS_DenyQuery directives. Default is "off".
QS_LimitRequestBody <bytes>, limits the allowed size of an HTTP request
message body.
QS_DenyDecoding ’uni’, enabled additional string decoding functions
which are applied before matching QS_Deny* and QS_Permit* directives.
Default is URL decoding (%xx, , ’+’).
QS_DenyInheritanceOff, disable inheritance of QS_Deny* and QS_Permit*
directives to a location.
QS_RequestHeaderFilter ’on’|’off’|’size’, filters request headers by
allowing only these headers which match the request header rules
defined by mod_qos. Request headers which do not conform these
definitions are either dropped or the whole request is denied. Custom
request headers may be added by the QS_RequestHeaderFilterRule
directive. Using the ’size’ option, the header field max. size is
verified only (similar to LimitRequestFieldsize but using individual
values for each header type) while the pattern is ignored.
QS_ResponseHeaderFilter ’on’|’off’, filters response headers by
allowing only these headers which match the response header rules
defined by mod_qos. Response headers which do not conform these
definitions are dropped.
QS_RequestHeaderFilterRule <header name> ’drop’|’deny’ <regular
expression> <size>, used to add custom request header filter rules
which override the internal filter rules of mod_qos. Directive is
allowed in global server context only.
QS_ResponseHeaderFilterRule <header name> <regular expression> <size>,
used to add custom response header filter rules which override the
internal filter rules of mod_qos. Directive is allowed in global server
context only.
QS_MileStone ’log’|’deny’ <pattern> [<thinktime>], defines request line
patterns a client must access in the defined order as they are defined
in the configuration file.
QS_MileStoneTimeout <seconds>, defines the time in seconds within a
client must reach the next milestone. Default are 3600 seconds.
QS_SessionCookieName <name>, defines a custom session cookie name,
default is MODQOS.
QS_SessionCookiePath <path>, defines the cookie path, default is "/".
QS_SessionTimeout <seconds>, defines the session life time for a VIP.
It is only used for session based (cookie) VIP identification (not for
IP based). Default is 3600 seconds.
QS_SessionKey <string>, secret key used for cookie encryption. Used
when using the same session cookie for multiple web servers (load
balancing) or sessions should survive a server restart. By default, a
random key is used which changes every server restart.
QS_VipHeaderName <name>[=<regex>] [drop], defines an HTTP response
header which marks a user as a VIP. mod_qos creates a session for this
user by setting a cookie, e.g., after successful user authentication.
Tests optionally its value against the provided regular expression.
Specify the action ’drop’ if you want mod_qos to remove this control
header from the HTTP response.
QS_VipIPHeaderName <name>[=<regex>] [drop], defines an HTTP response
header which marks a client source IP address as a VIP. Tests
optionally its value against the provided regular expression. Specify
the action ’drop’ if you want mod_qos to remove this control header
from the HTTP response.
QS_VipUser, creates a VIP session for users which have been
authenticated by the Apache server, e.g., by the standard mod_auth*
modules. It works similar to the QS_VipHeaderName directive.
QS_VipIpUser, marks a source IP address as a VIP if the user has been
authenticated by the Apache server, e.g. by the standard mod_auth*
modules. It works similar to the QS_VipIPHeaderName directive.
QS_UserTrackingCookieName <name> [<path>] [<domain>] [’session’]
[’jsredirect’], enables the user tracking cookie by defining a cookie
name. The "path" parameter is an option cookie check page which is used
to ensure the client accepts cookies. The "domain" option defines the
Domain attriibute for the Set-Cookie header. The option "session"
indicates that the cookie shall be a session cookie expiring when the
user closes it’s browser. User tracking requires mod_unique_id. This
feature is disabled by default. Ignores QS_LogOnly.
QS_SetEnvIf [!]<variable1>[=<regex>] [[!]<variable2>]
[!]<variable=value>, sets (or unsets) the ’variable=value’ (literal
string) if variable1 (literal string) AND variable2 (literal string)
are set in the request environment variable list (not case sensitive).
This is used to combine multiple variables to a new event type.
Alternatively, a regular expression can be specified for variable1’s
value and variable2 must be omitted in order to simply set a new
variable if the regular expression matches.
QS_SetEnvIfCmpP <env-variable1> eq|ne|gt|lt <env-variable2>
[!]<env-variable>[=<value>], sets the specified environment variable if
the specified env-variables are alphabetically or numerical equal (eq),
not equal (ne), greater (gt), less (lt).
QS_SetEnvIfQuery <regex> [!]<variable>[=value], directive works quite
similar to the SetEnvIf directive of the Apache module mod_setenvif,
but the specified regex is applied against the query string portion of
the request line. The directive recognizes the occurrences of $1..$9
within value and replaces them by the sub-expressions of the defined
regex pattern.
QS_SetEnvIfParp <regex> [!]<variable>[=value], directive parsing the
request payload using the Apache module mod_parp. It matches the
request URL query and the HTTP request message body data as well
(’application/x-www-form-urlencoded’, ’multipart/form-data’, and
’multipart/mixed’) and sets the defined process variable (quite similar
to the QS_SetEnvIfQuery directive). The directive recognizes the
occurrences of $1..$9 within value and replaces them by the
sub-expressions of the defined regex pattern. This directive activates
mod_parp for every request to the virtual host. You may deactivate
mod_parp for selected requests using the SetEnvIf directive: unset the
variable ’parp’ to do so. Important: request message body processing
requires that the server loads the whole request into its memory (at
least twice the length of the message). You should limit the allowed
size of the HTTP request message body using the QS_LimitRequestBody
directive when using QS_SetEnvIfParp!
QS_SetEnvIfBody <regex> [!]<variable>[=value], parses the request body
using the Apache module mod_parp. Specify the content types to process
using the mod_parp directive PARP_BodyData and ensure that mod_parp is
enabled using the SetEnvIf directive of the Apache module mod_setenvif.
You should limit the allowed size of HTTP requests message body using
the QS_LimitRequestBody directive when using mod_parp. The directive
recognizes the occurrence of $1 within the variable value and replaces
it by the sub-expressions of the defined regex pattern.
QS_SetEnvStatus (deprecated, use QS_SetEnvIfStatus)
QS_SetEnvIfStatus <status code> <variable>, adds the defined request
environment variable if the HTTP status code matches the defined value.
The value ’QS_SrvMinDataRate’ may be used as a special status code to
set a QS_Block event in order to handle connection close events caused
by QS_SrvMinDataRate rules while the status ’NullConnection’ may be
used to mark connections which are closed before any HTTP request has
ever been received. The ’QS_SrvMaxConnPerIP’ value may be used to count
QS_Block events for connections closed by the QS_SrvMaxConnPerIP
directive. The ’BrokenConnection’ value may be used to mark clients not
reading the full HTTP response.
QS_SetEnvResBody (deprecated, use QS_SetEnvIfResBody)
QS_SetEnvIfResBody <string> [!]<variable>, adds the defined request
environment variable (e.g. QS_Block) if the HTTP response body contains
the defined literal string. Supports only one pattern per location.
QS_SetEnv <variable> <value>, sets the defined variable with the value
where the value string may contain other environment variables
surrounded by "${" and "}". The variable is only set if all defined
variables within the value can be resolved.
QS_SetReqHeader [!]<header name> <variable> [’late’], sets the defined
HTTP request header to the request if the specified environment
variable is set.
QS_UnsetReqHeader <header name>, Removes the specified header from the
request.
QS_UnsetResHeader <header name>, Removes the specified header from the
response.
QS_SetEnvResHeader <header name> [drop], sets the defined HTTP response
header (name and value) to the request environment variables Deletes
the header if the action ’drop’ has been specified.
QS_SetEnvResHeaderMatch <header name> <regex>, sets the defined HTTP
response header (name and value) to the request environment variables
if the specified regular expression matches the header value.
QS_SetEnvRes <variable> <regex> <variable2>[=<value>], sets the
environment variable2 if the regular expression matches against the
value of the environment variable. Occurrences of $1..$9 within the
value and replace them by parenthesized subexpressions of the regular
expression.
QS_RedirectIf <variable> <regex> [<code>:]<url>, redirects the client
to the configured url if the regular expression matches the value of
the the environment variable.
QS_ClientEntries <number>, defines the number of individual clients
managed by mod_qos. Default is 50000. Directive is allowed in global
server context only.
QS_ClientPrefer [<percent>], prefers known VIP clients when server has
less than 80% (or the configured value) of free TCP connections.
Preferred clients are VIP clients (or those without any negative
penalties), see QS_VipHeaderName directive. Directive is allowed in
global server context only.
QS_ClientTolerance <percent>, defines the allowed tolerance (variation)
from a "normal" client (average) in percent. Default is 20%. Directive
is allowed in global server context only.
QS_ClientContentTypes <html> <css/js> <images> <other> <304>, defines
the distribution of HTTP response content types a client normally
receives when accessing the server. mod_qos normally learns the average
behavior automatically by default but you may specify a static
configuration in order to avoid influences by a high number of abnormal
clients.
QS_ClientEventBlockCount <number> [<seconds>], defines the maximum
number of QS_Block allowed within the defined time (default are 10
minutes). Directive is allowed in global server context only.
QS_ClientEventBlockExcludeIP <addr>, excludes an IP address or address
range from being limited by QS_ClientEventBlockCount.
QS_ClientEventLimitCount <number> [<seconds> [<variable>]], defines the
maximum number of the specified environment variable (QS_Limit by
default) allowed within the defined time (default are 10 minutes).
Directive is allowed in global server context only.
QS_CondClientEventLimitCount <number> <seconds> <variable> <pattern>,
defines the maximum number of the specified environment variable
allowed within the defined time. Directive works similar as
QS_ClientEventLimitCount but requests are only blocked if the QS_Cond
variable matches the defined pattern (regex). Directive is allowed in
global server context only.
QS_ClientEventPerSecLimit <number>, defines the number events pro
seconds on a per client (source IP) basis. Events are identified by
requests having the QS_Event variable set. Directive is allowed in
global server context only.
QS_ClientEventRequestLimit <number>, defines the allowed number of
concurrent requests coming from the same client source IP address
having the QS_EventRequest variable set. Directive is allowed in global
server context only.
QS_ClientSerialize, serializes requests having the QS_Serialize
variable set if they are coming from the same IP address.
QS_ClientIpFromHeader <header>, defines a HTTP request header to read
the client’s source IP address from (instead of taking the IP address
of the client opening the TCP connection). This may be used for the
QS_ClientEventLimitCount directive and QS_Country variable.
QS_ClientGeoCountryDB <path>, path to the geograpical database file.
QS_ClientGeoCountryPriv <list> <connections> [’excludeUnknown’],
defines a comma separated list of country codes for origin client IP
address which are allowed to access the server if the number of busy
TCP connections reaches the defined number of connections while others
are denied access. Clients whose IP can’t be mapped to a country code
can be excluded from the limitation by configuring the ’excludeUnknown’
argument.
QS_ErrorPage <url>, defines a custom error page.
QS_ErrorResponseCode <code>, defines the HTTP response code which is
used when a request is denied, default is 500.
QS_ForcedClose ’on’|’off’, defines if mod_qos connection handler shall
exit with an error code (on) or not. Default is on (except for Apache
2.4.49).
QS_LogOnly ’on’|’off’, enables the log only mode of the module where no
limitations are enforced. Default is off. Directive is allowed in
global server context only.
QS_LogEnv ’on’|’off’, enables logging of environment variables.
QS_SupportIPv6 ’on’|’off’, enables IPv6 address support. Default is on.
QS_SemMemFile <path>, optional path to a directory or file which shall
be used for file based semaphores/shared memory usage, e.g. /var/tmp.
QS_MaxClients <number>, optional override for mod_qos’s
MaxClients/MaxRequestWorkers calculation which defines the maximum
number of TCP connections the server can handle.
QS_DisableHandler ’on’|’off’, disables the qos-viewer and qos-console
for a virtual host
QS_Status ’on’|’off’, writes a log message containing server statistics
once every minute. Default is off.
QS_EventCount ’on’|’off’, enables error event counting (counters are
shown in the machine-readable version of the status viewer). Default is
off.
QSLog <arg>, used to configure a global (per Apache instance) ’qslog’
logger.

AUTHOR

Pascal Buchbinder, http://mod-qos.sourceforge.net/