[nginx-site] Documented ngx_mail_limit_conn_module.
Maxim Dounin
mdounin at mdounin.ru
Mon Jul 7 23:16:23 UTC 2025
details: http://freenginx.org/hg/nginx-site/rev/46810dc719ce
branches:
changeset: 3110:46810dc719ce
user: Maxim Dounin <mdounin at mdounin.ru>
date: Mon Jul 07 07:22:09 2025 +0300
description:
Documented ngx_mail_limit_conn_module.
diffstat:
xml/en/GNUmakefile | 1 +
xml/en/docs/index.xml | 7 +-
xml/en/docs/mail/ngx_mail_limit_conn_module.xml | 201 +++++++++--------------
xml/en/docs/mail/ngx_mail_pop3_module.xml | 9 +-
xml/ru/GNUmakefile | 1 +
xml/ru/docs/index.xml | 7 +-
xml/ru/docs/mail/ngx_mail_limit_conn_module.xml | 200 +++++++++--------------
xml/ru/docs/mail/ngx_mail_pop3_module.xml | 9 +-
8 files changed, 192 insertions(+), 243 deletions(-)
diffs (741 lines):
diff --git a/xml/en/GNUmakefile b/xml/en/GNUmakefile
--- a/xml/en/GNUmakefile
+++ b/xml/en/GNUmakefile
@@ -89,6 +89,7 @@ REFS = \
mail/ngx_mail_auth_http_module \
mail/ngx_mail_core_module \
mail/ngx_mail_imap_module \
+ mail/ngx_mail_limit_conn_module \
mail/ngx_mail_pop3_module \
mail/ngx_mail_proxy_module \
mail/ngx_mail_realip_module \
diff --git a/xml/en/docs/index.xml b/xml/en/docs/index.xml
--- a/xml/en/docs/index.xml
+++ b/xml/en/docs/index.xml
@@ -8,7 +8,7 @@
<article name="freenginx documentation"
link="/en/docs/"
lang="en"
- rev="53"
+ rev="54"
toc="no">
@@ -454,6 +454,11 @@ ngx_mail_realip_module</link>
</listitem>
<listitem>
+<link doc="mail/ngx_mail_limit_conn_module.xml">
+ngx_mail_limit_conn_module</link>
+</listitem>
+
+<listitem>
<link doc="mail/ngx_mail_ssl_module.xml">
ngx_mail_ssl_module</link>
</listitem>
diff --git a/xml/en/docs/http/ngx_http_limit_conn_module.xml b/xml/en/docs/mail/ngx_mail_limit_conn_module.xml
copy from xml/en/docs/http/ngx_http_limit_conn_module.xml
copy to xml/en/docs/mail/ngx_mail_limit_conn_module.xml
--- a/xml/en/docs/http/ngx_http_limit_conn_module.xml
+++ b/xml/en/docs/mail/ngx_mail_limit_conn_module.xml
@@ -2,28 +2,30 @@
<!--
Copyright (C) Igor Sysoev
+ Copyright (C) Maxim Dounin
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"
+<module name="Module ngx_mail_limit_conn_module"
+ link="/en/docs/mail/ngx_mail_limit_conn_module.html"
lang="en"
- rev="15">
+ rev="1">
<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.
+The <literal>ngx_mail_limit_conn_module</literal> module (1.29.0)
+is used to limit the number of connections per the defined key,
+in particular, the number of connections from an authenticated client.
</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.
+Connections are limited after
+<link url="ngx_mail_auth_http_module.xml">authentication</link>,
+so the user name updated by the authentication server can be used as a key,
+as well as arbitrary authentication server response header fields.
</para>
</section>
@@ -33,8 +35,8 @@ and the whole request header has already
<para>
<example>
-http {
- limit_conn_zone $binary_remote_addr zone=addr:10m;
+mail {
+ limit_conn_zone $remote_user zone=user:10m;
...
@@ -42,9 +44,9 @@ http {
...
- location /download/ {
- limit_conn addr 1;
- }
+ limit_conn user 10;
+ }
+}
</example>
</para>
@@ -56,48 +58,47 @@ http {
<directive name="limit_conn">
<syntax><value>zone</value> <value>number</value></syntax>
<default/>
-<context>http</context>
+<context>mail</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.
+When this limit is exceeded, the server will return a protocol-specific
+error and close the connection.
For example, the directives
<example>
-limit_conn_zone $binary_remote_addr zone=addr:10m;
+limit_conn_zone $remote_user zone=user:10m;
server {
- location /download/ {
- limit_conn addr 1;
- }
+ limit_conn user 5;
</example>
-allow only one connection per an IP address at a time.
-<note>
-In HTTP/2 and HTTP/3,
-each concurrent request is considered a separate connection.
-</note>
+allow only at most 5 connections for an authenticated user at a time.
+</para>
+
+<para>
+Note that not all email clients support the response codes being used,
+and might show password prompt to the user.
+Therefore, it is not recommended to configure limits which are low enough
+to be exceeded by well-behaving clients.
</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:
+of connections per user, and, at the same time, number of connections
+for all users in the particular domain, as provided by the authentication
+server:
<example>
-limit_conn_zone $binary_remote_addr zone=perip:10m;
-limit_conn_zone $server_name zone=perserver:10m;
+limit_conn_zone $remote_user zone=user:10m;
+limit_conn_zone $auth_http_domain zone=domain:10m;
server {
...
- limit_conn perip 10;
- limit_conn perserver 100;
+ limit_conn user 5;
+ limit_conn domain 100;
}
</example>
-
</para>
<para>
@@ -112,10 +113,8 @@ defined on the current level.
<directive name="limit_conn_dry_run">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
-<context>http</context>
+<context>mail</context>
<context>server</context>
-<context>location</context>
-<appeared-in>1.17.6</appeared-in>
<para>
Enables the dry run mode.
@@ -134,10 +133,8 @@ as usual.
<literal>warn</literal> |
<literal>error</literal></syntax>
<default>error</default>
-<context>http</context>
+<context>mail</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
@@ -147,104 +144,68 @@ limits the number of connections.
</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>
+<context>mail</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>
+</para>
+
+<para>
+The <value>key</value> can be one of the following:
+
+<list type="tag">
+
+<tag-name><var>$remote_addr</var></tag-name>
+<tag-desc>
+client address
+</tag-desc>
+
+<tag-name><var>$remote_user</var></tag-name>
+<tag-desc>
+user name supplied during authentication
+</tag-desc>
+
+<tag-name><var>$auth_http_</var><value>name</value></tag-name>
+<tag-desc>
+arbitrary authentication server response header field;
+the last part of a variable name is the field name converted
+to lower case with dashes replaced by underscores
+</tag-desc>
+
+</list>
+
+Connections with an empty key value are not accounted.
+</para>
+
+<para>
Usage example:
<example>
-limit_conn_zone $binary_remote_addr zone=addr:10m;
+limit_conn_zone $remote_user 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.
+Here, the user name serves as a key.
+</para>
+
+<para>
+On 32-bit platforms a stored state occupies
+32 bytes for keys up to 12 bytes,
+64 bytes for keys from 13 to 44 bytes.
+On 64-bit platforms a stored state occupies
+64 bytes for keys up to 28 bytes.
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>
-
-</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>
+If the zone storage is exhausted,
+the server will return an error and close the connection.
</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>
diff --git a/xml/en/docs/mail/ngx_mail_pop3_module.xml b/xml/en/docs/mail/ngx_mail_pop3_module.xml
--- a/xml/en/docs/mail/ngx_mail_pop3_module.xml
+++ b/xml/en/docs/mail/ngx_mail_pop3_module.xml
@@ -78,7 +78,7 @@ will not be automatically included in <l
<directive name="pop3_capabilities">
<syntax><value>extension</value> ...</syntax>
-<default>TOP USER UIDL</default>
+<default>TOP USER UIDL RESP-CODES</default>
<context>mail</context>
<context>server</context>
@@ -107,6 +107,13 @@ The current list of standardized extensi
<link url="http://www.iana.org/assignments/pop3-extension-mechanism">www.iana.org</link>.
</para>
+<para>
+<note>
+Prior to version 1.29.0, the default value was
+<literal>TOP USER UIDL</literal>.
+</note>
+</para>
+
</directive>
</section>
diff --git a/xml/ru/GNUmakefile b/xml/ru/GNUmakefile
--- a/xml/ru/GNUmakefile
+++ b/xml/ru/GNUmakefile
@@ -79,6 +79,7 @@ REFS = \
mail/ngx_mail_auth_http_module \
mail/ngx_mail_core_module \
mail/ngx_mail_imap_module \
+ mail/ngx_mail_limit_conn_module \
mail/ngx_mail_pop3_module \
mail/ngx_mail_proxy_module \
mail/ngx_mail_realip_module \
diff --git a/xml/ru/docs/index.xml b/xml/ru/docs/index.xml
--- a/xml/ru/docs/index.xml
+++ b/xml/ru/docs/index.xml
@@ -8,7 +8,7 @@
<article name="freenginx: документация"
link="/ru/docs/"
lang="ru"
- rev="53"
+ rev="54"
toc="no">
@@ -460,6 +460,11 @@ ngx_mail_realip_module</link>
</listitem>
<listitem>
+<link doc="mail/ngx_mail_limit_conn_module.xml">
+ngx_mail_limit_conn_module</link>
+</listitem>
+
+<listitem>
<link doc="mail/ngx_mail_ssl_module.xml">
ngx_mail_ssl_module</link>
</listitem>
diff --git a/xml/ru/docs/http/ngx_http_limit_conn_module.xml b/xml/ru/docs/mail/ngx_mail_limit_conn_module.xml
copy from xml/ru/docs/http/ngx_http_limit_conn_module.xml
copy to xml/ru/docs/mail/ngx_mail_limit_conn_module.xml
--- a/xml/ru/docs/http/ngx_http_limit_conn_module.xml
+++ b/xml/ru/docs/mail/ngx_mail_limit_conn_module.xml
@@ -2,27 +2,31 @@
<!--
Copyright (C) Igor Sysoev
+ Copyright (C) Maxim Dounin
Copyright (C) Nginx, Inc.
-->
<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
-<module name="Модуль ngx_http_limit_conn_module"
- link="/ru/docs/http/ngx_http_limit_conn_module.html"
+<module name="Модуль ngx_mail_limit_conn_module"
+ link="/ru/docs/mail/ngx_mail_limit_conn_module.html"
lang="ru"
- rev="15">
+ rev="1">
<section id="summary">
<para>
-Модуль <literal>ngx_http_limit_conn_module</literal> позволяет ограничить
-число соединений по заданному ключу, в частности, число соединений с одного
-IP-адреса.
+Модуль <literal>ngx_mail_limit_conn_module</literal> (1.29.0)
+позволяет ограничить число соединений по заданному ключу,
+в частности, число соединений от одного аутентифицированного пользователя.
</para>
<para>
-Учитываются не все соединения, а лишь те, в которых имеются
-запросы, обрабатываемые сервером, и заголовок запроса уже прочитан.
+Соединения ограничиваются после
+<link url="ngx_mail_auth_http_module.xml">аутентификации</link>,
+так что в качестве ключа может использоваться имя пользователя,
+возвращённое сервером аутентификации,
+а также произвольные поля заголовка ответа сервера аутентификации.
</para>
</section>
@@ -32,8 +36,8 @@ IP-адреса.
<para>
<example>
-http {
- limit_conn_zone $binary_remote_addr zone=addr:10m;
+mail {
+ limit_conn_zone $remote_user zone=user:10m;
...
@@ -41,9 +45,9 @@ http {
...
- location /download/ {
- limit_conn addr 1;
- }
+ limit_conn user 10;
+ }
+}
</example>
</para>
@@ -55,48 +59,47 @@ http {
<directive name="limit_conn">
<syntax><value>зона</value> <value>число</value></syntax>
<default/>
-<context>http</context>
+<context>mail</context>
<context>server</context>
-<context>location</context>
<para>
Задаёт зону разделяемой памяти и максимально допустимое число соединений
для одного значения ключа.
-При превышении этого числа в ответ на запрос сервер вернёт
-<link id="limit_conn_status">ошибку</link>.
+При превышении этого числа сервер вернёт ошибку и закроет соединение.
Например, директивы
<example>
-limit_conn_zone $binary_remote_addr zone=addr:10m;
+limit_conn_zone $remote_user zone=user:10m;
server {
- location /download/ {
- limit_conn addr 1;
- }
+ limit_conn user 5;
</example>
-разрешают одновременно обрабатывать не более одного соединения с одного
-IP-адреса.
-<note>
-В HTTP/2 и HTTP/3
-каждый параллельный запрос считается отдельным соединением.
-</note>
+разрешают одновременно обрабатывать не более пяти соединений
+от одного аутентифицированного пользователя.
+</para>
+
+<para>
+Следует иметь в виду, что
+не все почтовые клиенты поддерживают используемые коды ответов,
+и могут предложить пользователю повторно ввести пароль.
+Поэтому не рекомендуется устанавливать слишком низкие ограничения,
+легко достижимые корректно ведущими себя почтовыми клиентами.
</para>
<para>
Директив <literal>limit_conn</literal> может быть несколько.
-Например, следующая конфигурация ограничивает число соединений с сервером
-с одного клиентского IP-адреса и в то же время ограничивает общее число
-соединений с виртуальным сервером:
+Например, следующая конфигурация ограничивает число соединений
+от одного пользователя и в то же время ограничивает число соединений
+для всех пользователей в домене, возвращённом сервером аутентификации:
<example>
-limit_conn_zone $binary_remote_addr zone=perip:10m;
-limit_conn_zone $server_name zone=perserver:10m;
+limit_conn_zone $remote_user zone=user:10m;
+limit_conn_zone $auth_http_domain zone=domain:10m;
server {
...
- limit_conn perip 10;
- limit_conn perserver 100;
+ limit_conn user 5;
+ limit_conn domain 100;
}
</example>
-
</para>
<para>
@@ -110,10 +113,8 @@ server {
<directive name="limit_conn_dry_run">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
-<context>http</context>
+<context>mail</context>
<context>server</context>
-<context>location</context>
-<appeared-in>1.17.6</appeared-in>
<para>
Включает режим пробного запуска.
@@ -132,10 +133,8 @@ server {
<literal>warn</literal> |
<literal>error</literal></syntax>
<default>error</default>
-<context>http</context>
+<context>mail</context>
<context>server</context>
-<context>location</context>
-<appeared-in>0.8.18</appeared-in>
<para>
Задаёт желаемый уровень записи в лог случаев ограничения
@@ -145,104 +144,67 @@ server {
</directive>
-<directive name="limit_conn_status">
-<syntax><value>код</value></syntax>
-<default>503</default>
-<context>http</context>
-<context>server</context>
-<context>location</context>
-<appeared-in>1.3.15</appeared-in>
-
-<para>
-Позволяет переопределить код ответа, используемый при отклонении запросов.
-</para>
-
-</directive>
-
-
<directive name="limit_conn_zone">
<syntax>
<value>ключ</value>
<literal>zone</literal>=<value>название</value>:<value>размер</value></syntax>
<default/>
-<context>http</context>
+<context>mail</context>
<para>
Задаёт параметры зоны разделяемой памяти, которая хранит состояние
для разных значений ключа.
Состояние в частности содержит текущее число соединений.
-В качестве ключа можно использовать текст, переменные и их комбинации.
+</para>
+
+<para>
+В качестве ключа можно использовать:
+
+<list type="tag">
+
+<tag-name><var>$remote_addr</var></tag-name>
+<tag-desc>
+адрес клиента
+</tag-desc>
+
+<tag-name><var>$remote_user</var></tag-name>
+<tag-desc>
+имя пользователя, использованное для аутентификации
+</tag-desc>
+
+<tag-name><var>$auth_http_</var><value>имя</value></tag-name>
+<tag-desc>
+произвольное поле заголовка ответа сервера аутентификации;
+последняя часть имени переменной соответствует имени поля, приведённому
+к нижнему регистру, с заменой символов тире на символы подчёркивания
+</tag-desc>
+
+</list>
+
Запросы с пустым значением ключа не учитываются.
-<note>
-До версии 1.7.6 в качестве ключа можно было задать ровно одну переменную.
-</note>
+</para>
+
+<para>
Пример использования:
<example>
-limit_conn_zone $binary_remote_addr zone=addr:10m;
+limit_conn_zone $remote_user zone=user:10m;
</example>
-Здесь в качестве ключа используется IP-адрес клиента.
-Обратите внимание, что вместо переменной <var>$remote_addr</var>
-использована переменная <var>$binary_remote_addr</var>.
-Длина значения переменной <var>$remote_addr</var> может колебаться
-от 7 до 15 байт, при этом размер хранимого состояния составляет
-либо 32, либо 64 байта на 32-битных платформах и всегда 64
-байта на 64-битных.
-Длина значения переменной <var>$binary_remote_addr</var> всегда
-равна 4 байтам для IPv4-адресов или 16 байтам для IPv6-адресов.
-При этом размер состояния всегда равен 32 или 64 байтам
-на 32-битных платформах и 64 байтам на 64-битных.
+Здесь в качестве ключа используется имя пользователя.
+</para>
+
+<para>
+Размер состояния на 32-битных платформах
+равен 32 байтам для ключей длиной до 12 байт включительно,
+и 64 байтам для ключей от 13 до 44 байт.
+Размер состояния на 64-битных платформах
+равен 64 байтам для ключей длиной до 28 байт включительно.
В зоне размером 1 мегабайт может разместиться около 32 тысяч состояний
размером 32 байта или 16 тысяч состояний размером 64 байта.
-При переполнении зоны в ответ на последующие запросы сервер будет
-возвращать
-<link id="limit_conn_status">ошибку</link>.
-</para>
-
-</directive>
-
-
-<directive name="limit_zone">
-<syntax>
- <value>название</value>
- <value>$переменная</value>
- <value>размер</value></syntax>
-<default/>
-<context>http</context>
-
-<para>
-Эта директива устарела в версии 1.1.8
-и была удалена в версии 1.7.6.
-Вместо неё следует
-использовать аналогичную директиву <link id="limit_conn_zone"/>
-с изменённым синтаксисом:
-<note>
-<literal>limit_conn_zone</literal>
-<value>$переменная</value>
-<literal>zone</literal>=<value>название</value>:<value>размер</value>;
-</note>
+При переполнении зоны сервер вернёт ошибку и закроет соединение.
</para>
</directive>
</section>
-
-<section id="variables" name="Встроенные переменные">
-
-<para>
-<list type="tag">
-
-<tag-name id="var_limit_conn_status"><var>$limit_conn_status</var></tag-name>
-<tag-desc>
-хранит результат ограничения числа соединений (1.17.6):
-<literal>PASSED</literal>,
-<literal>REJECTED</literal> или
-<literal>REJECTED_DRY_RUN</literal>
-</tag-desc>
-
-</list>
-</para>
-
-</section>
-
</module>
diff --git a/xml/ru/docs/mail/ngx_mail_pop3_module.xml b/xml/ru/docs/mail/ngx_mail_pop3_module.xml
--- a/xml/ru/docs/mail/ngx_mail_pop3_module.xml
+++ b/xml/ru/docs/mail/ngx_mail_pop3_module.xml
@@ -78,7 +78,7 @@
<directive name="pop3_capabilities">
<syntax><value>расширение</value> ...</syntax>
-<default>TOP USER UIDL</default>
+<default>TOP USER UIDL RESP-CODES</default>
<context>mail</context>
<context>server</context>
@@ -108,6 +108,13 @@
<link url="http://www.iana.org/assignments/pop3-extension-mechanism">www.iana.org</link>.
</para>
+<para>
+<note>
+До версии 1.29.0 по умолчанию использовалось значение
+<literal>TOP USER UIDL</literal>.
+</note>
+</para>
+
</directive>
</section>
More information about the nginx-devel
mailing list