MOD_QOS(1)

📦
version 11.79 · 3 versions
, in ubuntu stonking

💖 mod_qos(1) — bestie edition, part 1 💖

Okay so this is the mod_qos(1) manual page, aka the manual for mod_qos. It is long, so it comes in 3 parts, and this is part 1. We are keeping the exact same sections in the exact same order, and every single flag, argument, default, warning, and little gremlin detail is staying. No cap. 🫶

✨ NAME ✨

mod_qos — quality of service module for the Apache Web server. That is the whole NAME section, short and iconic. 👑

🌸 DESCRIPTION 🌸

mod_qos is a quality of service module for the Apache Web server. It implements control mechanisms that can provide different levels of priority to different HTTP requests. It is literally giving bouncer-at-the-club energy, but the club is your server and the guests are HTTP requests. 💅

💅 OPTIONS 💅

Okay bestie, this is the big one. Every directive, every argument, every default, every condition. Let's go. 🏃‍♀️✨

  • QS_LocRequestLimitDefault <number> — defines the default for the QS_LocRequestLimit and QS_LocRequestLimitMatch directives. It is the fallback number, the "if you did not say otherwise" vibe. ✨
  • 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 request. 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 are slowed 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 request. 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. The rule is only enforced if the QS_Cond variable matches the specified pattern (regex). Conditional queen behavior. 👑
  • QS_EventRequestLimit <variable>[=<regex>] <number> — defines the number of concurrent events. This 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 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. VIP pass, but for IPs. 🎟️
  • 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). One at a time, bestie. 🚶‍♀️
  • 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 enforcement (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. 👑 (Yes, this one is back with a different BFF directive. The manual lists it twice, so we list it twice. Periodt.)
  • 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 and 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. 🍪
okay bestie we're still in the directives, keep scrolling, we're not done slaying 💅
  • QS_SessionCookiePath <path> — sets where the cookie lives. The default is "/". Simple as that. 🍪
  • QS_SessionTimeout <seconds> — how long a VIP's session lasts. Heads up though: this is only for session-based (cookie) VIP identification, not the IP-based kind. Default is 3600 seconds. ⏰
  • QS_SessionKey <string> — the secret key used for cookie encryption. You want this when the same session cookie is shared across multiple web servers (hello, load balancing 🌈) or when sessions should survive a server restart. By default a random key is used which changes every server restart — so like, your sessions get amnesia every time you restart. 😭
  • QS_VipHeaderName <name>[=<regex>] [drop] — defines an HTTP response header that marks a user as a VIP. mod_qos creates a session for this user by setting a cookie, e.g. after successful user authentication. It optionally tests the header's value against the provided regular expression. Add the action drop if you want mod_qos to remove this control header from the HTTP response. 👑
  • QS_VipIPHeaderName <name>[=<regex>] [drop] — same energy, but this header marks a client source IP address as a VIP. Also optionally tests its value against the provided regular expression. And yeah, drop removes this control header from the HTTP response too. 🌟
  • QS_VipUser — makes a VIP session for users who've been authenticated by the Apache server, e.g. by the standard mod_auth* modules. Works similar to the QS_VipHeaderName directive. vibe check: passed ✅
  • 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. Works similar to the QS_VipIPHeaderName directive. 🫶
  • QS_UserTrackingCookieName <name> [<path>] [<domain>] ['session'] ['jsredirect'] — turns on the user tracking cookie by giving it 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 attribute 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. It 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), or less (lt). comparison core 🧮
  • QS_SetEnvIfQuery <regex> [!]<variable>[=value] — 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. It 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] — parses 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). It 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. A few special status codes live here:
    • 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.
    • 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. Just so you know: it 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. no half-finished vibes here 🎀
  • 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. bye felicia 👋
  • QS_UnsetResHeader <header name> — removes the specified header from the response. also bye 👋
  • 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. match made in heaven ✨
  • QS_SetEnvRes <variable> <regex> <variable2>[=<value>] — sets variable2 if the regular expression matches against the value of the environment variable. Occurrences of $1..$9 within the value get replaced 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 environment variable. yeet them elsewhere 🚀
  • QS_ClientEntries <number> — defines the number of individual clients managed by mod_qos. Default is 50000. Heads up: this directive is allowed in global server context only. 🌍
  • QS_ClientPrefer [<percent>] — prefers known VIP clients when the 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 the QS_VipHeaderName directive. Global server context only. 👑
  • QS_ClientTolerance <percent> — defines the allowed tolerance (variation) from a "normal" client (average) in percent. Default is 20%. 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). Global server context only. 🚫
  • QS_ClientEventBlockExcludeIP <addr> — excludes an IP address or address range from being limited by QS_ClientEventBlockCount. exempt, bestie 💖
  • 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). Global server context only. ⏳
  • QS_CondClientEventLimitCount <number> <seconds> <variable> <pattern> — defines the maximum number of the specified environment variable allowed within the defined time. It works similar to QS_ClientEventLimitCount, but requests are only blocked if the QS_Cond variable matches the defined pattern (regex). 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. 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. Global server context only. 🧵
  • QS_ClientSerialize — serializes requests having the QS_Serialize variable set if they are coming from the same IP address. one at a time, we wait our turn 💅
  • 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). 🕵️
  • 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. 🗺️

Overrides QS_ClientIpFromHeader for the use with QS_Country variable.

  • QS_ErrorPage <url> — defines a custom error page. make it cute 🌸
  • 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 the 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' — turns on the module's log-only mode, where it literally just watches and writes stuff down and enforces nothing — no limits, no blocks, just vibes and receipts 📝. Default is off. Heads up bestie: this directive is allowed in global server context only, so don't try to sneak it into a <VirtualHost>.
  • QS_LogEnv 'on'|'off' — switches on logging of environment variables 🫧.
  • QS_SupportIPv6 'on'|'off' — enables IPv6 address support 🌐. Default is on, as it should be, we're not living in 2009.
  • QS_SemMemFile <path> — optional path to a directory or file that mod_qos should use for its file-based semaphores / shared memory usage, e.g. /var/tmp 🗂️.
  • QS_MaxClients <number> — optional override for mod_qos's own MaxClients/MaxRequestWorkers calculation, which is the thing that 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, and those counters show up 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/ — the icon, the legend, the person who wrote all of this 💖🫶

okay and that's a wrap on MOD_QOS(1) bestie!! 🎀 this one shipped as the mod_qos Apache Module man page, dated May 2026 ✨ go forth and throttle responsibly, ily 💜🦋

📦 where this page comes from