Mercurial > hg > nginx-site
view xml/ru/docs/http/ngx_http_core_module.xml @ 426:1d6dc85ed324
Specifying "ignore_invalid_headers" or "underscores_in_headers" on the
server level in a default server affects all virtual servers listening
on the same address:port.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Mon, 27 Feb 2012 10:36:08 +0000 |
parents | 8fa5f2273014 |
children | 2b9507b2cdf3 |
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 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-тип ответов по умолчанию. См. также директиву <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>on</literal> | <literal>off</literal> | <literal>if_not_owner</literal></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> </list> </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> требуют дополнительных затрат на обработку. Кроме того, использование этих параметров требует, чтобы рабочие процессы имели возможность читать все промежуточные каталоги. </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> <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"/>; </listitem> <listitem> подзапросы, формируемые командой “<command>include virtual</command>” модуля <link doc="ngx_http_ssi_module.xml">ngx_http_ssi_module</link>; </listitem> <listitem> запросы, изменённые директивой <link doc="ngx_http_rewrite_module.xml" id="rewrite"/>; </listitem> <listitem> запросы, перенаправленные с помощью поля <header>X-Accel-Redirect</header> заголовка ответа вышестоящего сервера. </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+ и FreeBSD 10.0-CURRENT) их можно сконфигурировать с помощью параметров <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 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"/>. </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> Эта директива была заменена параметром <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="../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\.)?(?<domain>.+)$; 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 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><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"/>. При передаче имени временного файла в проксированном запросе или в запросе к 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>