Mercurial > hg > nginx-site

view xml/ru/docs/http/ngx_http_core_module.xml @ 280:cbb789d3ce5e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fixed grammar error.
author Ruslan Ermilov <ru@nginx.com>
date Tue, 27 Dec 2011 09:57:05 +0000
parents 457c54242cfa
children 4a0fe9283dc7
line wrap: on
line source

<?xml version="1.0"?>

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

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

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

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

<para>
Разрешает или запрещает использование файлового асинхронного ввода-вывода (AIO)
во FreeBSD и Linux.
</para>

<para>
Во FreeBSD AIO можно использовать, начиная с FreeBSD&nbsp;4.3.
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>
Для работы AIO нужно выключить
<link id="sendfile"/>:
<example>
location /video/ {
    sendfile       off;
    aio            on;
    output_buffers 1 64k;
}
</example>
</para>

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

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

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

</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>
Задаёт максимально допустимый размер тела запроса клиента,
указываемый в поле
<header>Content-Length</header>
заголовка запроса.
Если размер больше заданного, то клиенту возвращается ошибка
<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</default>
<context>http</context>
<context>server</context>

<para>
Позволяет производить точную настройку выделений памяти
под конкретные соединения.
Эта директива не оказывает существенного влияния на
производительность и её не следует использовать.
</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-тип ответов по умолчанию.
См. также директиву <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> (Mac OS X)
или функцию <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="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, который будет показываться для указанных ошибок.
Директивы <literal>error_page</literal> наследуются с предыдущего уровня
при условии, что на данном уровне не описаны свои директивы
<literal>error_page</literal>.
В значении URI можно использовать переменные.
</para>

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

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

<para>
Если ошибочный ответ обрабатывается проксированным сервером или
FastCGI-сервером, и этот сервер может вернуть разные коды ответов,
например, 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>

</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>
не проверять поле
<header>If-Modified-Since</header> заголовка запроса (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>

</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"/>;
</listitem>

<listitem>
подзапросы, формируемые командой
“<command>include virtual</command>”
модуля
<link doc="ngx_http_ssi_module.xml">ngx_http_ssi_module</link>;
ngx_http_ssi_module;
</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>
</para>

</directive>


<directive name="keepalive_disable">
<syntax><literal>none</literal> | <value>браузер</value> ...</syntax>
<default>msie6 safari</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.
Значение <literal>none</literal> разрешает keep-alive соединения
со всеми браузерами.
</para>

</directive>


<directive name="keepalive_requests">
<syntax><value>число</value></syntax>
<default>100</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>0.8.0</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
соединение с клиентом не будет закрыто со стороны сервера.
Второй необязательный параметр задаёт значение в поле
<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>

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

<para>
Если необходимо ограничить скорость для части клиентов на уровне
<link id="server">сервера</link>, то директива <literal>limit_rate</literal>
для этого не подходит.
Вместо этого следует задать желаемое ограничение скорости в переменной
<var>$limit_rate</var>:
<example>
server {

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

    ...
}
</example>
</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>
Задаёт начальный объём данных, после передачи которого начинает
ограничиваться скорость передачи ответа клиенту.
</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>

</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>setfib</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>ssl</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>setfib</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>ssl</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>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>ssl</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> может быть именем хоста, например:
<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 [fe80::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>listen</literal> можно также указать несколько
дополнительных параметров, специфичных для системных вызовов
<c-func>listen</c-func> и <c-func>bind</c-func>.
Эти параметры можно задать в любой директиве <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).
В настоящий момент это работает только на FreeBSD.
</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
и 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-фильтра.
Работает только на FreeBSD, можно использовать два фильтра —
<literal>dataready</literal> и <literal>httpready</literal>.
По сигналу <c-def>SIGHUP</c-def> accept-фильтр можно менять только в
последних версиях FreeBSD, начиная с 6.0, 5.4-STABLE и 4.11-STABLE.
</tag-desc>

<tag-name>
<literal>deferred</literal>
</tag-name>
<tag-desc>
указывает использовать отложенный <c-func>accept</c-func> на Linux
с помощью опции <c-def>TCP_DEFER_ACCEPT</c-def>.
</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>backlog</literal>,
<literal>rcvbuf</literal>, <literal>sndbuf</literal>,
<literal>accept_filter</literal>, <literal>deferred</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>
для слушающего сокета.
Установить этот параметр можно только один раз на старте.
</tag-desc>

<tag-name>
<literal>ssl</literal>
</tag-name>
<tag-desc>
этот параметр (0.7.14) не имеет отношения к системным вызовам
<c-func>listen</c-func> и <c-func>bind</c-func>, а позволяет указать,
что все соединения, принимаемые на этом порту, должны работать
в режиме SSL.
Это позволяет задать компактную конфигурацию для сервера,
работающего сразу в двух режимах — HTTP и HTTPS.
<example>
listen 80;
listen 443 default ssl;
</example>
</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+)
их можно сконфигурировать с помощью параметров <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 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 запроса.
location можно задать префиксной строкой или регулярным выражением.
Регулярные выражения задаются либо с префиксом “<literal>~*</literal>”
(для поиска совпадения без учёта регистра символов),
либо с префиксом “<literal>~</literal>” (с учётом регистра).
Чтобы найти location, соответствующий запросу, вначале проверяются
location'ы, заданные префиксными строками (префиксные location'ы).
Среди них ищется максимальное совпадение.
Затем проверяются регулярные выражения, в порядке их следования
в конфигурационном файле.
Проверка регулярных выражений прекращается после первого же совпадения,
и используется соответствующая конфигурация.
Если совпадение с регулярным выражением не найдено, то используется
конфигурация максимально совпавшего префиксного location'а.
</para>

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

