<?xml version="1.0"?>

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

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

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

<section id="directives" name="Директивы">

<directive name="absolute_redirect">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.11.8</appeared-in>

<para>
Если запрещено, то перенаправления, выдаваемые nginx’ом, будут относительными.
</para>

<para>
См. также директивы <link id="server_name_in_redirect"/>
и <link id="port_in_redirect"/>.
</para>

</directive>


<directive name="aio">
<syntax>
    <literal>on</literal> |
    <literal>off</literal> |
    <literal>threads</literal>[<literal>=</literal><value>pool</value>]</syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>0.8.11</appeared-in>

<para>
Разрешает или запрещает использование файлового асинхронного ввода-вывода (AIO)
во FreeBSD и Linux:
<example>
location /video/ {
    aio            on;
    output_buffers 1 64k;
}
</example>
</para>

<para>
Во FreeBSD AIO можно использовать, начиная с FreeBSD&nbsp;4.3.
До FreeBSD&nbsp;11.0
AIO можно либо собрать в ядре статически:
<example>
options VFS_AIO
</example>
либо загрузить динамически через загружаемый модуль ядра:
<example>
kldload aio
</example>
</para>

<!--
<para>
В версиях FreeBSD 5 и 6 включение AIO статически или динамически
на стадии загрузки ядра приводит к тому, что вся сетевая подсистема
будет использовать блокировку Giant, что может негативно сказаться на
производительности системы в целом.
Это ограничение устранено во FreeBSD&nbsp;6.4-STABLE в 2009 году
и во FreeBSD&nbsp;7.
Однако, начиная с FreeBSD&nbsp;5.3 есть возможность включать AIO,
не связывая сетевую подсистему блокировкой Giant — для этого модуль
AIO нужно подгружать уже после загрузки ядра.
В этом случае в <path>/var/log/messages</path> появится следующее сообщение:
<example>
WARNING: Network stack Giant-free, but aio requires Giant.
Consider adding 'options NET_WITH_GIANT' or setting debug.mpsafenet=0
</example>
которое можно смело проигнорировать.
<note>
Требование использовать блокировку Giant в AIO связано с тем, что
FreeBSD поддерживает асинхронные вызовы
<c-func>aio_read</c-func>
и
<c-func>aio_write</c-func>
для работы с сокетами.
Но поскольку nginx использует AIO только для работы с диском,
то проблем не возникает.
</note>
</para>
-->

<para>
В Linux AIO можно использовать только начиная с версии ядра 2.6.22.
Кроме того, необходимо также дополнительно включить
<link id="directio"/>,
иначе чтение будет блокирующимся:
<example>
location /video/ {
    aio            on;
    directio       512;
    output_buffers 1 128k;
}
</example>
</para>

<para>
В Linux
<link id="directio"/>
можно использовать только для чтения блоков, выравненных
на границу 512 байт (или 4К для XFS).
Невыравненный конец файла будет читаться блокированно.
То же относится к запросам с указанием диапазона запрашиваемых байт
(byte-range requests) и к запросам FLV не с начала файла: чтение
невыравненных начала и конца ответа будет блокирующимся.
</para>

<para>
При одновременном включении AIO и <link id="sendfile"/> в Linux
для файлов, размер которых больше либо равен указанному
в директиве <link id="directio"/>, будет использоваться AIO,
а для файлов меньшего размера
или при выключенном <link id="directio"/> — <link id="sendfile"/>:
<example>
location /video/ {
    sendfile       on;
    aio            on;
    directio       8m;
}
</example>
</para>

<para>
Кроме того, читать и <link id="sendfile">отправлять</link>
файлы можно в многопоточном режиме (1.7.11),
не блокируя при этом рабочий процесс:
<example>
location /video/ {
    sendfile       on;
    aio            threads;
}
</example>
Операции чтения или отправки файлов будут обрабатываться потоками из указанного
<link doc="../ngx_core_module.xml" id="thread_pool">пула</link>.
Если пул потоков не задан явно,
используется пул с именем “<literal>default</literal>”.
Имя пула может быть задано при помощи переменных:
<example>
aio threads=pool$disk;
</example>
По умолчанию поддержка многопоточности выключена, её сборку следует
разрешить с помощью конфигурационного параметра
<literal>--with-threads</literal>.
В настоящий момент многопоточность совместима только с методами
<link doc="../events.xml" id="epoll"/>,
<link doc="../events.xml" id="kqueue"/>
и
<link doc="../events.xml" id="eventport"/>.
Отправка файлов в многопоточном режиме поддерживается только на Linux.
</para>

<para>
См. также директиву <link id="sendfile"/>.
</para>

</directive>


<directive name="aio_write">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.9.13</appeared-in>

<para>
При включённом <link id="aio"/> разрешает его использование для записи файлов.
В настоящий момент это работает только при использовании
<literal>aio threads</literal>
и ограничено записью временных файлов с данными,
полученными от проксируемых серверов.
</para>

</directive>


<directive name="alias">
<syntax><value>путь</value></syntax>
<default/>
<context>location</context>

<para>
Задаёт замену для указанного location’а.
Например, при такой конфигурации
<example>
location /i/ {
    alias /data/w3/images/;
}
</example>
на запрос
“<literal>/i/top.gif</literal>” будет отдан файл
<path>/data/w3/images/top.gif</path>.
</para>

<para>
В значении параметра <value>путь</value> можно использовать переменные,
кроме <var>$document_root</var> и <var>$realpath_root</var>.
</para>

<para>
Если <literal>alias</literal> используется внутри location’а, заданного
регулярным выражением, то регулярное выражение должно содержать
выделения, а сам <literal>alias</literal> — ссылки на эти выделения
(0.7.40), например:
<example>
location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ {
    alias /data/w3/images/$1;
}
</example>
</para>

<para>
Если location и последняя часть значения директивы совпадают:
<example>
location /images/ {
    alias /data/w3/images/;
}
</example>
то лучше воспользоваться директивой
<link id="root"/>:
<example>
location /images/ {
    root /data/w3;
}
</example>
</para>

</directive>


<directive name="auth_delay">
<syntax><value>время</value></syntax>
<default>0s</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.17.10</appeared-in>

<para>
Задерживает обработку неавторизованных запросов с кодом ответа 401
для предотвращения атак по времени в случае ограничения доступа по
<link doc="ngx_http_auth_basic_module.xml">паролю</link> или по
<link doc="ngx_http_auth_request_module.xml">результату подзапроса</link>.
</para>

</directive>


<directive name="chunked_transfer_encoding">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Позволяет запретить формат передачи данных частями (chunked transfer
encoding) в HTTP/1.1.
Это может понадобиться при использовании программ, не поддерживающих
chunked encoding, несмотря на требования стандарта.
</para>

</directive>


<directive name="client_body_buffer_size">

<syntax><value>размер</value></syntax>
<default>8k|16k</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт размер буфера для чтения тела запроса клиента.
Если тело запроса больше заданного буфера,
то всё тело запроса или только его часть записывается во
<link id="client_body_temp_path">временный файл</link>.
По умолчанию размер одного буфера равен двум размерам страницы.
На x86, других 32-битных платформах и x86-64 это 8K.
На других 64-битных платформах это обычно 16K.
</para>

</directive>


<directive name="client_body_in_file_only">
<syntax>
    <literal>on</literal> |
    <literal>clean</literal> |
    <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Определяет, сохранять ли всё тело запроса клиента в файл.
Директиву можно использовать для отладки и при использовании переменной
<var>$request_body_file</var>
или метода
<link doc="ngx_http_perl_module.xml" id="methods">$r->request_body_file</link>
модуля
<link doc="ngx_http_perl_module.xml">ngx_http_perl_module</link>.
</para>

<para>
При установке значения <literal>on</literal> временные файлы
по окончании обработки запроса не удаляются.
</para>

<para>
Значение <literal>clean</literal> разрешает удалять временные файлы,
оставшиеся по окончании обработки запроса.
</para>

</directive>


<directive name="client_body_in_single_buffer">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Определяет, сохранять ли всё тело запроса клиента в одном буфере.
Директива рекомендуется при использовании переменной
<var>$request_body</var>
для уменьшения требуемого числа операций копирования.
</para>

</directive>


<directive name="client_body_temp_path">
<syntax>
    <value>путь</value>
    [<value>уровень1</value>
    [<value>уровень2</value>
    [<value>уровень3</value>]]]</syntax>
<default>client_body_temp</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт каталог для хранения временных файлов с телами запросов клиентов.
В каталоге может использоваться иерархия подкаталогов до трёх уровней.
Например, при такой конфигурации
<example>
client_body_temp_path /spool/nginx/client_temp 1 2;
</example>
путь к временному файлу будет следующего вида:
<example>
/spool/nginx/client_temp/7/45/00000123457
</example>
</para>

</directive>


<directive name="client_body_timeout">
<syntax><value>время</value></syntax>
<default>60s</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт таймаут при чтении тела запроса клиента.
Таймаут устанавливается не на всю передачу тела запроса,
а только между двумя последовательными операциями чтения.
Если по истечении этого времени клиент ничего не передаст,
обработка запроса прекращается с ошибкой
<http-status code="408" text="Request Time-out"/>.
</para>

</directive>


<directive name="client_header_buffer_size">
<syntax><value>размер</value></syntax>
<default>1k</default>
<context>http</context>
<context>server</context>

<para>
Задаёт размер буфера для чтения заголовка запроса клиента.
Для большинства запросов достаточно буфера размером в 1K байт.
Однако если в запросе есть длинные cookies, или же запрос
пришёл от WAP-клиента, то он может не поместиться в 1K.
Поэтому, если строка запроса или поле заголовка запроса
не помещаются полностью в этот буфер, то выделяются буферы
большего размера, задаваемые директивой
<link id="large_client_header_buffers"/>.
</para>

<para>
Если директива указана на уровне <link id="server"/>,
то может использоваться значение из сервера по умолчанию.
Подробнее см. в разделе
“<link doc="server_names.xml" id="virtual_server_selection">Выбор
виртуального сервера</link>”.
</para>

</directive>


<directive name="client_header_timeout">
<syntax><value>время</value></syntax>
<default>60s</default>
<context>http</context>
<context>server</context>

<para>
Задаёт таймаут при чтении заголовка запроса клиента.
Если по истечении этого времени клиент не передаст полностью заголовок,
обработка запроса прекращается с ошибкой
<http-status code="408" text="Request Time-out"/>.
</para>

</directive>


<directive name="client_max_body_size">
<syntax><value>размер</value></syntax>
<default>1m</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт максимально допустимый размер тела запроса клиента.
Если размер больше заданного, то клиенту возвращается ошибка
<http-status code="413" text="Request Entity Too Large"/>.
Следует иметь в виду, что
<!--link doc="/web/upload.xml"-->браузеры не умеют корректно показывать
эту ошибку<!--/link-->.
Установка параметра <value>размер</value> в 0 отключает
проверку размера тела запроса клиента.
</para>

</directive>


<directive name="connection_pool_size">
<syntax><value>размер</value></syntax>
<default>256|512</default>
<context>http</context>
<context>server</context>

<para>
Позволяет производить точную настройку выделения памяти
под конкретные соединения.
Эта директива не оказывает существенного влияния на
производительность, и её не следует использовать.
По умолчанию размер равен
256 байт на 32-битных платформах и 512 байт на 64-битных платформах.
<note>
До версии 1.9.8 по умолчанию использовалось значение 256 на всех платформах.
</note>
</para>

