Mercurial > hg > nginx-site
diff xml/en/docs/http/ngx_http_limit_req_module.xml @ 179:8cc01e2179a9
- Reflected recent changes made to ngx_http_limit_conn_module.
- Revamped documentation for ngx_http_limit_req_module.
- Translated ngx_http_limit_{conn,req}_module into English.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Mon, 14 Nov 2011 18:09:03 +0000 |
parents | |
children | bfe3eff81d04 |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/xml/en/docs/http/ngx_http_limit_req_module.xml @@ -0,0 +1,162 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_http_limit_req_module" + link="/en/docs/http/ngx_http_limit_req_module.html" + lang="en"> + +<section id="summary"> + +<para> +The module ngx_http_limit_req_module (0.7.21) allow to limit the number +of requests per defined key, in particular, the number of requests +from a single IP address. +The limitation is done using the “leaky bucket” method. +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +http { + limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s; + + ... + + server { + + ... + + location /search/ { + limit_req zone=one burst=5; + } +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="limit_req"> +<syntax> + <parameter>zone</parameter>=<argument>name</argument> + [<parameter>burst</parameter>=<argument>number</argument>] + [<parameter>nodelay</parameter>] +</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Sets a zone and the maximum allowed burst of requests. +If the rate of requests exceeds the rate configured for a zone, +request processing is delayed such as that they are processed +at a defined rate. +Excessive requests are delayed until their number exceeds the +defined number of bursts. +In this case, the request is terminated with an error +<http-status code="503" text="Service Temporarily Unavailable"/>. +By default, the number of bursts is equal to zero. +For example, the directives +<example> +limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s; + + server { + location /search/ { + limit_req zone=one burst=5; + } + +</example> +allow not more than 1 request per second at an average, +with bursts not exceeding 5 requests. +</para> + +<para> +If delaying of excessive requests while requests are being limited is not +desired, the parameter <parameter>nodelay</parameter> should be used: +<example> + limit_req zone=one burst=5 nodelay; +</example> +</para> + +</directive> + + +<directive name="limit_req_log_level"> +<syntax> +<value>info</value> | +<value>notice</value> | +<value>warn</value> | +<value>error</value> +</syntax> +<default>error</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>0.8.18</appeared-in> + +<para> +Sets the desired logging level for cases when the server limits +the number of requests, or delays request processing. +Delays are logged with the level one less than limits; for example, +if <command>limit_req_log_level notice</command> is specified, +delays are logged with the <value>info</value> level. +</para> + +</directive> + + +<directive name="limit_req_zone"> +<syntax> + <argument>$variable </argument> + <parameter>zone</parameter>=<argument>name</argument>:<argument>size </argument> + <parameter>rate</parameter>=<argument>rate</argument> +</syntax> +<default/> +<context>http</context> + +<para> +Sets the parameters for a zone that keeps states for various keys. +This state stores the current number of requests in particular. +The key is the value of the specified variable. +Example usage: +<example> +limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s; +</example> +</para> + +<para> +Here, the states are kept in a 10 megabyte zone “one”, and an +average rate of requests for this zone cannot exceed +1 request per second. +</para> + +<para> +An IP address of the client serves as a key. +Note that instead of <var>$remote_addr</var>, the +<var>$binary_remote_addr</var> variable is used here, +allowing to lower the size of a state down to 64 bytes. +One megabyte zone can keep about 16 thousand 64-byte states. +If the storage for a zone is exhausted, the server will return error +<http-status code="503" text="Service Temporarily Unavailable"/> +to all further requests. +</para> + +<para> +The rate is specified in requests per second (r/s). +If a rate of less than one request per second is desired, +it is specified in request per minute (r/m). +For example, half-request per second is 30r/m. +</para> + +</directive> + +</section> + +</module>