<para>
Для операционных систем, нечувствительных к регистру символов, таких
как Mac OS X и 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 ^~ /images/ {
    [ конфигурация В ]
}

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

<para>
Префикс “<literal>@</literal>” задаёт именованный location.
Такой location не используется при обычной обработке запросов, а
предназначен только для перенаправления в него запросов.
Такие location'ы не могут быть вложенными и не могут содержать
вложенные location'ы.
</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>

<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"/>
в сервере по умолчанию, то её значение распространяется на
все виртуальные сервера, слушающие на том же адресе и порту.
</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="optimize_server_names">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>

<para>
Директива устарела, вместо неё следует использовать директиву
<link id="server_name_in_redirect"/>.
</para>

<!--
<para>
Разрешает или запрещает оптимизировать проверку имени хоста в name-based
виртуальных серверах.
Проверка в частности влияет на имя хоста, используемого в перенаправлениях.
Если оптимизация разрешена и все name-based сервера, слушающие на одной
паре адрес:порт, имеют одинаковую конфигурацию, то во время исполнения запроса
имена не проверяются и в перенаправлениях используется первое имя сервера.
Если в перенаправлении нужно использовать имя хоста, переданное клиентом,
то оптимизацию нужно выключить.
</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>
Разрешает или запрещает указывать порт в перенаправлениях, выдаваемых 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"/>.
</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>
Разрешает или запрещает сброс соединений по таймауту.
Сброс делается следующим образом — перед закрытием сокета для него
ставится опция
<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>]</syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт серверы DNS, используемые для преобразования имён апстрим серверов
в адреса, например:
<example>
resolver 127.0.0.1 192.0.2.1;
</example>
Параметр <value>адрес</value> может быть задан либо
IPv4-адресом, либо именем хоста;
во втором случае используется первый полученный IPv4-адрес.
Серверы DNS опрашиваются циклически.
<note>
До версии 1.1.7 можно было задать лишь один DNS-сервер.
</note>
По умолчанию nginx кэширует ответы, используя значение TTL из ответа.
Необязательный параметр <literal>valid</literal> позволяет это
переопределить:
<example>
resolver 127.0.0.1 192.0.2.1 valid=30s;
</example>
<note>
До версии 1.1.9 настройка времени кэширования была невозможна
и nginx всегда кэшировал ответы на срок в 5 минут.
</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>
разрешают доступ.
</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="satisfy_any">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Эта директива была переименована в директиву
<link id="satisfy">satisfy any</link>.
</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>,
с указанным размером.
</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>