</directive>


<directive name="default_type">
<syntax><value>mime-тип</value></syntax>
<default>text/plain</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт MIME-тип ответов по умолчанию.
Соответствие расширений имён файлов MIME-типу ответов задаётся
с помощью директивы <link id="types"/>.
</para>

</directive>


<directive name="directio">
<syntax><value>размер</value> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>0.7.7</appeared-in>

<para>
Разрешает использовать флаги
<c-def>O_DIRECT</c-def> (FreeBSD, Linux),
<c-def>F_NOCACHE</c-def> (macOS)
или функцию <c-func>directio</c-func> (Solaris)
при чтении файлов, размер которых больше либо равен указанному.
Директива автоматически запрещает (0.7.15) использование
<link id="sendfile"/>
для данного запроса.
Рекомендуется использовать для больших файлов:
<example>
directio 4m;
</example>
или при использовании <link id="aio"/> в Linux.
</para>

</directive>


<directive name="directio_alignment">
<syntax><value>размер</value></syntax>
<default>512</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>0.8.11</appeared-in>

<para>
Устанавливает выравнивание для
<link id="directio"/>.
В большинстве случаев достаточно 512-байтового выравнивания, однако
при использовании XFS под Linux его нужно увеличить до 4K.
</para>

</directive>


<directive name="disable_symlinks">
<syntax><literal>off</literal></syntax>
<syntax>
    <literal>on</literal> |
    <literal>if_not_owner</literal>
    [<literal>from</literal>=<value>часть</value>]</syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.1.15</appeared-in>

<para>
Определяет, как следует поступать с символическими ссылками
при открытии файлов:
<list type="tag">

<tag-name><literal>off</literal></tag-name>
<tag-desc>
Символические ссылки в пути допускаются и не проверяются.
Это стандартное поведение.
</tag-desc>

<tag-name><literal>on</literal></tag-name>
<tag-desc>
Если любой компонент пути является символической ссылкой,
доступ к файлу запрещается.
</tag-desc>

<tag-name><literal>if_not_owner</literal></tag-name>
<tag-desc>
Доступ к файлу запрещается, если любой компонент пути
является символической ссылкой, а ссылка и объект, на
который она ссылается, имеют разных владельцев.
</tag-desc>

<tag-name><literal>from</literal>=<value>часть</value></tag-name>
<tag-desc>
При проверке символических ссылок
(параметры <literal>on</literal> и <literal>if_not_owner</literal>)
обычно проверяются все компоненты пути.
Можно не проверять символические ссылки в начальной части пути,
указав дополнительно параметр
<literal>from</literal>=<value>часть</value>.
В этом случае символические ссылки проверяются лишь начиная
с компонента пути, который следует за заданной начальной частью.
Если значение не является начальной частью проверяемого пути,
путь проверяется целиком, как если бы этот параметр не был указан вовсе.
Если значение целиком совпадает с именем файла,
символические ссылки не проверяются.
В значении параметра можно использовать переменные.
</tag-desc>

</list>
</para>

<para>
Пример:
<example>
disable_symlinks on from=$document_root;
</example>
</para>

<para>
Эта директива доступна только на системах, в которых есть
интерфейсы <c-func>openat</c-func> и <c-func>fstatat</c-func>.
К таким системам относятся современные версии FreeBSD, Linux и Solaris.
</para>

<para>
Параметры <literal>on</literal> и <literal>if_not_owner</literal>
требуют дополнительных затрат на обработку.
<note>
На системах, не поддерживающих операцию открытия каталогов только для поиска,
для использования этих параметров требуется, чтобы рабочие процессы
имели право читать все проверяемые каталоги.
</note>
</para>

<para>
<note>
Модули
<link doc="ngx_http_autoindex_module.xml">ngx_http_autoindex_module</link>,
<link doc="ngx_http_random_index_module.xml">ngx_http_random_index_module</link>
и <link doc="ngx_http_dav_module.xml">ngx_http_dav_module</link>
в настоящий момент игнорируют эту директиву.
</note>
</para>

</directive>


<directive name="error_page">
<syntax>
    <value>код</value> ...
    [<literal>=</literal>[<value>ответ</value>]]
    <value>uri</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if в location</context>

<para>
Задаёт URI, который будет показываться для указанных ошибок.
В значении <value>uri</value> можно использовать переменные.
</para>

<para>
Пример:
<example>
error_page 404             /404.html;
error_page 500 502 503 504 /50x.html;
</example>
</para>

<para>
При этом делается внутреннее перенаправление на указанный <value>uri</value>,
а метод запроса клиента меняется на “<literal>GET</literal>”
(для всех методов, отличных от
“<literal>GET</literal>” и “<literal>HEAD</literal>”).
</para>

<para>
Кроме того, можно поменять код ответа на другой,
используя синтаксис вида “<literal>=</literal><value>ответ</value>”, например:
<example>
error_page 404 =200 /empty.gif;
</example>
</para>

<para>
Если ошибочный ответ обрабатывается проксированным сервером или
FastCGI/uwsgi/SCGI/gRPC-сервером,
и этот сервер может вернуть разные коды ответов,
например, 200, 302, 401 или 404, то можно выдавать возвращаемый им код:
<example>
error_page 404 = /404.php;
</example>
</para>

<para>
Если при внутреннем перенаправлении не нужно менять URI и метод,
то можно передать обработку ошибки в именованный location:
<example>
location / {
    error_page 404 = @fallback;
}

location @fallback {
    proxy_pass http://backend;
}
</example>
</para>

<para>
<note>
Если при обработке <value>uri</value> происходит ошибка,
клиенту возвращается ответ с кодом последней случившейся ошибки.
</note>
</para>

<para>
Также существует возможность использовать перенаправления URL для обработки
ошибок:
<example>
error_page 403      http://example.com/forbidden.html;
error_page 404 =301 http://example.com/notfound.html;
</example>
В этом случае по умолчанию клиенту возвращается код ответа 302.
Его можно изменить только на один из кодов ответа, относящихся к
перенаправлениям (301, 302, 303, 307 и 308).
<note>
До версий 1.1.16 и 1.0.13 код 307 не обрабатывался как перенаправление.
</note>

<note>
До версии 1.13.0 код 308 не обрабатывался как перенаправление.
</note>
</para>

<para>
Директивы наследуются с предыдущего уровня конфигурации при условии, что
на данном уровне не описаны свои директивы <literal>error_page</literal>.
</para>

</directive>


<directive name="etag">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.3.3</appeared-in>

<para>
Разрешает или запрещает автоматическую генерацию поля <header>ETag</header>
заголовка ответа для статических ресурсов.
</para>

</directive>


<directive name="http">
<syntax block="yes"/>
<default/>
<context>main</context>

<para>
Предоставляет контекст конфигурационного файла, в котором указываются
директивы HTTP-сервера.
</para>

</directive>


<directive name="if_modified_since">
<syntax>
    <literal>off</literal> |
    <literal>exact</literal> |
    <literal>before</literal></syntax>
<default>exact</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>0.7.24</appeared-in>

<para>
Определяет, как сравнивать время модификации ответа с
временем в поле
<header>If-Modified-Since</header>
заголовка запроса:

<list type="tag">

<tag-name><literal>off</literal></tag-name>
<tag-desc>
ответ всегда считается изменившимся (0.7.34);
</tag-desc>

<tag-name><literal>exact</literal></tag-name>
<tag-desc>
точное совпадение;
</tag-desc>

<tag-name><literal>before</literal></tag-name>
<tag-desc>
время модификации ответа меньше или равно времени, заданному в поле
<header>If-Modified-Since</header> заголовка запроса.
</tag-desc>

</list>
</para>

</directive>


<directive name="ignore_invalid_headers">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>

<para>
Если включено, nginx игнорирует поля заголовка с недопустимыми именами.
Допустимыми считаются имена, состоящие из английских букв, цифр, дефисов
и возможно знаков подчёркивания (последнее контролируется директивой
<link id="underscores_in_headers"/>).
</para>

<para>
Если директива указана на уровне <link id="server"/>,
то может использоваться значение из сервера по умолчанию.
Подробнее см. в разделе
“<link doc="server_names.xml" id="virtual_server_selection">Выбор
виртуального сервера</link>”.
</para>

</directive>


<directive name="internal">
<syntax/>
<default/>
<context>location</context>

<para>
Указывает, что location может использоваться только для внутренних запросов.
Для внешних запросов клиенту будет возвращаться ошибка
<http-status code="404" text="Not Found"/>.
Внутренними запросами являются:

<list type="bullet">

<listitem>
запросы, перенаправленные директивами
<link id="error_page"/>,
<link doc="ngx_http_index_module.xml" id="index"/>,
<link doc="ngx_http_random_index_module.xml" id="random_index"/> и
<link id="try_files"/>;
</listitem>

<listitem>
запросы, перенаправленные с помощью поля
<header>X-Accel-Redirect</header> заголовка ответа вышестоящего сервера;
</listitem>

<listitem>
подзапросы, формируемые командой
“<command>include virtual</command>”
модуля
<link doc="ngx_http_ssi_module.xml">ngx_http_ssi_module</link>,
директивами модуля
<link doc="ngx_http_addition_module.xml">ngx_http_addition_module</link>,
а также директивами
<link doc="ngx_http_auth_request_module.xml" id="auth_request"/> и
<link doc="ngx_http_mirror_module.xml" id="mirror"/>;

</listitem>

<listitem>
запросы, изменённые директивой
<link doc="ngx_http_rewrite_module.xml" id="rewrite"/>.
</listitem>

</list>
</para>

<para>
Пример:
<example>
error_page 404 /404.html;

location = /404.html {
    internal;
}
</example>
<note>
Для предотвращения зацикливания, которое может возникнуть при
использовании некорректных конфигураций, количество внутренних
перенаправлений ограничено десятью.
По достижении этого ограничения будет возвращена ошибка
<http-status code="500" text="Internal Server Error"/>.
В таком случае в лог-файле ошибок можно увидеть сообщение
“rewrite or internal redirection cycle”.
</note>
</para>

</directive>


<directive name="keepalive_disable">
<syntax><literal>none</literal> | <value>браузер</value> ...</syntax>
<default>msie6</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Запрещает keep-alive соединения с некорректно ведущими себя браузерами.
Параметры <value>браузер</value> указывают, на какие браузеры это
распространяется.
Значение <literal>msie6</literal> запрещает keep-alive соединения
со старыми версиями MSIE после получения запроса POST.
Значение <literal>safari</literal> запрещает keep-alive соединения
с Safari и подобными им браузерами на macOS и подобных ей ОС.
Значение <literal>none</literal> разрешает keep-alive соединения
со всеми браузерами.
<note>
До версии 1.1.18 под значение <literal>safari</literal> подпадали
все Safari и подобные им браузеры на всех ОС, и keep-alive
соединения с ними были по умолчанию запрещены.
</note>
</para>

</directive>


<directive name="keepalive_requests">
<syntax><value>число</value></syntax>
<default>1000</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>0.8.0</appeared-in>

<para>
Задаёт максимальное число запросов, которые можно
сделать по одному keep-alive соединению.
После того, как сделано максимальное число запросов,
соединение закрывается.
</para>

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

<para>
<note>
До версии 1.19.10 по умолчанию использовалось значение 100.
</note>
</para>

