<?xml version="1.0"?>

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

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

<module name="Module ngx_stream_limit_conn_module"
        link="/en/docs/stream/ngx_stream_limit_conn_module.html"
        lang="en"
        rev="3">

<section id="summary">

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

</section>


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

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

    ...

    server {

        ...

        limit_conn           addr 1;
        limit_conn_log_level error;
    }
}
</example>
</para>

</section>


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

<directive name="limit_conn">
<syntax><value>zone</value> <value>number</value></syntax>
<default/>
<context>stream</context>
<context>server</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 close the connection.
For example, the directives
<example>
limit_conn_zone $binary_remote_addr zone=addr:10m;

server {
    ...
    limit_conn addr 1;
}
</example>
allow only one connection per an IP address at a time.
</para>

<para>
When several <literal>limit_conn</literal> directives are specified,
any configured limit will apply.
</para>

<para>
The directives are inherited from the previous level if and
only if there are no
<literal>limit_conn</literal>
directives on the current level.
</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>stream</context>
<context>server</context>

<para>
Sets the desired logging level for cases when the server
limits the number of connections.
</para>

</directive>


<directive name="limit_conn_zone">
<syntax>
    <value>key</value>
    <literal>zone</literal>=<value>name</value>:<value>size</value></syntax>
<default/>
<context>stream</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 combinations (1.11.2).
Connections with an empty key value are not accounted.
Usage example:
<example>
limit_conn_zone $binary_remote_addr zone=addr:10m;
</example>
Here, the key is a client IP address set by the
<literal>$binary_remote_addr</literal> variable.
The size of <literal>$binary_remote_addr</literal>
is 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 close the connection.
</para>

</directive>


</section>

</module>