<?xml version="1.0"?>

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

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

<module name="Модуль ngx_http_limit_req_module"
        link="/ru/docs/http/ngx_http_limit_req_module.html"
        lang="ru"
        rev="16">

<section id="summary">

<para>
Модуль <literal>ngx_http_limit_req_module</literal> (0.7.21) позволяет
ограничить скорость обработки запросов по заданному ключу или,
как частный случай, скорость обработки запросов, поступающих
с одного IP-адреса.
Ограничение обеспечивается с помощью метода “leaky bucket”.
</para>

</section>


<section id="example" name="Пример конфигурации">

<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="Директивы">

<directive name="limit_req">
<syntax>
    <literal>zone</literal>=<value>название</value>
    [<literal>burst</literal>=<value>число</value>]
    [<literal>nodelay</literal> |
     <literal>delay</literal>=<value>число</value>]</syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт зону разделяемой памяти (<literal>zone</literal>)
и максимальный размер всплеска запросов (<literal>burst</literal>).
Если скорость поступления запросов превышает описанную в зоне,
то их обработка задерживается так, чтобы запросы обрабатывались
с заданной скоростью.
Избыточные запросы задерживаются до тех пор, пока их число
не превысит максимальный размер всплеска.
При превышении запрос завершается с
<link id="limit_req_status">ошибкой</link>.
По умолчанию максимальный размер всплеска равен нулю.
Например, директивы
<example>
limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;

server {
    location /search/ {
        limit_req zone=one burst=5;
    }
</example>
позволяют в среднем не более 1 запроса в секунду
со всплесками не более 5 запросов.
</para>

<para>
Если же избыточные запросы в пределах лимита всплесков задерживать
не требуется, то следует использовать параметр <literal>nodelay</literal>:
<example>
limit_req zone=one burst=5 nodelay;
</example>
</para>

<para id="limit_req_delay">
Параметр <literal>delay</literal> (1.15.7) задаёт лимит,
по достижении которого избыточные запросы задерживаются.
Значение по умолчанию равно нулю и означает,
что задерживаются все избыточные запросы.
</para>

<para>
Директив <literal>limit_req</literal> может быть несколько.
Например, следующая конфигурация ограничивает скорость обработки запросов,
поступающих с одного IP-адреса, и в то же время ограничивает
скорость обработки запросов одним виртуальным сервером:
<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>
Директивы наследуются с предыдущего уровня конфигурации при условии, что
на данном уровне не описаны свои директивы <literal>limit_req</literal>.
</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>
Включает режим пробного запуска.
В данном режиме скорость обработки запросов не ограничивается, однако
в зоне разделяемой памяти текущее число избыточных запросов учитывается
как обычно.
</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>
Задаёт желаемый уровень записи в лог
случаев отказа в обработке запросов при превышении скорости
и случаев задержек при обработке запроса.
Задержки записываются в лог с уровнем на единицу меньшим, чем отказы,
например, если указано “<literal>limit_req_log_level notice</literal>”,
то задержки будут записываться в лог на уровне <literal>info</literal>.
</para>

</directive>


<directive name="limit_req_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_req_zone">
<syntax>
    <value>ключ</value>
    <literal>zone</literal>=<value>название</value>:<value>размер</value>
    <literal>rate</literal>=<value>скорость</value>
    [<literal>sync</literal>]</syntax>
<default/>
<context>http</context>

<para>
Задаёт параметры зоны разделяемой памяти,
которая хранит состояние для разных значений ключа.
Состояние в частности хранит текущее число избыточных запросов.
В качестве ключа можно использовать текст, переменные и их комбинации.
Запросы с пустым значением ключа не учитываются.
<note>
До версии 1.7.6 в качестве ключа можно было задать ровно одну переменную.
</note>
Пример использования:
<example>
limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
</example>
</para>

<para>
В данном случае состояния хранятся в зоне “one” размером 10 мегабайт,
и средняя скорость обработки запросов для этой зоны не может превышать
1 запроса в секунду.
</para>

<para>
В качестве ключа используется IP-адрес клиента.
Обратите внимание, что вместо переменной <var>$remote_addr</var> используется
переменная <var>$binary_remote_addr</var>.
Длина значения переменной <var>$binary_remote_addr</var> всегда
равна 4 байтам для IPv4-адресов или 16 байтам для IPv6-адресов.
При этом размер состояния всегда равен
64 байтам на 32-битных платформах и 128 байтам на 64-битных платформах.
В зоне размером 1 мегабайт может разместиться около 16 тысяч состояний
размером 64 байта или около 8 тысяч состояний размером 128 байт.
</para>

<para>
При переполнении зоны удаляется наименее востребованное состояние.
Если и это не позволяет создать новое состояние, запрос завершается с
<link id="limit_req_status">ошибкой</link>.
</para>

<para>
Скорость задаётся в запросах в секунду (r/s).
Если же нужна скорость меньше одного запроса в секунду,
то она задаётся в запросах в минуту (r/m), например,
ползапроса в секунду — это 30r/m.
</para>

<para id="limit_req_zone_sync">
Параметр <literal>sync</literal> (1.15.3) разрешает
<link doc="../stream/ngx_stream_zone_sync_module.xml" id="zone_sync">синхронизацию</link>
данной зоны разделяемой памяти.
<note>
Параметр <literal>sync</literal> доступен как часть
<commercial_version>коммерческой подписки</commercial_version>.
</note>
</para>

<para>
<note>
Дополнительно, как часть
<commercial_version>коммерческой подписки</commercial_version>,
<link doc="ngx_http_api_module.xml" id="http_limit_reqs_">информацию о состоянии</link>
каждой такой зоны разделяемой памяти можно
<link doc="ngx_http_api_module.xml" id="getHttpLimitReqZone">получить</link> или
<link doc="ngx_http_api_module.xml" id="deleteHttpLimitReqZoneStat">сбросить</link>
при помощи <link doc="ngx_http_api_module.xml">API</link>
начиная с версии 1.17.7.
</note>
</para>

</directive>

</section>


<section id="variables" name="Встроенные переменные">

<para>
<list type="tag">

<tag-name id="var_limit_req_status"><var>$limit_req_status</var></tag-name>
<tag-desc>
хранит результат ограничения скорости поступления запросов (1.17.6):
<literal>PASSED</literal>,
<literal>DELAYED</literal>,
<literal>REJECTED</literal>,
<literal>DELAYED_DRY_RUN</literal> или
<literal>REJECTED_DRY_RUN</literal>
</tag-desc>

</list>
</para>

</section>

</module>