</directive>


<directive name="sendfile_max_chunk">

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

<para>
При установке в ненулевое значение ограничивает объём данных,
который может передан за один вызов <c-func>sendfile</c-func>.
Без этого ограничения одно быстрое соединение может целиком
захватить рабочий процесс.
</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="../virtual_hosts.xml">
настройке виртуальных серверов</link>.
</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>
Первое имя становится основным именем сервера.
В именах серверов можно использовать звёздочку (“<literal>*</literal>”)
для замены первой или последней части имени:
<example>
server {
    server_name example.com *.example.com www.example.*;
}
</example>
</para>

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

<para>
Если параметр равен “<var>$hostname</var>” (0.9.4), то
подставляется имя хоста (hostname) машины.
</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>
Возможно также указать пустое имя сервера (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>

</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>
Разрешает или запрещает использовать в перенаправлениях, выдаваемых 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></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает или запрещает выдавать версию nginx'а в сообщениях об ошибках и
в поле <header>Server</header> заголовка ответа.
</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.
</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 последний параметр может также быть кодом:
<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>32|64|128</default>
<context>http</context>
<context>server</context>
<context>location</context>

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

</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>512</default>
<context>http</context>

<para>
Задаёт максимальный <value>размер</value> хэш-таблицы переменных.
Подробнее смотрите в документе по
<link doc="../hash.xml">настройке хэшей</link>.
</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><var>$arg_</var><value>имя</value></tag-name>
<tag-desc>
аргумент <value>имя</value> в строке запроса
</tag-desc>

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

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

<tag-name><var>$body_bytes_sent</var></tag-name>
<tag-desc>
число байт, переданное клиенту, без учёта заголовка ответа
</tag-desc>

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

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

<tag-name><var>$cookie_</var><value>имя</value></tag-name>
<tag-desc>
cookie <value>имя</value>
</tag-desc>

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

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

<tag-name><var>$host</var></tag-name>
<tag-desc>
поле <header>Host</header> заголовка запроса,
или имя сервера, соответствующего запросу, если этого поля нет
</tag-desc>

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

<tag-name><var>$http_</var><value>имя</value></tag-name>
<tag-desc>
поле <value>имя</value> заголовка запроса
</tag-desc>

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

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

<tag-name><var>$limit_rate</var></tag-name>
<tag-desc>
позволяет ограничивать скорость соединения
</tag-desc>

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

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

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

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

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

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

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

<tag-name><var>$request</var></tag-name>
<tag-desc>
оригинальная строка запроса целиком
</tag-desc>

<tag-name><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"/>.
</para>
</tag-desc>

<tag-name><var>$request_body_file</var></tag-name>
<tag-desc>
имя временного файла, в котором хранится тело запроса
<para>
По завершению обработки файл необходимо удалить.
Для того, чтобы тело запроса всегда записывалось в файл,
следует указать
<link id="client_body_in_file_only">client_body_in_file_only on</link>.
При передаче имени временного файла в проксированном запросе
или в запросе к FastCGI-серверу следует запретить передачу самого
тела директивами
<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>
соответственно.
</para>
</tag-desc>

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

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

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

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

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

<tag-name><var>$sent_http_</var><value>имя</value></tag-name>
<tag-desc>
поле <value>имя</value> заголовка ответа
</tag-desc>

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

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

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

<tag-name><var>$server_protocol</var></tag-name>
<tag-desc>
протокол сервера, обычно
“<literal>HTTP/1.0</literal>”
или
“<literal>HTTP/1.1</literal>”
</tag-desc>

<tag-name><var>$uri</var></tag-name>
<tag-desc>
текущий URI запроса
<para>
Он может отличаться от первоначального, например, при внутренних
перенаправлениях или при использовании индексных файлов.
</para>
</tag-desc>

</list>
</para>

</section>

</module>