</directive>


<directive name="keepalive_time">
<syntax><value>время</value></syntax>
<default>1h</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.19.10</appeared-in>

<para>
Ограничивает максимальное время, в течение которого
могут обрабатываться запросы в рамках keep-alive соединения.
По достижении заданного времени соединение закрывается
после обработки очередного запроса.
</para>

</directive>


<directive name="keepalive_timeout">
<syntax>
    <value>таймаут</value>
    [<value>заголовок_таймаута</value>]</syntax>
<default>75s</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Первый параметр задаёт таймаут, в течение которого keep-alive
соединение с клиентом не будет закрыто со стороны сервера.
Значение 0 запрещает keep-alive соединения с клиентами.
Второй необязательный параметр задаёт значение в поле
<header>Keep-Alive: timeout=<value>время</value></header>
заголовка ответа.
Два параметра могут отличаться друг от друга.
</para>

<para>
Поле
<header>Keep-Alive: timeout=<value>время</value></header>
заголовка понимают Mozilla и Konqueror.
MSIE сам закрывает keep-alive соединение примерно через 60 секунд.
</para>

</directive>


<directive name="large_client_header_buffers">
<syntax><value>число</value> <value>размер</value></syntax>
<default>4 8k</default>
<context>http</context>
<context>server</context>

<para>
Задаёт максимальное <value>число</value> и <value>размер</value>
буферов для чтения большого заголовка запроса клиента.
Строка запроса не должна превышать размера одного буфера, иначе клиенту
возвращается ошибка
<http-status code="414" text="Request-URI Too Large"/>.
Поле заголовка запроса также не должно превышать размера одного буфера,
иначе клиенту возвращается ошибка
<http-status code="400" text="Bad Request"/>.
Буферы выделяются только по мере необходимости.
По умолчанию размер одного буфера равен 8K байт.
Если по окончании обработки запроса соединение переходит в состояние
keep-alive, эти буферы освобождаются.
</para>

<para>
Если директива указана на уровне <link id="server"/>,
то может использоваться значение из сервера по умолчанию.
Подробнее см. в разделе
“<link doc="server_names.xml" id="virtual_server_selection">Выбор
виртуального сервера</link>”.
</para>

</directive>


<directive name="limit_except">
<syntax block="yes"><value>метод</value> ...</syntax>
<default/>
<context>location</context>

<para>
Ограничивает HTTP-методы, доступные внутри location.
Параметр <value>метод</value> может быть одним из
<literal>GET</literal>,
<literal>HEAD</literal>,
<literal>POST</literal>,
<literal>PUT</literal>,
<literal>DELETE</literal>,
<literal>MKCOL</literal>,
<literal>COPY</literal>,
<literal>MOVE</literal>,
<literal>OPTIONS</literal>,
<literal>PROPFIND</literal>,
<literal>PROPPATCH</literal>,
<literal>LOCK</literal>,
<literal>UNLOCK</literal>
или
<literal>PATCH</literal>.
Если разрешён метод <literal>GET</literal>, то метод
<literal>HEAD</literal> также будет разрешён.
Доступ к остальным методам может быть ограничен при помощи директив модулей
<link doc="ngx_http_access_module.xml">ngx_http_access_module</link> и
<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>:
<example>
limit_except GET {
    allow 192.168.1.0/32;
    deny  all;
}
</example>
Обратите внимание, что данное ограничение действует для всех методов,
<emphasis>кроме</emphasis> GET и HEAD.
</para>

</directive>


<directive name="limit_rate">
<syntax><value>скорость</value></syntax>
<default>0</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if в location</context>

<para>
Ограничивает скорость передачи ответа клиенту.
<value>Скорость</value> задаётся в байтах в секунду.
Значение 0 отключает ограничение скорости.
<!--
Чем меньше скорость, тем более аккуратным будет ограничение.
-->
Ограничение устанавливается на запрос, поэтому, если клиент одновременно
откроет два соединения, суммарная скорость будет вдвое выше
заданного ограничения.
</para>

<para>
В значении параметра можно использовать переменные (1.17.0).
Это может быть полезно в случаях, когда скорость нужно ограничивать
в зависимости от какого-либо условия:
<example>
map $slow $rate {
    1     4k;
    2     8k;
}

limit_rate $rate;
</example>
</para>

<para>
Ограничение скорости можно также задать в переменной
<link id="var_limit_rate"><var>$limit_rate</var></link>,
однако начиная с 1.17.0 использовать данный метод не рекомендуется:
<example>
server {

    if ($slow) {
        set $limit_rate 4k;
    }

    ...
}
</example>
</para>

<para>
Кроме того, ограничение скорости может быть задано в поле
<header>X-Accel-Limit-Rate</header> заголовка ответа проксированного сервера.
Эту возможность можно запретить с помощью директив
<link doc="ngx_http_proxy_module.xml" id="proxy_ignore_headers"/>,
<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_ignore_headers"/>,
<link doc="ngx_http_uwsgi_module.xml" id="uwsgi_ignore_headers"/>
и
<link doc="ngx_http_scgi_module.xml" id="scgi_ignore_headers"/>.
</para>

</directive>


<directive name="limit_rate_after">
<syntax><value>размер</value></syntax>
<default>0</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if в location</context>
<appeared-in>0.8.0</appeared-in>

<para>
Задаёт начальный объём данных, после передачи которого начинает
ограничиваться скорость передачи ответа клиенту.
В значении параметра можно использовать переменные (1.17.0).
</para>

<para>
Пример:
<example>
location /flv/ {
    flv;
    limit_rate_after 500k;
    limit_rate       50k;
}
</example>
</para>

</directive>


<directive name="lingering_close">
<syntax>
    <literal>off</literal> |
    <literal>on</literal> |
    <literal>always</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.1.0</appeared-in>
<appeared-in>1.0.6</appeared-in>

<para>
Управляет закрытием соединений с клиентами.
</para>

<para>
Со значением по умолчанию “<literal>on</literal>” nginx будет
<link id="lingering_timeout">ждать</link> и
<link id="lingering_time">обрабатывать</link> дополнительные данные,
поступающие от клиента, перед полным закрытием соединения, но только
если эвристика указывает на то, что клиент может ещё послать данные.
</para>

<para>
Со значением “<literal>always</literal>” nginx всегда будет
ждать и обрабатывать дополнительные данные, поступающие от клиента.
</para>

<para>
Со значением “<literal>off</literal>” nginx не будет ждать поступления
дополнительных данных и сразу же закроет соединение.
Это поведение нарушает протокол и поэтому не должно использоваться без
необходимости.
</para>

<para>
Для управления закрытием
<link doc="ngx_http_v2_module.xml">HTTP/2</link>-соединений
директива должна быть задана на уровне <link id="server"/> (1.19.1).
</para>

</directive>


<directive name="lingering_time">
<syntax><value>время</value></syntax>
<default>30s</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Если действует <link id="lingering_close"/>,
эта директива задаёт максимальное время, в течение которого nginx
будет обрабатывать (читать и игнорировать) дополнительные данные,
поступающие от клиента.
По прошествии этого времени соединение будет закрыто, даже если
будут ещё данные.
</para>

</directive>


<directive name="lingering_timeout">
<syntax><value>время</value></syntax>
<default>5s</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Если действует <link id="lingering_close"/>, эта директива задаёт
максимальное время ожидания поступления дополнительных данных от клиента.
Если в течение этого времени данные не были получены, соединение закрывается.
В противном случае данные читаются и игнорируются, и nginx снова
ждёт поступления данных.
Цикл “ждать-читать-игнорировать” повторяется, но не дольше чем задано
директивой <link id="lingering_time"/>.
</para>

</directive>


