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/