<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!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"
        rev="16">

<section id="summary">

<para>
The <literal>ngx_http_limit_req_module</literal> module (0.7.21) is used
to limit the request processing rate per a defined key,
in particular, the processing rate of requests coming
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>
    <literal>zone</literal>=<value>name</value>
    [<literal>burst</literal>=<value>number</value>]
    [<literal>nodelay</literal> |
     <literal>delay</literal>=<value>number</value>]</syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Sets the shared memory zone
and the maximum burst size of requests.
If the requests rate exceeds the rate configured for a zone,
their processing is delayed such that requests are processed
at a defined rate.
Excessive requests are delayed until their number exceeds the
maximum burst size
in which case the request is terminated with an
<link id="limit_req_status">error</link>.
By default, the maximum burst size 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 <literal>nodelay</literal> should be used:
<example>
limit_req zone=one burst=5 nodelay;
</example>
</para>

<para id="limit_req_delay">
The <literal>delay</literal> parameter (1.15.7) specifies a limit
at which excessive requests become delayed.
Default value is zero, i.e. all excessive requests are delayed.
</para>

<para>
There could be several <literal>limit_req</literal> directives.
For example, the following configuration will limit the processing rate
of requests coming from a single IP address and, at the same time,
the request processing rate by the virtual server:
<example>
limit_req_zone $binary_remote_addr zone=perip:10m rate=1r/s;
limit_req_zone $server_name zone=perserver:10m rate=10r/s;

server {
    ...
    limit_req zone=perip burst=5 nodelay;
    limit_req zone=perserver burst=10;
}
</example>

</para>

<para>
These directives are inherited from the previous configuration level
if and only if there are no <literal>limit_req</literal> directives
defined on the current level.
</para>

</directive>


<directive name="limit_req_dry_run">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.17.1</appeared-in>

<para>
Enables the dry run mode.
In this mode, requests processing rate is not limited, however,
in the shared memory zone, the number of excessive requests is accounted
as usual.
</para>

</directive>


<directive name="limit_req_log_level">
<syntax>
<literal>info</literal> |
<literal>notice</literal> |
<literal>warn</literal> |
<literal>error</literal></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 refuses to process requests
due to rate exceeding,
or delays request processing.
Logging level for delays is one point less than for refusals; for example,
if “<literal>limit_req_log_level notice</literal>” is specified,
delays are logged with the <literal>info</literal> level.
</para>

</directive>


<directive name="limit_req_status">
<syntax><value>code</value></syntax>
<default>503</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.3.15</appeared-in>

<para>
Sets the status code to return in response to rejected requests.
</para>

</directive>


<directive name="limit_req_zone">
<syntax>
    <value>key</value>
    <literal>zone</literal>=<value>name</value>:<value>size</value>
    <literal>rate</literal>=<value>rate</value>
    [<literal>sync</literal>]</syntax>
<default/>
<context>http</context>

<para>
Sets parameters for a shared memory zone
that will keep states for various keys.
In particular, the state stores the current number of excessive requests.
The <value>key</value> can contain text, variables, and their combination.
Requests with an empty key value are not accounted.
<note>
Prior to version 1.7.6, a <value>key</value> could contain exactly one variable.
</note>
Usage example:
<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 request processing rate for this zone cannot exceed
1 request per second.
</para>

<para>
A client IP address serves as a key.
Note that instead of <var>$remote_addr</var>, the
<var>$binary_remote_addr</var> variable is used here.
The <var>$binary_remote_addr</var> variable’s size
is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses.
The stored state always occupies
64 bytes on 32-bit platforms and 128 bytes on 64-bit platforms.
One megabyte zone can keep about 16 thousand 64-byte states
or about 8 thousand 128-byte states.
</para>

<para>
If the zone storage is exhausted, the least recently used state is removed.
If even after that a new state cannot be created, the request is terminated with
an <link id="limit_req_status">error</link>.
</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>

<para id="limit_req_zone_sync">
The <literal>sync</literal> parameter (1.15.3) enables
<link doc="../stream/ngx_stream_zone_sync_module.xml" id="zone_sync">synchronization</link>
of the shared memory zone.
<note>
The <literal>sync</literal> parameter is available as part of our
<commercial_version>commercial subscription</commercial_version>.
</note>
</para>

<para>
<note>
Additionally, as part of our
<commercial_version>commercial subscription</commercial_version>,
the
<link doc="ngx_http_api_module.xml" id="http_limit_reqs_">status information</link>
for each such shared memory zone can be
<link doc="ngx_http_api_module.xml" id="getHttpLimitReqZone">obtained</link> or
<link doc="ngx_http_api_module.xml" id="deleteHttpLimitReqZoneStat">reset</link>
with the <link doc="ngx_http_api_module.xml">API</link> since 1.17.7.
</note>
</para>

</directive>

</section>


<section id="variables" name="Embedded Variables">

<para>
<list type="tag">

<tag-name id="var_limit_req_status"><var>$limit_req_status</var></tag-name>
<tag-desc>
keeps the result of limiting the request processing rate (1.17.6):
<literal>PASSED</literal>,
<literal>DELAYED</literal>,
<literal>REJECTED</literal>,
<literal>DELAYED_DRY_RUN</literal>, or
<literal>REJECTED_DRY_RUN</literal>
</tag-desc>

</list>
</para>

</section>

</module>