<directive name="listen">
<syntax>
    <value>адрес</value>[:<value>порт</value>]
    [<literal>default_server</literal>]
    [<literal>ssl</literal>]
    [<literal>http2</literal> |
     <literal>quic</literal>]
    [<literal>proxy_protocol</literal>]
    [<literal>setfib</literal>=<value>число</value>]
    [<literal>fastopen</literal>=<value>число</value>]
    [<literal>backlog</literal>=<value>число</value>]
    [<literal>rcvbuf</literal>=<value>размер</value>]
    [<literal>sndbuf</literal>=<value>размер</value>]
    [<literal>accept_filter</literal>=<value>фильтр</value>]
    [<literal>deferred</literal>]
    [<literal>bind</literal>]
    [<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>]
    [<literal>reuseport</literal>]
    [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax>
<syntax>
    <value>порт</value>
    [<literal>default_server</literal>]
    [<literal>ssl</literal>]
    [<literal>http2</literal> |
     <literal>quic</literal>]
    [<literal>proxy_protocol</literal>]
    [<literal>setfib</literal>=<value>число</value>]
    [<literal>fastopen</literal>=<value>число</value>]
    [<literal>backlog</literal>=<value>число</value>]
    [<literal>rcvbuf</literal>=<value>размер</value>]
    [<literal>sndbuf</literal>=<value>размер</value>]
    [<literal>accept_filter</literal>=<value>фильтр</value>]
    [<literal>deferred</literal>]
    [<literal>bind</literal>]
    [<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>]
    [<literal>reuseport</literal>]
    [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax>
<syntax>
    <literal>unix:</literal><value>путь</value>
    [<literal>default_server</literal>]
    [<literal>ssl</literal>]
    [<literal>http2</literal> |
     <literal>quic</literal>]
    [<literal>proxy_protocol</literal>]
    [<literal>backlog</literal>=<value>число</value>]
    [<literal>rcvbuf</literal>=<value>размер</value>]
    [<literal>sndbuf</literal>=<value>размер</value>]
    [<literal>accept_filter</literal>=<value>фильтр</value>]
    [<literal>deferred</literal>]
    [<literal>bind</literal>]
    [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax>
<default>*:80 | *:8000</default>
<context>server</context>

<para>
Задаёт <value>адрес</value> и <value>порт</value> для IP
или <value>путь</value> для UNIX-сокета,
на которых сервер будет принимать запросы.
Можно указать <value>адрес</value> и <value>порт</value>,
либо только <value>адрес</value> или только <value>порт</value>.
Кроме того, <value>адрес</value> может быть именем хоста, например:
<example>
listen 127.0.0.1:8000;
listen 127.0.0.1;
listen 8000;
listen *:8000;
listen localhost:8000;
</example>
IPv6-адреса (0.7.36) задаются в квадратных скобках:
<example>
listen [::]:8000;
listen [::1];
</example>
UNIX-сокеты (0.8.21) задаются при помощи префикса “<literal>unix:</literal>”:
<example>
listen unix:/var/run/nginx.sock;
</example>
</para>

<para>
Если указан только <value>адрес</value>, то используется порт 80.
</para>

<para>
Если директива не указана, то используется либо <literal>*:80</literal>,
если nginx работает с привилегиями суперпользователя,
либо <literal>*:8000</literal>.
</para>

<para>
Если у директивы есть параметр <literal>default_server</literal>, то сервер,
в котором описана эта директива, будет сервером по умолчанию для указанной пары
<value>адрес</value>:<value>порт</value>.
Если же директив с параметром <literal>default_server</literal> нет, то
сервером по умолчанию будет первый сервер, в котором описана пара
<value>адрес</value>:<value>порт</value>.
<note>
До версии 0.8.21 этот параметр назывался просто
<literal>default</literal>.
</note>
</para>

<para>
Параметр <literal>ssl</literal> (0.7.14) указывает на то, что все соединения,
принимаемые на данном порту, должны работать в режиме SSL.
Это позволяет задать компактную <link doc="configuring_https_servers.xml"
id="single_http_https_server">конфигурацию</link> для сервера,
работающего сразу в двух режимах — HTTP и HTTPS.
</para>

<para>
Параметр <literal>http2</literal> (1.9.5) позволяет принимать на этом порту
<link doc="ngx_http_v2_module.xml">HTTP/2</link>-соединения.
Обычно, чтобы это работало, следует также указать параметр
<literal>ssl</literal>, однако nginx можно также настроить и на приём
HTTP/2-соединений без SSL.
<note>
Параметр устарел, вместо него следует использовать
директиву <link doc="ngx_http_v2_module.xml" id="http2">http2</link>.
</note>
</para>

<para id="quic">
Параметр <literal>quic</literal> (1.25.0) позволяет принимать на этом порту
<link doc="ngx_http_v3_module.xml">QUIC</link>-соединения.
</para>

<para>
Параметр <literal>proxy_protocol</literal> (1.5.12)
указывает на то, что все соединения, принимаемые на данном порту,
должны использовать
<link url="http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt">протокол
PROXY</link>.
<note>
Протокол PROXY версии 2 поддерживается начиная с версии 1.13.11.
</note>
</para>

<para>
В директиве <literal>listen</literal> можно также указать несколько
дополнительных параметров, специфичных для связанных с сокетами
системных вызовов.
Эти параметры можно задать в любой директиве <literal>listen</literal>,
но только один раз для указанной пары
<value>адрес</value>:<value>порт</value>.
<note>
До версии 0.8.21 их можно было указывать лишь в директиве
<literal>listen</literal> совместно с параметром <literal>default</literal>.
</note>
<list type="tag">

<tag-name>
<literal>setfib</literal>=<value>число</value>
</tag-name>
<tag-desc>
этот параметр (0.8.44) задаёт таблицу маршрутизации, FIB
(параметр <c-def>SO_SETFIB</c-def>) для слушающего сокета.
В настоящий момент это работает только на FreeBSD.
</tag-desc>

<tag-name>
<literal>fastopen</literal>=<value>число</value>
</tag-name>
<tag-desc>
включает
“<link url="http://en.wikipedia.org/wiki/TCP_Fast_Open">TCP Fast Open</link>”
для слушающего сокета (1.5.8) и
<link url="https://datatracker.ietf.org/doc/html/rfc7413#section-5.1">ограничивает</link>
максимальную длину очереди соединений, которые ещё не завершили процесс
three-way handshake.
<note>
Не включайте “TCP Fast Open”, не убедившись, что сервер может адекватно
обрабатывать многократное получение
<link url="https://datatracker.ietf.org/doc/html/rfc7413#section-6.1">
одного и того же SYN-пакета с данными</link>.
</note>
</tag-desc>

<tag-name>
<literal>backlog</literal>=<value>число</value>
</tag-name>
<tag-desc>
задаёт параметр <literal>backlog</literal> в вызове
<c-func>listen</c-func>, который ограничивает
максимальный размер очереди ожидающих приёма соединений.
По умолчанию <literal>backlog</literal> устанавливается равным -1 для
FreeBSD, DragonFly BSD и macOS, и 511 для других платформ.
</tag-desc>

<tag-name>
<literal>rcvbuf</literal>=<value>размер</value>
</tag-name>
<tag-desc>
задаёт размер буфера приёма
(параметр <c-def>SO_RCVBUF</c-def>) для слушающего сокета.
</tag-desc>

<tag-name>
<literal>sndbuf</literal>=<value>размер</value>
</tag-name>
<tag-desc>
задаёт размер буфера передачи
(параметр <c-def>SO_SNDBUF</c-def>) для слушающего сокета.
</tag-desc>

<tag-name>
<literal>accept_filter</literal>=<value>фильтр</value>
</tag-name>
<tag-desc>
задаёт название accept-фильтра
(параметр <c-def>SO_ACCEPTFILTER</c-def>) для слушающего сокета,
который включается для фильтрации входящих соединений
перед передачей их в <c-func>accept</c-func>.
Работает только на FreeBSD и NetBSD 5.0+.
Можно использовать два фильтра:
<link url="http://man.freebsd.org/accf_data">dataready</link>
и
<link url="http://man.freebsd.org/accf_http">httpready</link>.
</tag-desc>

<tag-name>
<literal>deferred</literal>
</tag-name>
<tag-desc>
указывает использовать отложенный <c-func>accept</c-func>
(параметр <c-def>TCP_DEFER_ACCEPT</c-def> сокета) на Linux.
</tag-desc>

<tag-name>
<literal>bind</literal>
</tag-name>
<tag-desc>
указывает, что для данной пары
<value>адрес</value>:<value>порт</value> нужно делать
<c-func>bind</c-func> отдельно.
Это нужно потому, что если описаны несколько директив <literal>listen</literal>
с одинаковым портом, но разными адресами, и одна из директив
<literal>listen</literal> слушает на всех адресах для данного порта
(<literal>*:</literal><value>порт</value>), то nginx сделает
<c-func>bind</c-func> только на <literal>*:</literal><value>порт</value>.
Необходимо заметить, что в этом случае для определения адреса, на который
пришло соединение, делается системный вызов <c-func>getsockname</c-func>.
Если же используются параметры <literal>setfib</literal>,
<literal>fastopen</literal>,
<literal>backlog</literal>, <literal>rcvbuf</literal>,
<literal>sndbuf</literal>, <literal>accept_filter</literal>,
<literal>deferred</literal>, <literal>ipv6only</literal>,
<literal>reuseport</literal>
или <literal>so_keepalive</literal>,
то для данной пары
<value>адрес</value>:<value>порт</value> всегда делается
отдельный вызов <c-func>bind</c-func>.
</tag-desc>

<tag-name>
<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>
</tag-name>
<tag-desc>
этот параметр (0.7.42) определяет
(через параметр сокета <c-def>IPV6_V6ONLY</c-def>),
будет ли слушающий на wildcard-адресе <literal>[::]</literal> IPv6-сокет
принимать только IPv6-соединения, или же одновременно IPv6- и IPv4-соединения.
По умолчанию параметр включён.
Установить его можно только один раз на старте.
<note>
До версии 1.3.4,
если этот параметр не был задан явно, то для сокета действовали
настройки операционной системы.
</note>
</tag-desc>

<tag-name id="reuseport">
<literal>reuseport</literal>
</tag-name>
<tag-desc>
этот параметр (1.9.1) указывает, что нужно создавать отдельный слушающий сокет
для каждого рабочего процесса
(через параметр сокета
<c-def>SO_REUSEPORT</c-def> для Linux 3.9+ и DragonFly BSD
или <c-def>SO_REUSEPORT_LB</c-def> для FreeBSD 12+), позволяя ядру
распределять входящие соединения между рабочими процессами.
В настоящий момент это работает только на Linux 3.9+, DragonFly BSD
и FreeBSD 12+ (1.15.1).
<note>
Ненадлежащее использование параметра может быть
<link url="http://man7.org/linux/man-pages/man7/socket.7.html">небезопасно</link>.
</note>
</tag-desc>

<tag-name>
<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]
</tag-name>
<tag-desc>
этот параметр (1.1.11) конфигурирует для слушающего сокета
поведение “TCP keepalive”.
Если этот параметр опущен, то для сокета будут действовать
настройки операционной системы.
Если он установлен в значение “<literal>on</literal>”, то для сокета
включается параметр <c-def>SO_KEEPALIVE</c-def>.
Если он установлен в значение “<literal>off</literal>”, то для сокета
параметр <c-def>SO_KEEPALIVE</c-def> выключается.
Некоторые операционные системы поддерживают настройку параметров
“TCP keepalive” на уровне сокета посредством параметров
<c-def>TCP_KEEPIDLE</c-def>, <c-def>TCP_KEEPINTVL</c-def> и
<c-def>TCP_KEEPCNT</c-def>.
На таких системах (в настоящий момент это Linux 2.4+, NetBSD 5+ и
FreeBSD 9.0-STABLE)
их можно сконфигурировать с помощью параметров <value>keepidle</value>,
<value>keepintvl</value> и <value>keepcnt</value>.
Один или два параметра могут быть опущены, в таком случае для
соответствующего параметра сокета будут действовать стандартные
системные настройки.
Например,
<example>so_keepalive=30m::10</example>
установит таймаут бездействия (<c-def>TCP_KEEPIDLE</c-def>) в 30 минут,
для интервала проб (<c-def>TCP_KEEPINTVL</c-def>) будет действовать
стандартная системная настройка, а счётчик проб (<c-def>TCP_KEEPCNT</c-def>)
будет равен 10.
</tag-desc>

</list>
</para>

<para>
Пример:
<example>
listen 127.0.0.1 default_server accept_filter=dataready backlog=1024;
</example>
</para>

</directive>


<directive name="location">
<syntax block="yes">[
    <literal>=</literal> |
    <literal>~</literal> |
    <literal>~*</literal> |
    <literal>^~</literal>
    ] <value>uri</value></syntax>
<syntax block="yes"><literal>@</literal><value>имя</value></syntax>
<default/>
<context>server</context>
<context>location</context>

<para>
Устанавливает конфигурацию в зависимости от URI запроса.
</para>

<para>
Для сопоставления используется URI запроса в нормализованном виде,
после декодирования текста, заданного в виде “<literal>%XX</literal>”,
преобразования относительных элементов пути “<literal>.</literal>” и
“<literal>..</literal>” в реальные и возможной
<link id="merge_slashes">замены</link> двух и более подряд идущих
слэшей на один.
</para>

<para>
location можно задать префиксной строкой или регулярным выражением.
Регулярные выражения задаются либо с модификатором “<literal>~*</literal>”
(для поиска совпадения без учёта регистра символов),
либо с модификатором “<literal>~</literal>” (с учётом регистра).
Чтобы найти location, соответствующий запросу, вначале проверяются
location’ы, заданные префиксными строками (префиксные location’ы).
Среди них ищется location с совпадающим префиксом
максимальной длины и запоминается.
Затем проверяются регулярные выражения, в порядке их следования
в конфигурационном файле.
Проверка регулярных выражений прекращается после первого же совпадения,
и используется соответствующая конфигурация.
Если совпадение с регулярным выражением не найдено, то используется
конфигурация запомненного ранее префиксного location’а.
</para>

<para>
Блоки <literal>location</literal> могут быть вложенными,
с некоторыми исключениями, о которых говорится ниже.
</para>

<para>
Для операционных систем, нечувствительных к регистру символов, таких
как macOS и Cygwin, сравнение с префиксными строками производится
без учёта регистра (0.7.7).
Однако сравнение ограничено только однобайтными locale’ями.
</para>

<para>
Регулярные выражения могут содержать выделения (0.7.40), которые могут
затем использоваться в других директивах.
</para>

<para>
Если у совпавшего префиксного location’а максимальной длины указан модификатор
“<literal>^~</literal>”, то регулярные выражения не проверяются.
</para>

<para>
Кроме того, с помощью модификатора “<literal>=</literal>” можно задать точное
совпадение URI и location.
При точном совпадении поиск сразу же прекращается.
Например, если запрос “<literal>/</literal>” случается часто, то
указав “<literal>location = /</literal>”, можно ускорить обработку
этих запросов, так как поиск прекратится после первого же сравнения.
Очевидно, что такой location не может иметь вложенные location’ы.
</para>

<para>
<note>
В версиях с 0.7.1 по 0.8.41, если запрос точно совпал с префиксным
location’ом без модификаторов “<literal>=</literal>” и “<literal>^~</literal>”,
то поиск тоже сразу же прекращается и регулярные выражения также
не проверяются.
</note>
</para>

<para>
Проиллюстрируем вышесказанное примером:
<example>
location = / {
    [ конфигурация А ]
}

location / {
    [ конфигурация Б ]
}

location /documents/ {
    [ конфигурация В ]
}

location ^~ /images/ {
    [ конфигурация Г ]
}

location ~* \.(gif|jpg|jpeg)$ {
    [ конфигурация Д ]
}
</example>
Для запроса “<literal>/</literal>” будет выбрана конфигурация А,
для запроса “<literal>/index.html</literal>” — конфигурация Б,
для запроса “<literal>/documents/document.html</literal>” — конфигурация В,
для запроса “<literal>/images/1.gif</literal>” — конфигурация Г,
а для запроса “<literal>/documents/1.jpg</literal>” — конфигурация Д.
</para>

<para id="location_named">
Префикс “<literal>@</literal>” задаёт именованный location.
Такой location не используется при обычной обработке запросов, а
предназначен только для перенаправления в него запросов.
Такие location’ы не могут быть вложенными и не могут содержать
вложенные location’ы.
</para>

<para>
Если location задан префиксной строкой со слэшом в конце
и запросы обрабатываются при помощи
<link doc="ngx_http_proxy_module.xml" id="proxy_pass"/>,
<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>,
<link doc="ngx_http_uwsgi_module.xml" id="uwsgi_pass"/>,
<link doc="ngx_http_scgi_module.xml" id="scgi_pass"/>,
<link doc="ngx_http_memcached_module.xml" id="memcached_pass"/> или
<link doc="ngx_http_grpc_module.xml" id="grpc_pass"/>,
происходит специальная обработка.
В ответ на запрос с URI равным этой строке, но без завершающего слэша,
будет возвращено постоянное перенаправление с кодом 301
на URI с добавленным в конец слэшом.
Если такое поведение нежелательно, можно задать точное совпадение
URI и location, например:
<example>
location /user/ {
    proxy_pass http://user.example.com;
}

location = /user {
    proxy_pass http://login.example.com;
}
</example>
</para>

<!--
<migration from="Apache" directive="Location" />
-->

</directive>


<directive name="log_not_found">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает или запрещает записывать в
<link doc="../ngx_core_module.xml" id="error_log"/>
ошибки о том, что файл не найден.
</para>

</directive>


<directive name="log_subrequest">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает или запрещает записывать в
<link doc="ngx_http_log_module.xml" id="access_log"/>
подзапросы.
</para>

</directive>


<directive name="max_ranges">
<syntax><value>число</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.1.2</appeared-in>

<para>
Ограничивает максимальное допустимое число диапазонов в запросах с
указанием диапазона запрашиваемых байт (byte-range requests).
Запросы, превышающие указанное ограничение, обрабатываются как
если бы они не содержали указания диапазонов.
По умолчанию число диапазонов не ограничено.
Значение 0 полностью запрещает поддержку диапазонов.
</para>

</directive>


<directive name="merge_slashes">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>

<para>
Разрешает или запрещает преобразование URI путём замены двух и более подряд
идущих слэшей (“<literal>/</literal>”) на один.
</para>

<para>
Необходимо иметь в виду, что это преобразование необходимо для корректной
проверки префиксных строк и регулярных выражений.
Если его не делать, то запрос “<literal>//scripts/one.php</literal>”
не попадёт в
<example>
location /scripts/ {
    ...
}
</example>
и может быть обслужен как статический файл.
Поэтому он преобразуется к виду “<literal>/scripts/one.php</literal>”.
</para>

<para>
Запрет преобразования может понадобиться, если в URI используются имена,
закодированные методом base64, в котором задействован символ
“<literal>/</literal>”.
Однако из соображений безопасности лучше избегать отключения преобразования.
</para>

<para>
Если директива указана на уровне <link id="server"/>,
то может использоваться значение из сервера по умолчанию.
Подробнее см. в разделе
“<link doc="server_names.xml" id="virtual_server_selection">Выбор
виртуального сервера</link>”.
</para>

</directive>


<directive name="msie_padding">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает или запрещает добавлять в ответы для MSIE со статусом больше 400
комментарий для увеличения размера ответа до 512 байт.
</para>

</directive>


<directive name="msie_refresh">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает или запрещает выдавать для MSIE клиентов refresh’ы вместо
перенаправлений.
</para>

</directive>


<directive name="open_file_cache">
<syntax><literal>off</literal></syntax>
<syntax>
<literal>max</literal>=<value>N</value>
[<literal>inactive</literal>=<value>время</value>]</syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт кэш, в котором могут храниться:
<list type="bullet">

<listitem>
дескрипторы открытых файлов, информация об их размерах и времени модификации;
</listitem>

<listitem>
информация о существовании каталогов;
</listitem>

<listitem>
информация об ошибках поиска файла — “нет файла”, “нет прав на чтение”
и тому подобное.
<note>
Кэширование ошибок нужно разрешить отдельно директивой
<link id="open_file_cache_errors"/>.
</note>
</listitem>

</list>
</para>

<para>
У директивы есть следующие параметры:
<list type="tag">

<tag-name>
<literal>max</literal>
</tag-name>
<tag-desc>
задаёт максимальное число элементов в кэше;
при переполнении кэша удаляются наименее востребованные элементы (LRU);
</tag-desc>

<tag-name>
<literal>inactive</literal>
</tag-name>
<tag-desc>
задаёт время, после которого элемент кэша удаляется, если к нему
не было обращений в течение этого времени; по умолчанию 60 секунд;
</tag-desc>

<tag-name>
<literal>off</literal>
</tag-name>
<tag-desc>
запрещает кэш.
</tag-desc>

</list>
</para>

<para>
Пример:
<example>
open_file_cache          max=1000 inactive=20s;
open_file_cache_valid    30s;
open_file_cache_min_uses 2;
open_file_cache_errors   on;
<!--
open_file_cache_events   on;
-->
</example>
</para>

</directive>


<directive name="open_file_cache_errors">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает или запрещает кэширование ошибок поиска файлов в
<link id="open_file_cache"/>.
</para>

</directive>


<!--

<directive name="open_file_cache_events">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает использование событий ядра для проверки актуальности элементов
<link id="open_file_cache"/>.
Эта директива работает только совместно с методом
<link doc="../events.xml" id="kqueue"/>.
Заметьте, что только NetBSD&nbsp;2.0+ и FreeBSD&nbsp;6.0+
поддерживают события для файловых систем произвольного типа.
Другие операционные системы поддерживают события только для
основных файловых систем, таких как UFS или FFS.
</para>

</directive>

-->


<directive name="open_file_cache_min_uses">
<syntax><value>число</value></syntax>
<default>1</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт минимальное <value>число</value> обращений к файлу
в течение времени, заданного параметром <literal>inactive</literal>
директивы <link id="open_file_cache"/>, необходимых для того, чтобы дескриптор
файла оставался открытым в кэше.
</para>

</directive>


<directive name="open_file_cache_valid">
<syntax><value>время</value></syntax>
<default>60s</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Определяет время, через которое следует проверять актуальность информации
об элементе в
<link id="open_file_cache"/>.
<!--
При включенном
<link id="open_file_cache_events"/>
открытые дескрипторы файлов проверяются лишь единожды, а затем обновляются
по факту их изменения.
-->
</para>

</directive>


<directive name="output_buffers">
<syntax><value>number</value> <value>size</value></syntax>
<default>2 32k</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт <value>число</value> и <value>размер</value> буферов,
используемых при чтении ответа с диска.
<note>
До версии 1.9.5 по умолчанию использовалось значение 1 32k.
</note>
</para>

</directive>


<directive name="port_in_redirect">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает или запрещает указывать порт в
<link id="absolute_redirect">абсолютных</link>
перенаправлениях, выдаваемых nginx’ом.
</para>

<para>
Использование в перенаправлениях основного имени сервера управляется
директивой <link id="server_name_in_redirect"/>.
</para>

</directive>


<directive name="postpone_output">
<syntax><value>размер</value></syntax>
<default>1460</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Если это возможно, то отправка данных клиенту будет отложена пока nginx не
накопит по крайней мере указанное количество байт для отправки.
Значение 0 запрещает отложенную отправку данных.
</para>

</directive>


<directive name="read_ahead">
<syntax><value>размер</value></syntax>
<default>0</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт ядру размер предчтения при работе с файлами.
</para>

<para>
На Linux используется системный вызов
<literal>posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)</literal>,
поэтому параметр <value>размер</value> там игнорируется.
</para>

<para>
На FreeBSD используется системный вызов
<literal>fcntl(O_READAHEAD,
</literal><value>размер</value><literal>)</literal>,
появившийся во FreeBSD&nbsp;9.0-CURRENT.
Для FreeBSD&nbsp;7 необходимо установить
<link url="http://sysoev.ru/freebsd/patch.readahead.txt">патч</link>.
</para>

</directive>


<directive name="recursive_error_pages">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает или запрещает делать несколько перенаправлений через директиву
<link id="error_page"/>.
Число таких перенаправлений <link id="internal">ограничено</link>.
</para>

</directive>


<directive name="request_pool_size">
<syntax><value>размер</value></syntax>
<default>4k</default>
<context>http</context>
<context>server</context>

<para>
Позволяет производить точную настройку выделений памяти
под конкретные запросы.
Эта директива не оказывает существенного влияния на
производительность, и её не следует использовать.
</para>

</directive>


<directive name="reset_timedout_connection">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает или запрещает сброс соединений по таймауту,
а также при
<link doc="ngx_http_rewrite_module.xml" id="return">закрытии</link>
соединений с помощью нестандартного кода 444 (1.15.2).
Сброс делается следующим образом.
Перед закрытием сокета для него задаётся параметр
<c-def>SO_LINGER</c-def>
с таймаутом 0.
После этого при закрытии сокета клиенту отсылается TCP RST, а вся память,
связанная с этим сокетом, освобождается.
Это позволяет избежать длительного нахождения уже закрытого сокета в
состоянии FIN_WAIT1 с заполненными буферами.
</para>

<para>
Необходимо отметить, что keep-alive соединения по истечении таймаута
закрываются обычным образом.
</para>

</directive>


<directive name="resolver">
<syntax>
    <value>адрес</value> ...
    [<literal>valid</literal>=<value>время</value>]
    [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>]
    [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]</syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт серверы DNS, используемые для преобразования имён вышестоящих серверов
в адреса, например:
<example>
resolver 127.0.0.1 [::1]:5353;
</example>
Адрес может быть указан в виде доменного имени или IP-адреса,
и необязательного порта (1.3.1, 1.2.2).
Если порт не указан, используется порт 53.
Серверы DNS опрашиваются циклически.
<note>
До версии 1.1.7 можно было задать лишь один DNS-сервер.
Задание DNS-серверов с помощью IPv6-адресов поддерживается
начиная с версий 1.3.1 и 1.2.2.
</note>
</para>

<para id="resolver_ipv6">
По умолчанию nginx будет искать как IPv4-, так и IPv6-адреса
при преобразовании имён в адреса.
Если поиск IPv4- или IPv6-адресов нежелателен,
можно указать параметр <literal>ipv4=off</literal> (1.23.1) или
<literal>ipv6=off</literal>.
<note>
Преобразование имён в IPv6-адреса поддерживается
начиная с версии 1.5.8.
</note>
</para>

<para id="resolver_valid">
По умолчанию nginx кэширует ответы, используя значение TTL из ответа.
Необязательный параметр <literal>valid</literal> позволяет это
переопределить:
<example>
resolver 127.0.0.1 [::1]:5353 valid=30s;
</example>
<note>
До версии 1.1.9 настройка времени кэширования была невозможна
и nginx всегда кэшировал ответы на срок в 5 минут.
</note>
<note>
Для предотвращения DNS-спуфинга рекомендуется
использовать DNS-серверы в защищённой доверенной локальной сети.
</note>
</para>

</directive>


<directive name="resolver_timeout">
<syntax><value>время</value></syntax>
<default>30s</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт таймаут для преобразования имени в адрес, например:
<example>
resolver_timeout 5s;
</example>
</para>

</directive>


<directive name="root">
<syntax><value>путь</value></syntax>
<default>html</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if в location</context>

<para>
Задаёт корневой каталог для запросов.
Например, при такой конфигурации
<example>
location /i/ {
    root /data/w3;
}
</example>
в ответ на запрос “<literal>/i/top.gif</literal>” будет отдан файл
<path>/data/w3/i/top.gif</path>.
</para>

<para>
В значении параметра <value>путь</value> можно использовать переменные,
кроме <var>$document_root</var> и <var>$realpath_root</var>.
</para>

<para>
Путь к файлу формируется путём простого добавления URI к значению директивы
<literal>root</literal>.
Если же URI необходимо поменять, следует воспользоваться директивой
<link id="alias"/>.
</para>

</directive>


<directive name="satisfy">
<syntax><literal>all</literal> | <literal>any</literal></syntax>
<default>all</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает доступ, если все (<literal>all</literal>)
или хотя бы один (<literal>any</literal>) из модулей
<link doc="ngx_http_access_module.xml">ngx_http_access_module</link>,
<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>
или
<link doc="ngx_http_auth_request_module.xml">ngx_http_auth_request_module</link>
разрешают доступ.
</para>

<para>
Пример:
<example>
location / {
    satisfy any;

    allow 192.168.1.0/32;
    deny  all;

    auth_basic           "closed site";
    auth_basic_user_file conf/htpasswd;
}
</example>
</para>

</directive>


<directive name="send_lowat">
<syntax><value>размер</value></syntax>
<default>0</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
При установке этой директивы в ненулевое значение nginx будет пытаться
минимизировать число операций отправки на клиентских сокетах либо при
помощи флага <c-def>NOTE_LOWAT</c-def> метода
<link doc="../events.xml" id="kqueue"/>,
либо при помощи параметра сокета <c-def>SO_SNDLOWAT</c-def>.
В обоих случаях будет использован указанный <value>размер</value>.
</para>

<para>
Эта директива игнорируется на Linux, Solaris и Windows.
</para>

</directive>


<directive name="send_timeout">
<syntax><value>время</value></syntax>
<default>60s</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт таймаут при передаче ответа клиенту.
Таймаут устанавливается не на всю передачу ответа,
а только между двумя операциями записями.
Если по истечении этого времени клиент ничего не примет,
соединение будет закрыто.
</para>

</directive>


<directive name="sendfile">

<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if в location</context>

<para>
Разрешает или запрещает использовать
<c-func>sendfile</c-func>.
</para>

<para>
Начиная с nginx&nbsp;0.8.12 и FreeBSD&nbsp;5.2.1,
можно использовать <link id="aio"/> для подгрузки данных
для <c-func>sendfile</c-func>:
<example>
location /video/ {
    sendfile       on;
    tcp_nopush     on;
    aio            on;
}
</example>
В такой конфигурации функция <c-func>sendfile</c-func> вызывается с флагом
<c-def>SF_NODISKIO</c-def>, в результате чего она не блокируется на диске, а
сообщает об отсутствии данных в памяти.
После этого nginx инициирует асинхронную подгрузку данных, читая один байт.
При этом ядро FreeBSD подгружает в память первые 128K байт файла, однако
при последующих чтениях файл подгружается частями только по 16K.
Изменить это можно с помощью директивы
<link id="read_ahead"/>.
<note>
До версии 1.7.11 подгрузка данных включалась с помощью
<literal>aio sendfile;</literal>.
</note>
</para>

</directive>


<directive name="sendfile_max_chunk">

<syntax><value>размер</value></syntax>
<default>2m</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Ограничивает объём данных,
который может передан за один вызов <c-func>sendfile</c-func>.
Без этого ограничения одно быстрое соединение может целиком
захватить рабочий процесс.
<note>
До версии 1.21.4 по умолчанию ограничения не было.
</note>
</para>

</directive>


<directive name="server">
<syntax block="yes"/>
<default/>
<context>http</context>

<para>
Задаёт конфигурацию для виртуального сервера.
Чёткого разделения виртуальных серверов на IP-based (на основании IP-адреса)
и name-based (на основании поля <header>Host</header> заголовка запроса) нет.
Вместо этого директивами <link id="listen"/> описываются все
адреса и порты, на которых нужно принимать соединения для этого сервера,
а в директиве <link id="server_name"/> указываются все имена серверов.
Примеры конфигураций описаны в документе
“<link doc="request_processing.xml"/>”.
</para>

</directive>


<directive name="server_name">
<syntax><value>имя</value> ...</syntax>
<default>""</default>
<context>server</context>

<para>
Задаёт имена виртуального сервера, например:
<example>
server {
    server_name example.com www.example.com;
}
</example>
</para>

<para>
Первое имя становится основным именем сервера.
</para>

<para>
В именах серверов можно использовать звёздочку (“<literal>*</literal>”)
для замены первой или последней части имени:
<example>
server {
    server_name example.com *.example.com www.example.*;
}
</example>
Такие имена называются именами с маской.
</para>

<para>
Два первых вышеприведённых имени можно объединить в одно:
<example>
server {
    server_name .example.com;
}
</example>
</para>

<para>
В качестве имени сервера можно также использовать регулярное выражение,
указав перед ним тильду (“<literal>~</literal>”):
<example>
server {
    server_name www.example.com ~^www\d+\.example\.com$;
}
</example>
</para>

<para>
Регулярное выражение может содержать выделения (0.7.40),
которые могут затем использоваться в других директивах:
<example>
server {
    server_name ~^(www\.)?(.+)$;

    location / {
        root /sites/$2;
    }
}

server {
    server_name _;

    location / {
        root /sites/default;
    }
}
</example>
</para>

<para>
Именованные выделения в регулярном выражении создают переменные (0.8.25),
которые могут затем использоваться в других директивах:
<example>
server {
    server_name ~^(www\.)?(?&lt;domain&gt;.+)$;

    location / {
        root /sites/$domain;
    }
}

server {
    server_name _;

    location / {
        root /sites/default;
    }
}
</example>
</para>

<para>
Если параметр директивы установлен в “<var>$hostname</var>” (0.9.4), то
подставляется имя хоста (hostname) машины.
</para>

<para>
Возможно также указать пустое имя сервера (0.7.11):
<example>
server {
    server_name www.example.com "";
}
</example>
Это позволяет обрабатывать запросы без поля <header>Host</header> заголовка
запроса в этом сервере, а не в сервере по умолчанию для данной пары адрес:порт.
Это настройка по умолчанию.
<note>
До 0.8.48 по умолчанию использовалось имя хоста (hostname) машины.
</note>
</para>

<para>
При поиске виртуального сервера по имени,
если имени соответствует несколько из указанных вариантов,
например, одновременно подходят и имя с маской, и регулярное выражение,
будет выбран первый подходящий вариант в следующем порядке приоритета:
<list type="enum">

<listitem>
точное имя
</listitem>

<listitem>
самое длинное имя с маской в начале,
например “<literal>*.example.com</literal>”
</listitem>

<listitem>
самое длинное имя с маской в конце,
например “<literal>mail.*</literal>”
</listitem>

<listitem>
первое подходящее регулярное выражение
(в порядке следования в конфигурационном файле)
</listitem>

</list>
</para>

<para>
Подробнее имена серверов обсуждаются в отдельном
<link doc="server_names.xml">документе</link>.
</para>

</directive>


<directive name="server_name_in_redirect">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает или запрещает использовать в
<link id="absolute_redirect">абсолютных</link> перенаправлениях,
выдаваемых nginx’ом, основное имя сервера, задаваемое директивой
<link id="server_name"/>.
Если использование основного имени сервера запрещено, то используется имя,
указанное в поле <header>Host</header> заголовка запроса.
Если же этого поля нет, то используется IP-адрес сервера.
</para>

<para>
Использование в перенаправлениях порта управляется
директивой <link id="port_in_redirect"/>.
</para>

</directive>


<directive name="server_names_hash_bucket_size">
<syntax><value>размер</value></syntax>
<default>32|64|128</default>
<context>http</context>

<para>
Задаёт размер корзины в хэш-таблицах имён серверов.
Значение по умолчанию зависит от размера строки кэша процессора.
Подробнее настройка хэш-таблиц обсуждается в отдельном
<link doc="../hash.xml">документе</link>.
</para>

</directive>


<directive name="server_names_hash_max_size">
<syntax><value>размер</value></syntax>
<default>512</default>
<context>http</context>

<para>
Задаёт максимальный <value>размер</value> хэш-таблиц имён серверов.
Подробнее настройка хэш-таблиц обсуждается в отдельном
<link doc="../hash.xml">документе</link>.
</para>

</directive>


<directive name="server_tokens">
<syntax>
    <literal>on</literal> |
    <literal>off</literal> |
    <literal>build</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает или запрещает выдавать версию nginx’а на страницах ошибок и
в поле <header>Server</header> заголовка ответа.
</para>

<para id="server_tokens_build">
Если указан параметр <literal>build</literal> (1.11.10),
то наряду с версией nginx’а будет также выдаваться
<link doc="../configure.xml" id="build">имя сборки</link>.
</para>

</directive>


<directive name="subrequest_output_buffer_size">
<syntax><value>размер</value></syntax>
<default>4k|8k</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.13.10</appeared-in>

<para>
Задаёт <value>размер</value> буфера, используемого для
хранения тела ответа подзапроса.
По умолчанию размер одного буфера равен размеру страницы памяти.
В зависимости от платформы это или 4K, или 8K,
однако его можно сделать меньше.
</para>

<para>
Директива применима только для подзапросов,
тело ответа которых сохраняется в памяти.
Например, подобные подзапросы создаются при помощи
<link doc="ngx_http_ssi_module.xml" id="ssi_include_set">SSI</link>.
</para>

</directive>


<directive name="tcp_nodelay">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает или запрещает использование параметра <c-def>TCP_NODELAY</c-def>.
Параметр включается при переходе соединения в состояние keep-alive.
Также, он включается на SSL-соединениях,
при небуферизованном проксировании
и при проксировании <link doc="websocket.xml">WebSocket</link>.
</para>

</directive>


<directive name="tcp_nopush">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает или запрещает использование параметра сокета
<c-def>TCP_NOPUSH</c-def> во FreeBSD или
<c-def>TCP_CORK</c-def> в Linux.
Параметр включаются только при использовании <link id="sendfile"/>.
Включение параметра  позволяет
<list type="bullet">

<listitem>
передавать заголовок ответа и начало файла в одном пакете
в Linux и во FreeBSD&nbsp;4.*;
</listitem>

<listitem>
передавать файл полными пакетами.
</listitem>

</list>
</para>

</directive>


<directive name="try_files">
<syntax><value>файл</value> ... <value>uri</value></syntax>
<syntax><value>файл</value> ... =<value>код</value></syntax>
<default/>
<context>server</context>
<context>location</context>

<para>
Проверяет существование файлов в заданном порядке и использует
для обработки запроса первый найденный файл, причём обработка
делается в контексте этого же location’а.
Путь к файлу строится из параметра <value>файл</value>
в соответствии с директивами
<link id="root"/> и <link id="alias"/>.
С помощью слэша в конце имени можно проверить существование каталога,
например, “<literal>$uri/</literal>”.
В случае, если ни один файл не найден, то делается внутреннее
перенаправление на <value>uri</value>, заданный последним параметром.
Например:
<example>
location /images/ {
    try_files $uri /images/default.gif;
}

location = /images/default.gif {
    expires 30s;
}
</example>
Последний параметр может также указывать на именованный location,
как в примерах ниже.
С версии 0.7.51 последний параметр может также быть <value>кодом</value>:
<example>
location / {
    try_files $uri $uri/index.html $uri.html =404;
}
</example>
</para>

<para>
Пример использования при проксировании Mongrel:
<example>
location / {
    try_files /system/maintenance.html
              $uri $uri/index.html $uri.html
              @mongrel;
}

location @mongrel {
    proxy_pass http://mongrel;
}
</example>
</para>

<para>
Пример использования вместе с Drupal/FastCGI:
<example>
location / {
    try_files $uri $uri/ @drupal;
}

location ~ \.php$ {
    try_files $uri @drupal;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
    fastcgi_param SCRIPT_NAME     $fastcgi_script_name;
    fastcgi_param QUERY_STRING    $args;

    ... прочие fastcgi_param
}

location @drupal {
    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to/index.php;
    fastcgi_param SCRIPT_NAME     /index.php;
    fastcgi_param QUERY_STRING    q=$uri&amp;$args;

    ... прочие fastcgi_param
}
</example>
В следующем примере директива <literal>try_files</literal>
<example>
location / {
    try_files $uri $uri/ @drupal;
}
</example>
аналогична директивам
<example>
location / {
    error_page 404 = @drupal;
    log_not_found off;
}
</example>
А здесь
<example>
location ~ \.php$ {
    try_files $uri @drupal;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;

    ...
}
</example>
<literal>try_files</literal> проверяет существование PHP-файла,
прежде чем передать запрос FastCGI-серверу.
</para>

<para>
Пример использования вместе с Wordpress и Joomla:
<example>
location / {
    try_files $uri $uri/ @wordpress;
}

location ~ \.php$ {
    try_files $uri @wordpress;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
    ... прочие fastcgi_param
}

location @wordpress {
    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to/index.php;
    ... прочие fastcgi_param
}
</example>
</para>

</directive>


<directive name="types">
<syntax block="yes"/>
<default>
    text/html  html;
    image/gif  gif;
    image/jpeg jpg;
</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт соответствие расширений имён файлов и MIME-типов ответов.
Расширения нечувствительны к регистру символов.
Одному MIME-типу может соответствовать несколько расширений, например:
<example>
types {
    application/octet-stream bin exe dll;
    application/octet-stream deb;
    application/octet-stream dmg;
}
</example>
</para>

<para>
Достаточно полная таблица соответствий входит в дистрибутив nginx
и находится в файле <path>conf/mime.types</path>.
</para>

<para>
Для того чтобы для определённого location’а для всех ответов
выдавался MIME-тип “<literal>application/octet-stream</literal>”,
можно использовать следующее:
<example>
location /download/ {
    types        { }
    default_type application/octet-stream;
}
</example>
</para>

</directive>


<directive name="types_hash_bucket_size">
<syntax><value>размер</value></syntax>
<default>64</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт размер корзины в хэш-таблицах типов.
Подробнее настройка хэш-таблиц обсуждается в отдельном
<link doc="../hash.xml">документе</link>.
<note>
До версии 1.5.13
значение по умолчанию зависело от размера строки кэша процессора.
</note>
</para>

</directive>


<directive name="types_hash_max_size">
<syntax><value>размер</value></syntax>
<default>1024</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт максимальный <value>размер</value> хэш-таблиц типов.
Подробнее настройка хэш-таблиц обсуждается в отдельном
<link doc="../hash.xml">документе</link>.
</para>

</directive>


<directive name="underscores_in_headers">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>

<para>
Разрешает или запрещает использование символов подчёркивания в
полях заголовка запроса клиента.
Если использование символов подчёркивания запрещено, поля заголовка запроса, в
именах которых есть подчёркивания,
помечаются как недопустимые и подпадают под действие директивы
<link id="ignore_invalid_headers"/>.
</para>

<para>
Если директива указана на уровне <link id="server"/>,
то может использоваться значение из сервера по умолчанию.
Подробнее см. в разделе
“<link doc="server_names.xml" id="virtual_server_selection">Выбор
виртуального сервера</link>”.
</para>

</directive>


<directive name="variables_hash_bucket_size">
<syntax><value>размер</value></syntax>
<default>64</default>
<context>http</context>

<para>
Задаёт размер корзины в хэш-таблице переменных.
Подробнее настройка хэш-таблиц обсуждается в отдельном
<link doc="../hash.xml">документе</link>.
</para>

</directive>


<directive name="variables_hash_max_size">
<syntax><value>размер</value></syntax>
<default>1024</default>
<context>http</context>

<para>
Задаёт максимальный <value>размер</value> хэш-таблицы переменных.
Подробнее настройка хэш-таблиц обсуждается в отдельном
<link doc="../hash.xml">документе</link>.
<note>
До версии 1.5.13 по умолчанию использовалось значение 512.
</note>
</para>

</directive>

</section>


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

<para>
Модуль <literal>ngx_http_core_module</literal> поддерживает встроенные
переменные, имена которых совпадают с именами переменных веб-сервера Apache.
Прежде всего, это переменные, представляющие из себя поля заголовка
запроса клиента, такие как <var>$http_user_agent</var>, <var>$http_cookie</var>
и тому подобное.
Кроме того, есть и другие переменные:
<list type="tag">

<tag-name id="var_arg_"><var>$arg_</var><value>имя</value></tag-name>
<tag-desc>
аргумент <value>имя</value> в строке запроса
</tag-desc>

<tag-name id="var_args"><var>$args</var></tag-name>
<tag-desc>
аргументы в строке запроса
</tag-desc>

<tag-name id="var_binary_remote_addr"><var>$binary_remote_addr</var></tag-name>
<tag-desc>
адрес клиента в бинарном виде, длина значения всегда 4 байта
для IPv4-адресов или 16 байт для IPv6-адресов
</tag-desc>

<tag-name id="var_body_bytes_sent"><var>$body_bytes_sent</var></tag-name>
<tag-desc>
число байт, переданное клиенту, без учёта заголовка ответа;
переменная совместима с параметром “<literal>%B</literal>” модуля Apache
<literal>mod_log_config</literal>
</tag-desc>

<tag-name id="var_bytes_sent"><var>$bytes_sent</var></tag-name>
<tag-desc>
число байт, переданных клиенту (1.3.8, 1.2.5)
</tag-desc>

<tag-name id="var_connection"><var>$connection</var></tag-name>
<tag-desc>
порядковый номер соединения (1.3.8, 1.2.5)
</tag-desc>

<tag-name id="var_connection_requests"><var>$connection_requests</var></tag-name>
<tag-desc>
текущее число запросов в соединении (1.3.8, 1.2.5)
</tag-desc>

<tag-name id="var_connection_time"><var>$connection_time</var></tag-name>
<tag-desc>
время соединения в секундах с точностью до миллисекунд (1.19.10)
</tag-desc>

<tag-name id="var_content_length"><var>$content_length</var></tag-name>
<tag-desc>
поле <header>Content-Length</header> заголовка запроса
</tag-desc>

<tag-name id="var_content_type"><var>$content_type</var></tag-name>
<tag-desc>
поле <header>Content-Type</header> заголовка запроса
</tag-desc>

<tag-name id="var_cookie_"><var>$cookie_</var><value>имя</value></tag-name>
<tag-desc>
cookie <value>имя</value>
</tag-desc>

<tag-name id="var_document_root"><var>$document_root</var></tag-name>
<tag-desc>
значение директивы <link id="root"/> или <link id="alias"/>
для текущего запроса
</tag-desc>

<tag-name id="var_document_uri"><var>$document_uri</var></tag-name>
<tag-desc>
то же, что и <var>$uri</var>
</tag-desc>

<tag-name id="var_host"><var>$host</var></tag-name>
<tag-desc>
в порядке приоритета:
имя хоста из строки запроса, или
имя хоста из поля <header>Host</header> заголовка запроса, или
имя сервера, соответствующего запросу
</tag-desc>

<tag-name id="var_hostname"><var>$hostname</var></tag-name>
<tag-desc>
имя хоста
</tag-desc>

<tag-name id="var_http_"><var>$http_</var><value>имя</value></tag-name>
<tag-desc>
произвольное поле заголовка запроса;
последняя часть имени переменной соответствует имени поля, приведённому
к нижнему регистру, с заменой символов тире на символы подчёркивания
</tag-desc>

<tag-name id="var_https"><var>$https</var></tag-name>
<tag-desc>
“<literal>on</literal>”
если соединение работает в режиме SSL,
либо пустая строка
</tag-desc>

<tag-name id="var_is_args"><var>$is_args</var></tag-name>
<tag-desc>
“<literal>?</literal>”, если в строке запроса есть аргументы,
и пустая строка, если их нет
</tag-desc>

<tag-name id="var_limit_rate"><var>$limit_rate</var></tag-name>
<tag-desc>
установка этой переменной позволяет ограничивать скорость
передачи ответа, см. <link id="limit_rate"/>
</tag-desc>

<tag-name id="var_msec"><var>$msec</var></tag-name>
<tag-desc>
текущее время в секундах с точностью до миллисекунд (1.3.9, 1.2.6)
</tag-desc>

<tag-name id="var_nginx_version"><var>$nginx_version</var></tag-name>
<tag-desc>
версия nginx
</tag-desc>

<tag-name id="var_pid"><var>$pid</var></tag-name>
<tag-desc>
номер (PID) рабочего процесса
</tag-desc>

<tag-name id="var_pipe"><var>$pipe</var></tag-name>
<tag-desc>
“<literal>p</literal>” если запрос был pipelined, иначе “<literal>.</literal>”
(1.3.12, 1.2.7)
</tag-desc>

<tag-name id="var_proxy_protocol_addr"><var>$proxy_protocol_addr</var></tag-name>
<tag-desc>
адрес клиента, полученный из заголовка протокола PROXY (1.5.12)
<para>
Протокол PROXY должен быть предварительно включён при помощи установки
параметра <literal>proxy_protocol</literal> в директиве <link id="listen"/>.
</para>
</tag-desc>

<tag-name id="var_proxy_protocol_port"><var>$proxy_protocol_port</var></tag-name>
<tag-desc>
порт клиента, полученный из заголовка протокола PROXY (1.11.0)
<para>
Протокол PROXY должен быть предварительно включён при помощи установки
параметра <literal>proxy_protocol</literal> в директиве <link id="listen"/>.
</para>
</tag-desc>

<tag-name id="var_proxy_protocol_server_addr"><var>$proxy_protocol_server_addr</var></tag-name>
<tag-desc>
адрес сервера, полученный из заголовка протокола PROXY (1.17.6)
<para>
Протокол PROXY должен быть предварительно включён при помощи установки
параметра <literal>proxy_protocol</literal> в директиве <link id="listen"/>.
</para>
</tag-desc>

<tag-name id="var_proxy_protocol_server_port"><var>$proxy_protocol_server_port</var></tag-name>
<tag-desc>
порт сервера, полученный из заголовка протокола PROXY (1.17.6)
<para>
Протокол PROXY должен быть предварительно включён при помощи установки
параметра <literal>proxy_protocol</literal> в директиве <link id="listen"/>.
</para>
</tag-desc>

<tag-name id="var_proxy_protocol_tlv_"><var>$proxy_protocol_tlv_</var><value>имя</value></tag-name>
<tag-desc>
TLV, полученный из заголовка протокола PROXY (1.23.2).
<literal>Имя</literal> может быть именем типа TLV или его числовым значением.
В последнем случае значение задаётся в шестнадцатеричном виде
и должно начинаться с <literal>0x</literal>:

<example>
$proxy_protocol_tlv_alpn
$proxy_protocol_tlv_0x01
</example>
SSL TLV могут также быть доступны как по имени типа TLV,
так и по его числовому значению,
оба должны начинаться с <literal>ssl_</literal>:
<example>
$proxy_protocol_tlv_ssl_version
$proxy_protocol_tlv_ssl_0x21
</example>

<para>
Поддерживаются следующие имена типов TLV:
<list type="bullet">

<listitem>
<literal>alpn</literal> (<literal>0x01</literal>)&mdash;
протокол более высокого уровня, используемый поверх соединения
</listitem>

<listitem>
<literal>authority</literal> (<literal>0x02</literal>)&mdash;
значение имени хоста, передаваемое клиентом
</listitem>

<listitem>
<literal>unique_id</literal> (<literal>0x05</literal>)&mdash;
уникальный идентификатор соединения
</listitem>

<listitem>
<literal>netns</literal> (<literal>0x30</literal>)&mdash;
имя пространства имён
</listitem>

<listitem>
<literal>ssl</literal> (<literal>0x20</literal>)&mdash;
структура SSL TLV в бинарном виде
</listitem>

</list>
</para>

<para>
Поддерживаются следующие имена типов SSL TLV:
<list type="bullet">

<listitem>
<literal>ssl_version</literal> (<literal>0x21</literal>)&mdash;
версия SSL, используемая в клиентском соединении
</listitem>

<listitem>
<literal>ssl_cn</literal> (<literal>0x22</literal>)&mdash;
Common Name сертификата
</listitem>

<listitem>
<literal>ssl_cipher</literal> (<literal>0x23</literal>)&mdash;
имя используемого шифра
</listitem>

<listitem>
<literal>ssl_sig_alg</literal> (<literal>0x24</literal>)&mdash;
алгоритм, используемый для подписи сертификата
</listitem>

<listitem>
<literal>ssl_key_alg</literal> (<literal>0x25</literal>)&mdash;
алгоритм публичного ключа
</listitem>

</list>
</para>

<para>
Также поддерживается следующее специальное имя типа SSL TLV:
<list type="bullet">

<listitem>
<literal>ssl_verify</literal>&mdash;
результат проверки клиентского сертификата:
<literal>0</literal>, если клиент предоставил сертификат
и он был успешно верифицирован,
либо ненулевое значение
</listitem>

</list>
</para>

<para>
Протокол PROXY должен быть предварительно включён при помощи установки
параметра <literal>proxy_protocol</literal> в директиве <link id="listen"/>.
</para>
</tag-desc>

<tag-name id="var_query_string"><var>$query_string</var></tag-name>
<tag-desc>
то же, что и <var>$args</var>
</tag-desc>

<tag-name id="var_realpath_root"><var>$realpath_root</var></tag-name>
<tag-desc>
абсолютный путь, соответствующий
значению директивы <link id="root"/> или <link id="alias"/>
для текущего запроса,
в котором все символические ссылки преобразованы в реальные пути
</tag-desc>

<tag-name id="var_remote_addr"><var>$remote_addr</var></tag-name>
<tag-desc>
адрес клиента
</tag-desc>

<tag-name id="var_remote_port"><var>$remote_port</var></tag-name>
<tag-desc>
порт клиента
</tag-desc>

<tag-name id="var_remote_user"><var>$remote_user</var></tag-name>
<tag-desc>
имя пользователя, использованное в Basic аутентификации
</tag-desc>

<tag-name id="var_request"><var>$request</var></tag-name>
<tag-desc>
первоначальная строка запроса целиком
</tag-desc>

<tag-name id="var_request_body"><var>$request_body</var></tag-name>
<tag-desc>
тело запроса
<para>
Значение переменной появляется в location’ах, обрабатываемых
директивами
<link doc="ngx_http_proxy_module.xml" id="proxy_pass"/>,
<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>,
<link doc="ngx_http_uwsgi_module.xml" id="uwsgi_pass"/>
и
<link doc="ngx_http_scgi_module.xml" id="scgi_pass"/>,
когда тело было прочитано в
<link id="client_body_buffer_size">буфер в памяти</link>.
</para>
</tag-desc>

<tag-name id="var_request_body_file"><var>$request_body_file</var></tag-name>
<tag-desc>
имя временного файла, в котором хранится тело запроса
<para>
По завершении обработки файл необходимо удалить.
Для того чтобы тело запроса всегда записывалось в файл,
следует включить <link id="client_body_in_file_only"/>.
При передаче имени временного файла в проксированном запросе
или в запросе к FastCGI/uwsgi/SCGI-серверу следует запретить передачу самого
тела директивами
<link doc="ngx_http_proxy_module.xml" id="proxy_pass_request_body">
proxy_pass_request_body off</link>,
<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass_request_body">
fastcgi_pass_request_body off</link>,
<link doc="ngx_http_uwsgi_module.xml" id="uwsgi_pass_request_body">
uwsgi_pass_request_body off</link>
или
<link doc="ngx_http_scgi_module.xml" id="scgi_pass_request_body">
scgi_pass_request_body off</link>
соответственно.
</para>
</tag-desc>

<tag-name id="var_request_completion"><var>$request_completion</var></tag-name>
<tag-desc>
“<literal>OK</literal>” если запрос завершился,
либо пустая строка
</tag-desc>

<tag-name id="var_request_filename"><var>$request_filename</var></tag-name>
<tag-desc>
путь к файлу для текущего запроса, формируемый из директив
<link id="root"/> или <link id="alias"/> и URI запроса
</tag-desc>

<tag-name id="var_request_id"><var>$request_id</var></tag-name>
<tag-desc>
уникальный идентификатор запроса,
сформированный из 16 случайных байт, в шестнадцатеричном виде (1.11.0)
</tag-desc>

<tag-name id="var_request_length"><var>$request_length</var></tag-name>
<tag-desc>
длина запроса (включая строку запроса, заголовок и тело запроса)
(1.3.12, 1.2.7)
</tag-desc>

<tag-name id="var_request_method"><var>$request_method</var></tag-name>
<tag-desc>
метод запроса, обычно
“<literal>GET</literal>” или “<literal>POST</literal>”
</tag-desc>

<tag-name id="var_request_time"><var>$request_time</var></tag-name>
<tag-desc>
время обработки запроса в секундах с точностью до миллисекунд
(1.3.9, 1.2.6);
время, прошедшее с момента чтения первых байт от клиента
</tag-desc>

<tag-name id="var_request_uri"><var>$request_uri</var></tag-name>
<tag-desc>
первоначальный URI запроса целиком (с аргументами)
</tag-desc>

<tag-name id="var_scheme"><var>$scheme</var></tag-name>
<tag-desc>
схема запроса, “<literal>http</literal>” или “<literal>https</literal>”
</tag-desc>

<tag-name id="var_sent_http_"><var>$sent_http_</var><value>имя</value></tag-name>
<tag-desc>
произвольное поле заголовка ответа;
последняя часть имени переменной соответствует имени поля, приведённому
к нижнему регистру, с заменой символов тире на символы подчёркивания
</tag-desc>

<tag-name id="var_sent_trailer_"><var>$sent_trailer_</var><value>имя</value></tag-name>
<tag-desc>
произвольное поле, отправленное в конце ответа (1.13.2);
последняя часть имени переменной соответствует имени поля, приведённому
к нижнему регистру, с заменой символов тире на символы подчёркивания
</tag-desc>

<tag-name id="var_server_addr"><var>$server_addr</var></tag-name>
<tag-desc>
адрес сервера, принявшего запрос
<para>
Получение значения этой переменной обычно требует одного системного вызова.
Чтобы избежать системного вызова, в директивах <link id="listen"/>
следует указывать адреса и использовать параметр <literal>bind</literal>.
</para>
</tag-desc>

<tag-name id="var_server_name"><var>$server_name</var></tag-name>
<tag-desc>
имя сервера, принявшего запрос
</tag-desc>

<tag-name id="var_server_port"><var>$server_port</var></tag-name>
<tag-desc>
порт сервера, принявшего запрос
</tag-desc>

<tag-name id="var_server_protocol"><var>$server_protocol</var></tag-name>
<tag-desc>
протокол запроса, обычно
“<literal>HTTP/1.0</literal>”,
“<literal>HTTP/1.1</literal>”,
“<link doc="ngx_http_v2_module.xml">HTTP/2.0</link>”
или
“<link doc="ngx_http_v3_module.xml">HTTP/3.0</link>”
</tag-desc>

<tag-name id="var_status"><var>$status</var></tag-name>
<tag-desc>
статус ответа (1.3.2, 1.2.2)
</tag-desc>

<tag-name id="var_time_iso8601"><var>$time_iso8601</var></tag-name>
<tag-desc>
локальное время в формате по стандарту ISO 8601 (1.3.12, 1.2.7)
</tag-desc>

<tag-name id="var_time_local"><var>$time_local</var></tag-name>
<tag-desc>
локальное время в Common Log Format (1.3.12, 1.2.7)
</tag-desc>

<tag-name id="var_tcpinfo_">
<var>$tcpinfo_rtt</var>,
<var>$tcpinfo_rttvar</var>,
<var>$tcpinfo_snd_cwnd</var>,
<var>$tcpinfo_rcv_space</var>
</tag-name>
<tag-desc>
информация о клиентском TCP-соединении; доступна на системах,
поддерживающих параметр сокета <c-def>TCP_INFO</c-def>
</tag-desc>

<tag-name id="var_uri"><var>$uri</var></tag-name>
<tag-desc>
текущий URI запроса в <link id="location">нормализованном</link> виде
<para>
Значение <var>$uri</var> может изменяться в процессе обработки запроса,
например, при внутренних перенаправлениях
или при использовании индексных файлов.
</para>
</tag-desc>

</list>
</para>

</section>

</module>