<?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="7">

<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>]</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>
Директив <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_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></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 байт.
При переполнении зоны в ответ на последующие запросы сервер будет
возвращать
<link id="limit_req_status">ошибку</link>.
</para>

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

</directive>

</section>

</module>