<?xml version="1.0"?>

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

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_limit_conn_module"
        link="/en/docs/http/ngx_http_limit_conn_module.html"
        lang="en"
        rev="14">

<section id="summary">

<para>
The <literal>ngx_http_limit_conn_module</literal> module is used to
limit the number of connections per the defined key, in
particular, the number of connections from a single IP address.
</para>

<para>
Not all connections are counted.
A connection is counted only if it has a request being processed by the server
and the whole request header has already been read.
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<example>
http {
    limit_conn_zone $binary_remote_addr zone=addr:10m;

    ...

    server {

        ...

        location /download/ {
            limit_conn addr 1;
        }
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="limit_conn">
<syntax><value>zone</value> <value>number</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Sets the shared memory zone
and the maximum allowed number of connections for a given key value.
When this limit is exceeded, the server will return the
<link id="limit_conn_status">error</link>
in reply to a request.
For example, the directives
<example>
limit_conn_zone $binary_remote_addr zone=addr:10m;

server {
    location /download/ {
        limit_conn addr 1;
    }
</example>
allow only one connection per an IP address at a time.
<note>
In HTTP/2 and SPDY, each concurrent request is considered a separate connection.
</note>
</para>

<para>
There could be several <literal>limit_conn</literal> directives.
For example, the following configuration will limit the number
of connections to the server per a client IP and, at the same time,
the total number of connections to the virtual server:
<example>
limit_conn_zone $binary_remote_addr zone=perip:10m;
limit_conn_zone $server_name zone=perserver:10m;

server {
    ...
    limit_conn perip 10;
    limit_conn perserver 100;
}
</example>

</para>

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

</directive>


<directive name="limit_conn_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.6</appeared-in>

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

</directive>


<directive name="limit_conn_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
limits the number of connections.
</para>

</directive>


<directive name="limit_conn_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_conn_zone">
<syntax>
    <value>key</value>
    <literal>zone</literal>=<value>name</value>:<value>size</value></syntax>
<default/>
<context>http</context>

<para>
Sets parameters for a shared memory zone
that will keep states for various keys.
In particular, the state includes the current number of connections.
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_conn_zone $binary_remote_addr zone=addr:10m;
</example>
Here, 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>$remote_addr</var> variable’s size can
vary from 7 to 15 bytes.
The stored state occupies either
32 or 64 bytes of memory on 32-bit platforms and always 64
bytes on 64-bit platforms.
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 32 or 64 bytes
on 32-bit platforms and 64 bytes on 64-bit platforms.
One megabyte zone can keep about 32 thousand 32-byte states
or about 16 thousand 64-byte states.
If the zone storage is exhausted, the server will return the
<link id="limit_conn_status">error</link>
to all further requests.
</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_conns_">status information</link>
for each such shared memory zone can be
<link doc="ngx_http_api_module.xml" id="getHttpLimitConnZone">obtained</link> or
<link doc="ngx_http_api_module.xml" id="deleteHttpLimitConnZoneStat">reset</link>
with the <link doc="ngx_http_api_module.xml">API</link> since 1.17.7.
</note>
</para>

</directive>


<directive name="limit_zone">
<syntax>
    <value>name</value>
    <value>$variable</value>
    <value>size</value></syntax>
<default/>
<context>http</context>

<para>
This directive was made obsolete in version 1.1.8
and was removed in version 1.7.6.
An equivalent <link id="limit_conn_zone"/> directive
with a changed syntax should be used instead:
<note>
<literal>limit_conn_zone</literal>
<value>$variable</value>
<literal>zone</literal>=<value>name</value>:<value>size</value>;
</note>
</para>

</directive>

</section>


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

<para>
<list type="tag">

<tag-name id="var_limit_conn_status"><var>$limit_conn_status</var></tag-name>
<tag-desc>
keeps the result of limiting the number of connections (1.17.6):
<literal>PASSED</literal>,
<literal>REJECTED</literal>, or
<literal>REJECTED_DRY_RUN</literal>
</tag-desc>

</list>
</para>

</section>

</module>