Mercurial > hg > nginx-site
view xml/ru/docs/http/ngx_http_core_module.xml @ 799:9e5847af3b2d
Documented the "proxy_headers_hash_bucket/max_size" directives.
author | Vladimir Homutov <vl@nginx.com> |
---|---|
date | Wed, 26 Dec 2012 12:18:18 +0000 |
parents | 32b8498cfb40 |
children | 7c72c3e67e77 |
line wrap: on
line source
<?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="13"> <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 4.3. AIO можно либо собрать в ядре статически: <example> options VFS_AIO </example> либо загрузить динамически через загружаемый модуль ядра: <example> kldload aio </example> </para> <para> В версиях FreeBSD 5 и 6 включение AIO статически или динамически на стадии загрузки ядра приводит к тому, что вся сетевая подсистема будет использовать блокировку Giant, что может негативно сказаться на производительности системы в целом. Это ограничение устранено во FreeBSD 6.4-STABLE в 2009 году и во FreeBSD 7. Однако, начиная с FreeBSD 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 5.2.1 и nginx 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-тип ответов по умолчанию. Соответствие расширений имён файлов 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="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, который будет показываться для указанных ошибок. Директивы <literal>error_page</literal> наследуются с предыдущего уровня при условии, что на данном уровне не описаны свои директивы <literal>error_page</literal>. В значении <literal>uri</literal> можно использовать переменные. </para> <para> Пример: <example> error_page 404 /404.html; error_page 500 502 503 504 /50x.html; </example> </para> <para> Кроме того, можно поменять код ответа на другой, используя синтаксис вида “<literal>=</literal><value>ответ</value>”, например: <example> error_page 404 =200 /empty.gif; </example> </para> <para> Если ошибочный ответ обрабатывается проксированным сервером или FastCGI-сервером, и этот сервер может вернуть разные коды ответов, например, 200, 302, 401 или 404, то можно выдавать возвращаемый им код: <example> error_page 404 = /404.php; </example> </para> <para> Также существует возможность использовать перенаправления для обработки ошибок: <example> error_page 403 http://example.com/forbidden.html; error_page 404 =301 http://example.com/notfound.html; </example> В этому случае клиенту возвращается код ответа 302. Его можно изменить только на один из кодов статуса, относящихся к перенаправлениям (301, 302, 303 и 307). </para> <para> Если при внутреннем перенаправлении не нужно менять URI, то можно передать обработку ошибки в именованный location: <example> location / { error_page 404 = @fallback; } location @fallback { proxy_pass http://backend; } </example> </para> <para> <note> Если при обработке <literal>uri</literal> происходит ошибка, клиенту возвращается ответ с кодом статуса последней случившейся ошибки. </note> </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> не проверять поле <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> <para> Директива может быть указана на уровне <link id="server"/> в сервере по умолчанию. В этом случае её значение распространяется на все виртуальные серверы, слушающие на том же адресе и порту. </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>; </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 и подобными им браузерами на Mac OS X и подобных ей ОС. Значение <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>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 отключает ограничение скорости. <!-- Чем меньше скорость, тем более аккуратным будет ограничение. --> Ограничение устанавливается на запрос, поэтому если клиент одновременно откроет два соединения, суммарная скорость будет вдвое выше заданного ограничения. </para> <para> Ограничение скорости можно также задать в переменной <var>$limit_rate</var>. Это может быть полезно в случаях, когда скорость нужно ограничивать в зависимости от какого-либо условия: <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"/>. </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> можно также указать несколько дополнительных параметров, специфичных для связанных с сокетами системных вызовов. Эти параметры можно задать в любой директиве <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>backlog</literal>=<value>число</value> </tag-name> <tag-desc> задаёт параметр <literal>backlog</literal> в вызове <c-func>listen</c-func>, который ограничивает максимальный размер очереди ожидающих приёма соединений. По умолчанию <literal>backlog</literal> устанавливается равным -1 для FreeBSD и Mac OS X, и 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>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>), будет ли слушающий на wildcard-адресе <literal>[::]</literal> IPv6-сокет принимать только IPv6-соединения, или же одновременно IPv6- и IPv4-соединения. По умолчанию параметр включён. Установить его можно только один раз на старте. <note> До версии 1.3.4, если этот параметр не был задан явно, то для сокета действовали настройки операционной системы. </note> </tag-desc> <tag-name> <literal>ssl</literal> </tag-name> <tag-desc> этот параметр (0.7.14) не имеет отношения к связанным с сокетами системным вызовам, а позволяет указать, что все соединения, принимаемые на этом порту, должны работать в режиме SSL. Это позволяет задать компактную <link doc="configuring_https_servers.xml" id="single_http_https_server">конфигурацию</link> для сервера, работающего сразу в двух режимах — HTTP и HTTPS. </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’а. </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 /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> Префикс “<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> <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"/> в сервере по умолчанию. В этом случае её значение распространяется на все виртуальные серверы, слушающие на том же адресе и порту. </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 2.0+ и FreeBSD 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 9.0-CURRENT. Для FreeBSD 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> Разрешает или запрещает сброс соединений по таймауту. Сброс делается следующим образом — перед закрытием сокета для него ставится параметр <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 [::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> По умолчанию nginx кэширует ответы, используя значение TTL из ответа. Необязательный параметр <literal>valid</literal> позволяет это переопределить: <example> resolver 127.0.0.1 [::1]:5353 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> Эта директива была заменена параметром <literal>any</literal> директивы <link id="satisfy"/>. </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="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\.)?(?<domain>.+)$; 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> Разрешает или запрещает использовать в перенаправлениях, выдаваемых 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 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&$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> <para> Директива может быть указана на уровне <link id="server"/> в сервере по умолчанию. В этом случае её значение распространяется на все виртуальные серверы, слушающие на том же адресе и порту. </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 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 байта </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_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_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"/>. </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-серверу следует запретить передачу самого тела директивами <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 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_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_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>” </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_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>