Mercurial > hg > nginx-site
changeset 253:ff1e139a8c98
Bring the ngx_http_core_module documentation up to date.
| author | Ruslan Ermilov <ru@nginx.com> |
|---|---|
| date | Mon, 19 Dec 2011 13:10:05 +0000 |
| parents | 6f710464be38 |
| children | 6080b2b90d15 |
| files | xml/ru/docs/http/ngx_http_core_module.xml |
| diffstat | 1 files changed, 1694 insertions(+), 836 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/ru/docs/http/ngx_http_core_module.xml Mon Dec 19 13:06:15 2011 +0000 +++ b/xml/ru/docs/http/ngx_http_core_module.xml Mon Dec 19 13:10:05 2011 +0000 @@ -2,138 +2,165 @@ <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> -<module name="Директивы модуля ngx_http_core_module" +<module name="Модуль ngx_http_core_module" link="/ru/docs/http/ngx_http_core_module.html" lang="ru"> -<section name="Директивы" id="directives"> +<section id="directives" name="Директивы"> <directive name="aio"> -<syntax><value>[on|off|sendfile]</value></syntax> +<syntax> + <value>on</value> | + <value>off</value> | + <value>sendfile</value> +</syntax> <default>off</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>0.8.11</appeared-in> <para> -Директива (0.8.11) разрешает или запрещает использовать файловый AIO +Разрешает или запрещает использование файлового асинхронного ввода-вывода (AIO) во FreeBSD и Linux. </para> <para> -Во FreeBSD AIO можно использовать, начиная с FreeBSD 4.3 версии. -AIO можно собрать в ядре статически +Во FreeBSD AIO можно использовать, начиная с FreeBSD 4.3. +AIO можно либо собрать в ядре статически: <example> options VFS_AIO </example> -или же подгрузить динамически +либо загрузить динамически через загружаемый модуль ядра: <example> kldload aio </example> </para> <para> -Во FreeBSD 5 и 6 при включении AIO статически или динамически на стадии -загрузки ядра вся сетевая подсистема будет использовать GiantLock, -что может негативно сказаться на производительности системы в целом. -Эта зависимость устранена во FreeBSD-6.4 STABLE от 2009 года и во FreeBSD 7. -Однако, начиная с FreeBSD 5.3, есть возможность включать AIO, -не связывая сетевую подсистему GiantLock'ом — для этого модуль AIO -нужно подгружать уже после загрузки ядра. -В этом случае в /var/log/messages появится сообщение +В версиях 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> -Требование использовать GiantLock в AIO связано с тем, что FreeBSD -поддерживает асинхронные вызовы aio_read()/aio_write() для работы с сокетами. -Но поскольку nginx использует AIO только для работы с диском, то проблем -не возникает. +Требование использовать блокировку Giant в AIO связано с тем, что +FreeBSD поддерживает асинхронные вызовы +<c-func>aio_read</c-func> +и +<c-func>aio_write</c-func> +для работы с сокетами. +Но поскольку nginx использует AIO только для работы с диском, +то проблем не возникает. </note> </para> <para> -Для работы AIO нужно выключить sendfile: +Для работы AIO нужно выключить +<link id="sendfile"/>: <example> -location /video/ { - sendfile off; - aio on; - output_buffers 1 64k; +location /video/ { + sendfile off; + aio on; + output_buffers 1 64k; } </example> </para> <para> -Кроме того, начиная с FreeBSD 5.2.1 и nginx-0.8.12, AIO также можно -использовать для подгрузки данных для sendfile(): +Кроме того, начиная с FreeBSD 5.2.1 и nginx 0.8.12, AIO также можно +использовать для подгрузки данных для <c-func>sendfile</c-func>: <example> -location /video/ { - sendfile on; - tcp_nopush on; - aio sendfile; +location /video/ { + sendfile on; + tcp_nopush on; + aio sendfile; } </example> -В такой конфигурации используется флаг SF_NODISKIO и sendfile() -не блокируется на диске, а сообщает об отсутствии данных в памяти, -после чего nginx инициирует асинхронную подгрузку данных, -читая только один байт. При этом ядро FreeBSD подгружает в память -первые 128K файла, однако при последующих чтениях файл подгружается -частями только по 16K. Изменить это можно с помощью директивы +В такой конфигурации функция <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"/>, иначе чтение будет блокирующимся: +В Linux AIO можно использовать только начиная с версии ядра 2.6.22, и, +кроме того, ещё необходимо дополнительно включать +<link id="directio"/>, +иначе чтение будет блокирующимся: <example> -location /video/ { - aio on; - directio 512; - output_buffers 1 128k; +location /video/ { + aio on; + directio 512; + output_buffers 1 128k; } </example> </para> <para> -Поскольку directio в Linux можно использовать только для чтения блоков, -выравненных по 512 байт (или 4К для XFS), то невыравненный конец файла -будет читаться блокировано. То же относится к запросам части ответа -byte-ranges и к запросам FLV не с начала файла: чтение невыровненных начала -и конца ответа будет блокирующимся. sendfile выключать не нужно, так -как при использовании directio он выключается сам. +Поскольку +<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> +<syntax><argument>путь</argument></syntax> <default/> <context>location</context> <para> -Директива задаёт замену для указанного location'а. +Задаёт замену для указанного location'а. Например, при такой конфигурации <example> -location /i/ { - alias /data/w3/images/; +location /i/ { + alias /data/w3/images/; } </example> -на запрос "/i/top.gif" будет отдан файл "/data/w3/images/top.gif". +на запрос +“<code>/i/top.gif</code>” будет отдан файл +<path>/data/w3/images/top.gif</path>. </para> <para> -В значении пути можно использовать переменные. +В значении аргумента <argument>путь</argument> можно использовать переменные, +кроме <var>$document_root</var> и <var>$realpath_root</var>. </para> <para> -Если директива alias используется внутри location'а, заданного -регулярным выражением, то регулярное выражение должно содержать выделения, -а директива alias — ссылки на эти выделения (0.7.40), например: +Если <code>alias</code> используется внутри location'а, заданного +регулярным выражением, то регулярное выражение должно содержать +выделения, а сам <code>alias</code> — ссылки на эти выделения +(0.7.40), например: <example> location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { - alias /data/w3/images/$1; + alias /data/w3/images/$1; } </example> </para> @@ -141,92 +168,132 @@ <para> Если location и последняя часть значения директивы совпадают: <example> -location /images/ { - alias /data/w3/images/; +location /images/ { + alias /data/w3/images/; +} +</example> +то лучше воспользоваться директивой +<link id="root"/>: +<example> +location /images/ { + root /data/w3; } </example> -то лучше воспользоваться директивой <link id="root"/>: -<example> -location /images/ { - root /data/w3; -} -</example> +</para> + +</directive> + + +<directive name="chunked_transfer_encoding"> +<syntax><value>on</value> | <value>off</value></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><argument>размер</argument></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><value>on|clean|off</value></syntax> +<syntax> + <value>on</value> | + <value>clean</value> | + <value>off</value> +</syntax> <default>off</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива определяет, сохранять ли всё тело запроса клиента в файл. -Директиву можно использовать для отладки и при использовании -переменной $request_body_file или метода -<link doc="ngx_http_perl_module.xml" id="methods">$r->request_body_file</link> -модуля ngx_http_perl_module. +Определяет, сохранять ли всё тело запроса клиента в файл. +Директиву можно использовать для отладки и при использовании переменной +<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> -При использовании параметра "on" временные файлы по окончании -обработки запроса не удаляется. +При установке значения <value>on</value> временные файлы +по окончании обработки запроса не удаляются. </para> <para> -Параметр "clean" разрешает удалять временные файлы, оставшиеся по окончании -обработки запроса. +Значение <value>clean</value> разрешает удалять временные файлы, +оставшиеся по окончании обработки запроса. </para> </directive> <directive name="client_body_in_single_buffer"> -<syntax><value>on|off</value></syntax> +<syntax><value>on</value> | <value>off</value> +</syntax> <default>off</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива определяет, хранить ли всё тело запроса клиента в одном буфере. -Директива рекомендуется при использовании переменной $request_body -для уменьшения операций копирования. -</para> - -</directive> - - -<directive name="client_body_buffer_size"> -<syntax><value>размер</value></syntax> -<default>8k/16k</default> -<context>http, server, location</context> - -<para> -Директива задаёт размер буфера для чтения тела запроса клиента. -Если тело запроса больше заданного буфера, то всё тело запроса или только -его часть записывается во временный файл. -По умолчанию размер одного буфера равен двум размерам страницы, в зависимости -от платформы это или 8K, или 16K. +Определяет, сохранять ли всё тело запроса клиента в одном буфере. +Директива рекомендуется при использовании переменной +<var>$request_body</var> +для уменьшения требуемого числа операций копирования. </para> </directive> <directive name="client_body_temp_path"> -<syntax><value>путь [ уровень1 [ уровень2 [ уровень3 ] ] ] -</value></syntax> +<syntax> + <argument>путь</argument> + [<argument>уровень1</argument> + [<argument>уровень2</argument> + [<argument>уровень3</argument>]]] +</syntax> <default>client_body_temp</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива задаёт имя каталога для хранения временных файлов с телом запроса -клиента. +Задаёт каталог для хранения временных файлов с телами запросов клиентов. В каталоге может использоваться иерархия подкаталогов до трёх уровней. Например, при такой конфигурации <example> -client_body_temp_path /spool/nginx/client_temp 1 2; +client_body_temp_path /spool/nginx/client_temp 1 2; </example> -имя временного будет такого вида: +временный файл будет следующего вида: <example> /spool/nginx/client_temp/7/45/00000123457 </example> @@ -236,33 +303,38 @@ <directive name="client_body_timeout"> -<syntax><value>время</value></syntax> -<default>60</default> -<context>http, server, location</context> +<syntax><argument>время</argument></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива задаёт таймаут при чтении тела запроса клиента. +Задаёт таймаут при чтении тела запроса клиента. Таймаут устанавливается не на всю передачу тела запроса, -а только между двумя операциями чтения. +а только между двумя последовательными операциями чтения. Если по истечении этого времени клиент ничего не передаст, -то ему возвращается ошибка "Request time out" (408). +то клиенту возвращается ошибка +<http-status code="408" text="Request Time-out"/>. </para> </directive> <directive name="client_header_buffer_size"> -<syntax><value>размер</value></syntax> +<syntax><argument>размер</argument></syntax> <default>1k</default> -<context>http, server</context> +<context>http</context> +<context>server</context> <para> -Директива задаёт размер буфера для чтения заголовка запроса клиента. -Для подавляющего большинства запросов вполне достаточно буфера размером в 1K. -Однако если в запросе есть большие cookies или же запрос пришёл -от wap-клиента, то он может не поместиться в 1K. -Поэтому, если строка запроса или строка заголовка запроса не помещается -полностью в этот буфер, то выделяются большие буферы, задаваемые директивой +Задаёт размер буфера для чтения заголовка запроса клиента. +Для большинства запросов достаточно буфера размером в 1K байт. +Однако если в запросе есть длинные cookies, или же запрос +пришёл от WAP-клиента, то он может не поместиться в 1K. +Поэтому, если строка запроса или поле заголовка запроса +не помещаются полностью в этот буфер, то выделяются буферы +большего размера, задаваемые директивой <link id="large_client_header_buffers"/>. </para> @@ -270,62 +342,96 @@ <directive name="client_header_timeout"> -<syntax><value>время</value></syntax> -<default>60</default> -<context>http, server</context> +<syntax><argument>время</argument></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> <para> -Директива задаёт таймаут при чтении заголовка запроса клиента. -Если по истечении этого времени клиент не передаст полностью заголовок -запроса, то ему возвращается ошибка "Request time out" (408). +Задаёт таймаут при чтении заголовка запроса клиента. +Если по истечении этого времени клиент не передаст полностью заголовок, +то клиенту возвращается ошибка +<http-status code="408" text="Request Time-out"/>. </para> </directive> <directive name="client_max_body_size"> -<syntax><value>размер</value></syntax> +<syntax><argument>размер</argument></syntax> <default>1m</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива задаёт максимально допустимый размер тела запроса клиента, -указываемый в строке "Content-Length" в заголовке запроса. +Задаёт максимально допустимый размер тела запроса клиента, +указываемый в поле +<header>Content-Length</header> +заголовка запроса. Если размер больше заданного, то клиенту возвращается ошибка -"Request Entity Too Large" (413). Следует иметь в виду, что -<link url="http://sysoev.ru/web/upload.html">браузеры не умеют -корректно показывать эту ошибку</link>. +<http-status code="413" text="Request Entity Too Large"/>. +Следует иметь в виду, что +<!--link doc="/web/upload.xml"-->браузеры не умеют корректно показывать +эту ошибку<!--/link-->. +Установка аргумента <argument>размер</argument> в 0 отключает +проверку размера тела запроса клиента. +</para> + +</directive> + + +<directive name="connection_pool_size"> +<syntax><argument>размер</argument></syntax> +<default>256</default> +<context>http</context> +<context>server</context> + +<para> +Позволяет производить точную настройку выделений памяти +под конкретные соединения. +Эта директива не оказывает существенного влияния на +производительность и её не следует использовать. </para> </directive> <directive name="default_type"> -<syntax><value>MIME-тип</value></syntax> +<syntax><argument>mime-тип</argument></syntax> <default>text/plain</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива задаёт MIME-тип ответов по умолчанию. +Задаёт MIME-тип ответов по умолчанию. +См. также директиву <link id="types"/>. </para> </directive> <directive name="directio"> -<syntax><value>[размер|off]</value></syntax> +<syntax><argument>размер</argument> | <value>off</value></syntax> <default>off</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>0.7.7</appeared-in> <para> -Директива (0.7.7) разрешает использовать флаги -O_DIRECT (FreeBSD, Linux), F_NOCACHE (Mac OS X) или функцию directio() (Solaris) +Разрешает использовать флаги +<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">sendfile'а</link> для данного запроса. +<link id="sendfile"/> +для данного запроса. Рекомендуется использовать для больших файлов: <example> -directio 4m; +directio 4m; </example> или при использовании <link id="aio"/> в Linux. </para> @@ -334,14 +440,17 @@ <directive name="directio_alignment"> -<syntax><value>размер</value></syntax> +<syntax><argument>размер</argument></syntax> <default>512</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>0.8.11</appeared-in> <para> -Директива (0.8.11) устанавливает выравнивание для +Устанавливает выравнивание для <link id="directio"/>. -В большинстве случае достаточно выравнивания 512 байт, однако +В большинстве случаев достаточно 512-байтового выравнивания, однако при использовании XFS под Linux его нужно увеличить до 4K. </para> @@ -349,40 +458,47 @@ <directive name="error_page"> -<syntax><value>код [код ...] [=|=ответ] uri</value> +<syntax> + <argument>код</argument> ... + [<value>=</value>[<argument>ответ</argument>]] + <argument>uri</argument> </syntax> <default/> -<context>http, server, location, if в location</context> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if в location</context> <para> -Директива задаёт URI, который будет показываться для указанных ошибок. -Директивы наследуются с предыдущего уровня при условии, что на данном -уровне не описаны свои директивы error_page. -В URI можно использовать переменные. +Задаёт URI, который будет показываться для указанных ошибок. +Директивы <code>error_page</code> наследуются с предыдущего уровня при условии, +что на данном уровне не описаны свои директивы +<code>error_page</code>. +В значении URI можно использовать переменные. </para> <para> -Пример использования: +Пример: <example> -error_page 404 /404.html; -error_page 502 503 504 /50x.html; -error_page 403 http://example.com/forbidden.html; +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; +error_page 404 =200 /empty.gif; </example> </para> <para> Если ошибочный ответ обрабатывается проксированным сервером или -FastCGI-сервером и этот сервер может вернуть разные коды ответов, -например, 200, 302, 401 или 404, то можно выдавать возвращаемый код: +FastCGI-сервером, и этот сервер может вернуть разные коды ответов, +например, 200, 302, 401 или 404, то можно выдавать возвращаемый им код: <example> -error_page 404 = /404.php; +error_page 404 = /404.php; </example> </para> @@ -391,11 +507,11 @@ обработку ошибки в именованный location: <example> location / { - error_page 404 = @fallback; + error_page 404 = @fallback; } location @fallback { - proxy_pass http://backend; + proxy_pass http://backend; } </example> </para> @@ -404,28 +520,41 @@ <directive name="if_modified_since"> -<syntax><value>[off|exact|before]</value></syntax> +<syntax> + <value>off</value> | + <value>exact</value> | + <value>before</value> +</syntax> <default>exact</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>0.7.24</appeared-in> <para> -Директива (0.7.24) определяет, как сравнивать время модификации ответа и -время в заголовке запроса "If-Modified-Since": -<list type="bullet"> - -<listitem> -off — не проверять заголовок запроса -"If-Modified-Since" (0.7.34); -</listitem> - -<listitem> -exact — точно совпадение; -</listitem> - -<listitem> -before — время модификации ответа меньше или равно времени, заданному -в заголовке запроса "If-Modified-Since". -</listitem> +Определяет, как сравнивать время модификации ответа с +временем в поле +<header>If-Modified-Since</header> +заголовка запроса: + +<list type="tag"> + +<tag-name><value>off</value></tag-name> +<tag-desc> +не проверять поле +<header>If-Modified-Since</header> заголовка запроса (0.7.34); +</tag-desc> + +<tag-name><value>exact</value></tag-name> +<tag-desc> +точное совпадение; +</tag-desc> + +<tag-name><value>before</value></tag-name> +<tag-desc> +время модификации ответа меньше или равно времени, заданному в поле +<header>If-Modified-Since</header> заголовка запроса. +</tag-desc> </list> </para> @@ -433,39 +562,61 @@ </directive> +<directive name="ignore_invalid_headers"> +<syntax><value>on</value> | <value>off</value></syntax> +<default>on</default> +<context>http</context> +<context>server</context> + +<para> +Если включено, nginx игнорирует поля заголовка с недопустимыми именами. +Допустимыми считаются имена, состоящие из английских букв, цифр, дефисов +и возможно знаков подчёркивания (последнее контролируется директивой +<link id="underscores_in_headers"/>). +</para> + +</directive> + + <directive name="internal"> <syntax/> <default/> <context>location</context> <para> -Директива указывает, что данный location может использоваться только -для внутренних запросов. -Для внешних запросов будет возвращаться ошибка "Not found" (404). -Внутренними запросами являются +Указывает, что location может использоваться только для внутренних запросов. +Для внешних запросов клиенту будет возвращаться ошибка +<http-status code="404" text="Not Found"/>. +Внутренними запросами являются: + <list type="bullet"> <listitem> -запросы, перенаправленные директивой error_page; +запросы, перенаправленные директивой <link id="error_page"/>; </listitem> <listitem> -подзапросы, формируемые командой include virtual модуля ngx_http_ssi_module; +подзапросы, формируемые командой +<command>include virtual</command> +модуля +<link doc="ngx_http_ssi_module.xml">ngx_http_ssi_module</link>; +ngx_http_ssi_module; </listitem> <listitem> -запросы, изменённые директивой rewrite модуля ngx_http_rewrite_module. +запросы, изменённые директивой +<link doc="ngx_http_rewrite_module.xml" id="rewrite"/>. </listitem> </list> </para> <para> -Пример использования: +Пример: <example> -error_page 404 /404.html; - -location /404.html { +error_page 404 /404.html; + +location /404.html { internal; } </example> @@ -474,30 +625,69 @@ </directive> +<directive name="keepalive_disable"> +<syntax><value>none</value> | <argument>браузер</argument> ...</syntax> +<default>msie6 safari</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Запрещает keep-alive соединения с некорректно ведущими себя браузерами. +Аргументы <argument>браузер</argument> указывают, на какие браузеры это +распространяется. +Значение <value>msie6</value> запрещает keep-alive соединения +со старыми версиями MSIE после получения запроса POST. +Значение <value>safari</value> запрещает keep-alive соединения +с браузерами Safari. +Значение <value>none</value> разрешает keep-alive соединения +со всеми браузерами. +</para> + +</directive> + + <directive name="keepalive_requests"> -<syntax><value>число</value></syntax> +<syntax><argument>число</argument></syntax> <default>100</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>0.8.0</appeared-in> <para> -Директива (0.8.0) задаёт максимальное число запросов, которые можно +Задаёт максимальное число запросов, которые можно сделать по одному keep-alive соединению. +После того, как будет сделано максимальное число запросов, +соединение закрывается. </para> </directive> <directive name="keepalive_timeout"> -<syntax><value>время [время]</value></syntax> -<default>75</default> -<context>http, server, location</context> +<syntax> + <argument>таймаут</argument> + [<argument>заголовок_таймаута</argument>] +</syntax> +<default>75s</default> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива задаёт таймаут, в течение которого keep-alive соединение -с клиентом не будет закрыто со стороны сервера. -Второй параметр задаёт значение в строке "Keep-Alive: timeout=время" -в заголовке ответа. Параметры могут отличаться друг от друга. -Строку "Keep-Alive: timeout=время" понимают Mozilla и Konqueror. +Первый аргумент задаёт таймаут, в течение которого keep-alive +соединение с клиентом не будет закрыто со стороны сервера. +Второй необязательный параметр задаёт значение в поле +<header>Keep-Alive: timeout=<argument>время</argument></header> +заголовка ответа. +Два аргумента могут отличаться друг от друга. +</para> + +<para> +Поле +<header>Keep-Alive: timeout=<argument>время</argument></header> +заголовка понимают Mozilla и Konqueror. MSIE сам закрывает keep-alive соединение примерно через 60 секунд. </para> @@ -505,76 +695,102 @@ <directive name="large_client_header_buffers"> -<syntax><value>число размер</value> -</syntax> -<default>4 4k/8k</default> -<context>http, server</context> +<syntax><argument>число размер</argument></syntax> +<default>4 8k</default> +<context>http</context> +<context>server</context> <para> -Директива задаёт максимальное число и размер буферов для чтения -большого заголовка запроса клиента. -Строка запроса должна быть не больше размера одного буфера, иначе клиенту -возвращается ошибка "Request URI too large" (414). -Длинная строка заголовка запроса также должна быть не больше размера одного -буфера, иначе клиенту возвращается ошибка "Bad request" (400). +Задаёт максимальное <argument>число</argument> и <argument>размер</argument> +буферов для чтения большого заголовка запроса клиента. +Строка запроса не должна превышать размера одного буфера, иначе клиенту +возвращается ошибка +<http-status code="414" text="Request-URI Too Large"/>. +Поле заголовка запроса также не должно превышать размера одного буфера, +иначе клиенту возвращается ошибка +<http-status code="400" text="Bad Request"/>. Буферы выделяются только по мере необходимости. -По умолчанию размер одного буфера равен размеру страницы, в зависимости -от платформы это или 4K, или 8K. +По умолчанию размер одного буфера равен 8K байт. Если по окончании обработки запроса соединение переходит в состояние -keep-alive, то эти буферы освобождаются. +keep-alive, эти буферы освобождаются. </para> </directive> <directive name="limit_except"> -<syntax block="yes"><value>методы</value></syntax> +<syntax block="yes"><argument>метод</argument> ...</syntax> <default/> <context>location</context> <para> -Директива ограничивает HTTP-методы, доступные внутри location. -Метод GET также включает в себя метод HEAD. -Для ограничения могут использоваться директивы модулей +Ограничивает HTTP-методы, доступные внутри location. +Аргумент <argument>метод</argument> может быть одним из +<value>GET</value>, +<value>HEAD</value>, +<value>POST</value>, +<value>PUT</value>, +<value>DELETE</value>, +<value>MKCOL</value>, +<value>COPY</value>, +<value>MOVE</value>, +<value>OPTIONS</value>, +<value>PROPFIND</value>, +<value>PROPPATCH</value>, +<value>LOCK</value>, +<value>UNLOCK</value> +или +<value>PATCH</value>. +Если разрешён метод <value>GET</value>, то метод +<value>HEAD</value> также будет разрешён. +Доступ к остальным методам может быть ограничен при помощи директив модулей <link doc="ngx_http_access_module.xml">ngx_http_access_module</link> -и <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>: +и +<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>: <example> -limit_except GET { - allow 192.168.1.0/32; - deny all; +limit_except GET { + allow 192.168.1.0/32; + deny all; } </example> -Обратите внимание, что данное ограничение будет выполняться для всех методов, -<value>кроме</value> методов GET и HEAD. +Обратите внимание, что данное ограничение действует для всех методов, +<emphasis>кроме</emphasis> GET и HEAD. </para> </directive> <directive name="limit_rate"> - -<syntax><value>скорость</value></syntax> -<default/> -<context>http, server, location, if в location</context> +<syntax><argument>скорость</argument></syntax> +<default>0</default> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if в location</context> <para> -Директива задаёт скорость передачи ответа клиенту. +Ограничивает скорость передачи ответа клиенту. Скорость задаётся в байтах в секунду. - -Ограничение работает только для одного соединения, то есть, -если клиент откроет 2 соединения, то суммарная скорость будет в 2 раза -выше ограниченной. +Значение 0 (установка по умолчанию) отключает ограничение скорости. +<!-- +Чем меньше скорость, тем более аккуратным будет ограничение. +--> +Ограничение срабатывает только для одного соединения, то есть если +клиент откроет 2 соединения, то суммарная скорость будет в 2 раза +выше заданного ограничения. </para> <para> -Если необходимо ограничить скорость для части клиентов на уровне сервера, -то директива limit_rate для этого не подходит. Вместо этого следует -задать нужную скорость переменной $limit_rate: +Если необходимо ограничить скорость для части клиентов на уровне +<link id="server">сервера</link>, то директива <code>limit_rate</code> +для этого не подходит. +Вместо этого следует задать желаемое ограничение скорости в переменной +<var>$limit_rate</var>: <example> server { if ($slow) { - set $limit_rate 4k; + set $limit_rate 4k; } ... @@ -586,18 +802,26 @@ <directive name="limit_rate_after"> -<syntax><value>размер</value></syntax> -<default/> -<context>http, server, location, if в location</context> +<syntax><argument>размер</argument></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> -Директива (0.8.0) задаёт объём данных, после передачи которого -начинает ограничиваться скорость передачи ответа клиенту, например: +Задаёт начальный объём данных, после передачи которого начинает +ограничиваться скорость передачи ответа клиенту. +</para> + +<para> +Пример: <example> location /flv/ { flv; - limit_rate_after 500k; - limit_rate 50k; + limit_rate_after 500k; + limit_rate 50k; } </example> </para> @@ -605,127 +829,318 @@ </directive> +<directive name="lingering_close"> +<syntax><value>off</value> | <value>on</value> | <value>always</value></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> +Со значение по умолчанию “<value>on</value>” nginx будет +<link id="lingering_timeout">ждать</link> и +<link id="lingering_time">обрабатывать</link> дополнительные данные, +поступающие от клиента, перед полным закрытием соединения, но только +если эвристика указывает на то, что клиент может ещё послать данные. +</para> + +<para> +Со значением “<value>always</value>” nginx всегда будет +ждать и обрабатывать дополнительные данные, поступающие от клиента. +</para> + +<para> +Со значением “<value>off</value>” nginx не будет ждать поступления +дополнительных данных и сразу же закроет соединение. +Это нарушает протокол, поэтому не следует это использовать без нужды. +</para> + +</directive> + + +<directive name="lingering_time"> +<syntax><argument>время</argument></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><argument>время</argument></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>адрес:порт - [default|default_server| - [backlog=число | - rcvbuf=размер | - sndbuf=размер | - accept_filter=фильтр | - deferred | - bind | - ipv6only=[on|off] | - ssl]] -</value></syntax> +<syntax> + <argument>адрес</argument>[:<argument>порт</argument>] + [<parameter>default_server</parameter>] + [<parameter>setfib</parameter>=<argument>число</argument>] + [<parameter>backlog</parameter>=<argument>число</argument>] + [<parameter>rcvbuf</parameter>=<argument>размер</argument>] + [<parameter>sndbuf</parameter>=<argument>размер</argument>] + [<parameter>accept_filter</parameter>=<argument>фильтр</argument>] + [<parameter>deferred</parameter>] + [<parameter>bind</parameter>] + [<parameter>ipv6only</parameter>=<value>on</value>|<value>off</value>] + [<parameter>ssl</parameter>] + [<parameter>so_keepalive</parameter>=<value>on</value>|<value>off</value>|[<argument>keepidle</argument>]:[<argument>keepintvl</argument>]:[<argument>keepcnt</argument>]]</syntax> +<syntax> + <argument>порт</argument> + [<parameter>default_server</parameter>] + [<parameter>setfib</parameter>=<argument>число</argument>] + [<parameter>backlog</parameter>=<argument>число</argument>] + [<parameter>rcvbuf</parameter>=<argument>размер</argument>] + [<parameter>sndbuf</parameter>=<argument>размер</argument>] + [<parameter>accept_filter</parameter>=<argument>фильтр</argument>] + [<parameter>deferred</parameter>] + [<parameter>bind</parameter>] + [<parameter>ipv6only</parameter>=<value>on</value>|<value>off</value>] + [<parameter>ssl</parameter>] + [<parameter>so_keepalive</parameter>=<value>on</value>|<value>off</value>|[<argument>keepidle</argument>]:[<argument>keepintvl</argument>]:[<argument>keepcnt</argument>]]</syntax> +<syntax> + <value>unix:</value><argument>путь</argument> + [<parameter>default_server</parameter>] + [<parameter>backlog</parameter>=<argument>число</argument>] + [<parameter>rcvbuf</parameter>=<argument>размер</argument>] + [<parameter>sndbuf</parameter>=<argument>размер</argument>] + [<parameter>accept_filter</parameter>=<argument>фильтр</argument>] + [<parameter>deferred</parameter>] + [<parameter>bind</parameter>] + [<parameter>ssl</parameter>] + [<parameter>so_keepalive</parameter>=<value>on</value>|<value>off</value>|[<argument>keepidle</argument>]:[<argument>keepintvl</argument>]:[<argument>keepcnt</argument>]]</syntax> <default>*:80 | *:8000</default> <context>server</context> <para> -Директива задаёт адрес и порт, на которых сервер принимает запросы. -Можно указать только адрес или только порт, кроме того, адрес может -быть именем сервера, например: +Задаёт <argument>адрес</argument> и <argument>порт</argument> для IP +или <argument>путь</argument> для UNIX-сокета, +на которых сервер будет принимать запросы. +Можно указать только <argument>адрес</argument> +или только <argument>порт</argument>. +Кроме того, <argument>адрес</argument> может быть именем хоста, например: <example> -listen 127.0.0.1:8000; -listen 127.0.0.1; -listen 8000; -listen *:8000; -listen localhost:8000; +listen 127.0.0.1:8000; +listen 127.0.0.1; +listen 8000; +listen *:8000; +listen localhost:8000; </example> -адреса IPv6 (0.7.36) задаются в квадратных скобках: +IPv6-адреса (0.7.36) задаются в квадратных скобках: <example> -listen [::]:8000; -listen [fe80::1]; +listen [::]:8000; +listen [fe80::1]; +</example> +UNIX-сокеты (0.8.21) задаются при помощи префикса “<code>unix:</code>”: +<example> +listen unix:/var/run/nginx.sock; </example> </para> <para> -Если указан только адрес, то используется порт 80. +Если указан только <argument>адрес</argument>, то используется порт 80. +</para> + +<para> +Если директива не указана, то используется либо <code>*:80</code> +(если nginx работает с привилегиями суперпользователя), +либо <code>*:8000</code>. </para> <para> -Если директива не указана, то используется порт *:80, если nginx работает -с правами пользователя root, или порт *:8000. -</para> - -<para> -Если у директивы есть параметр default, то сервер, в котором описана -эта директива, будет сервером по умолчанию для указанной пары адрес:порт. -Если же директив с параметром default нет, то сервером по умолчанию -будет первый сервер, в котором описана пара адрес:порт. -Начиная с версии 0.8.21, можно использовать параметр default_server. +Если у директивы есть параметр <parameter>default_server</parameter>, то сервер, +в котором описана эта директива, будет сервером по умолчанию для указанной пары +<argument>адрес</argument>:<argument>порт</argument>. +Если же директив с параметром <parameter>default_server</parameter> нет, то +сервером по умолчанию будет первый сервер, в котором описана пара +<argument>адрес</argument>:<argument>порт</argument>. +адрес:порт. +<note> +До версии 0.8.21 этот параметр назывался просто +<parameter>default</parameter>. +</note> </para> <para> -В директиве listen с параметром default можно также указать несколько -параметров, специфичных для системных вызовов listen(2) и bind(2). -Начиная с версии 0.8.21, эти параметры можно задать в любой директиве -listen, но только один раз для указанной пары адрес:порт. -<list type="bullet"> - -<listitem> -backlog=число — задаёт параметр backlog в вызове listen(2). -По умолчанию backlog равен -1 для FreeBSD и 511 для всех остальных -платформ. -</listitem> - -<listitem> -rcvbuf=размер — задаёт параметр SO_RCVBUF для слушающего сокета. -</listitem> - -<listitem> -sndbuf=размер — задаёт параметр SO_SNDBUF для слушающего сокета. -</listitem> - -<listitem> -accept_filter=фильтр — задаёт название accept-фильтра. -Работает только на FreeBSD, можно использовать два фильтра — dataready -и httpready. -По сигналу -HUP accept-фильтр можно менять только в последних -версиях FreeBSD, начиная с 6.0, 5.4-STABLE и 4.11-STABLE. -</listitem> - -<listitem> -deferred — указывает использовать отложенный accept(2) на Linux -с помощью опции TCP_DEFER_ACCEPT. -</listitem> - -<listitem> -bind — указывает, что для данной пары адрес:порт нужно делать bind(2) -отдельно. -Дело в том, что если описаны несколько директив listen с одинаковым портом, -но разными адресами и одна из директив listen слушает на всех адресах -для данного порта (*:порт), то nginx сделает bind(2) только на *:порт. -Необходимо учитывать, что в этом случае для определения адреса, на которой -пришло соединение, делается системный вызов getsockname(). -Если же используются параметры backlog, rcvbuf, sndbuf, accept_filter -или deferred, то для данной пары адрес:порт bind(2) всегда делается отдельно. -</listitem> - -<listitem> -ipv6only — параметр (0.7.42) задаёт значение параметра IPV6_V6ONLY +В директиве <code>listen</code> можно также указать несколько +дополнительных параметров, специфичных для системных вызовов +<c-func>listen</c-func> и <c-func>bind</c-func>. +Эти параметры можно задать в любой директиве <code>listen</code>, +но только один раз для указанной пары +<argument>адрес</argument>:<argument>порт</argument>. +<note> +До версии 0.8.21 их можно было указывать лишь в директиве +<code>listen</code> с параметром <parameter>default</parameter>. +</note> +<list type="tag"> + +<tag-name> +<parameter>setfib</parameter>=<argument>число</argument> +</tag-name> +<tag-desc> +этот параметр (0.8.44) задаёт для слушающего сокета соответствующую +таблицу маршрутизации (FIB). +В настоящий момент это работает только на FreeBSD. +</tag-desc> + +<tag-name> +<parameter>backlog</parameter>=<argument>число</argument> +</tag-name> +<tag-desc> +задаёт параметр <parameter>backlog</parameter> в вызове +<c-func>listen</c-func>. +По умолчанию <parameter>backlog</parameter> равен -1 для FreeBSD +и 511 для других платформ. +</tag-desc> + +<tag-name> +<parameter>rcvbuf</parameter>=<argument>размер</argument> +</tag-name> +<tag-desc> +задаёт параметр <c-def>SO_RCVBUF</c-def> для слушающего сокета +</tag-desc> + +<tag-name> +<parameter>sndbuf</parameter>=<argument>размер</argument> +</tag-name> +<tag-desc> +задаёт параметр <c-def>SO_SNDBUF</c-def> для слушающего сокета +</tag-desc> + +<tag-name> +<parameter>accept_filter</parameter>=<argument>фильтр</argument> +</tag-name> +<tag-desc> +задаёт название accept-фильтра. +Работает только на FreeBSD, можно использовать два фильтра — +<value>dataready</value> и <value>httpready</value>. +По сигналу <c-def>SIGHUP</c-def> accept-фильтр можно менять только в +последних версиях FreeBSD, начиная с 6.0, 5.4-STABLE и 4.11-STABLE. +</tag-desc> + +<tag-name> +<parameter>deferred</parameter> +</tag-name> +<tag-desc> +указывает использовать отложенный <c-func>accept</c-func> на Linux +с помощью опции <c-def>TCP_DEFER_ACCEPT</c-def>. +</tag-desc> + +<tag-name> +<parameter>bind</parameter> +</tag-name> +<tag-desc> +указывает, что для данной пары +<argument>адрес</argument>:<argument>порт</argument> нужно делать +<c-func>bind</c-func> отдельно. +Дело в том, что если описаны несколько директив <code>listen</code> +с одинаковым портом, но разными адресами и одна из директив +<code>listen</code> слушает на всех адресах для данного порта +(<code>*</code>:<argument>порт</argument>, то nginx сделает +<c-func>bind</c-func> только на <code>*</code>:<argument>порт</argument>. +Необходимо заметить, что в этом случае для определения адреса, на которой +пришло соединение, делается системный вызов <c-func>getsockname</c-func>. +Если же используются параметры <parameter>backlog</parameter>, +<parameter>rcvbuf</parameter>, <parameter>sndbuf</parameter>, +<parameter>accept_filter</parameter>, <parameter>deferred</parameter> +или <parameter>so_keepalive</parameter>, то для данной пары +<argument>адрес</argument>:<argument>порт</argument> всегда делается +отдельный вызов <c-func>bind</c-func>. +</tag-desc> + +<tag-name> +<parameter>ipv6only</parameter>=<value>on</value>|<value>off</value> +</tag-name> +<tag-desc> +параметр (0.7.42) задаёт значение параметра <c-def>IPV6_V6ONLY</c-def> для слушающего сокета. Установить этот параметр можно только один раз на старте. -</listitem> - -<listitem> -ssl — параметр (0.7.14) не имеет отношения к системным вызовам -listen(2) и bind(2), а позволяет указать, что все соединения, -принимаемые на этом порту, должны работать в режиме SSL. +</tag-desc> + +<tag-name> +<parameter>ssl</parameter> +</tag-name> +<tag-desc> +этот параметр (0.7.14) не имеет отношения к системным вызовам +<c-func>listen</c-func> и <c-func>bind</c-func>, а позволяет указать, +что все соединения, принимаемые на этом порту, должны работать +в режиме SSL. Это позволяет задать компактную конфигурацию для сервера, -работающего сразу в двух режимах — HTTP и HTTPS. +работающего сразу в двух режимах — HTTP и HTTPS. <example> -listen 80; -listen 443 default ssl; +listen 80; +listen 443 default ssl; </example> -</listitem> +</tag-desc> + +<tag-name> +<parameter>so_keepalive</parameter>=<value>on</value>|<value>off</value>|[<argument>keepidle</argument>]:[<argument>keepintvl</argument>]:[<argument>keepcnt</argument>] +</tag-name> +<tag-desc> +этот параметр (1.1.11) конфигурирует для слушающего сокета +поведение “TCP keepalive”. +Если этот параметр опущен, то для сокета будут действовать +стандартные системные настройки. +Если он установлен в значение “<value>on</value>”, то для сокета +включается опция <c-def>SO_KEEPALIVE</c-def>. +Если он установлен в значение “<value>off</value>”, то для сокета +опция <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+) +их можно сконфигурировать с помощью аргументов <argument>keepidle</argument>, +<argument>keepintvl</argument> и <argument>keepcnt</argument>. +Один или два аргумента могут быть опущены, в таком случае для +соответствующей опции сокета будут действовать стандартные +системные настройки. +Например, +<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; +listen 127.0.0.1 default accept_filter=dataready backlog=1024; </example> </para> @@ -733,101 +1148,126 @@ <directive name="location"> -<syntax block="yes">[<value>=|~|~*|^~|@</value>] <value>/uri/</value> +<syntax block="yes">[ + <value>=</value> | + <value>~</value> | + <value>~*</value> | + <value>^~</value> + ] <argument>uri</argument> </syntax> +<syntax block="yes"><value>@</value><argument>имя</argument></syntax> <default/> <context>server</context> +<context>location</context> <para> -Директива устанавливает конфигурацию в зависимости от URI запроса. -location можно задать обычной строкой или регулярным выражением. -Регулярные выражения задаются префиксом "~*" — без учёта регистра -символов, и "~" — с учётом. -Для определения соответствия location'а и запроса -сначала проверяются location'ы, заданные обычными строками. +Устанавливает конфигурацию в зависимости от URI запроса. +location можно задать префиксной строкой или регулярным выражением. +Регулярные выражения задаются либо с префиксом “<value>~*</value>” +(для поиска совпадения без учёта регистра символов), +либо с префиксом “<value>~</value>” (с учётом регистра). +Чтобы найти location, соответствующий запросу, вначале проверяются +location'ы, заданные префиксными строками (префиксные location'ы). Среди них ищется максимальное совпадение. -Затем проверяются регулярные выражения. -В отличие от обычных строк, они не сортируются, а проверяются в порядке -их следования в конфигурационном файле. -Проверка регулярных выражений прекращается после первого же совпадения. +Затем проверяются регулярные выражения, в порядке их следования +в конфигурационном файле. +Проверка регулярных выражений прекращается после первого же совпадения, +и используется соответствующая конфигурация. Если совпадение с регулярным выражением не найдено, то используется -конфигурация максимально совпавшего location'а. +конфигурация максимально совпавшего префиксного location'а. </para> <para> -Для операционных систем, не чувствительных к регистру символов, таких -как Mac OS X и Cygwin, проверка обычных строк делается без учёта -регистра (0.7.7). +location'ы могут быть вложенными, с некоторыми исключениями, +о которых говорится ниже. +</para> + +<para> +Для операционных систем, нечувствительных к регистру символов, таких +как Mac OS X и Cygwin, сравнение с префиксными строками производится +без учёта регистра (0.7.7). Однако, сравнение ограничено только однобайтными locale'ями. </para> <para> -Регулярное выражение может содержать выделения (0.7.40), которые -могут затем использоваться в других директивах. +Регулярные выражения могут содержать выделения (0.7.40), которые могут +затем использоваться в других директивах. </para> <para> -Если нужно запретить проверку регулярных выражений после проверки -обычных строк, то это можно сделать с помощью префикса "^~". -Если у максимально совпавшего location'а есть этот префикс, то -регулярные выражения не проверяются. +Если у максимального совпавшего префиксного location'а указан префикс +“<value>^~</value>”, то регулярные выражения не проверяются. </para> <para> -Кроме того, с помощью префикса "=" можно задать точное совпадение -URI и location. При совпадении поиск сразу же прекращается, так как -дальше искать не имеет смысла. Например, если запрос "/" очень частый, -то указав "location = /", можно ускорить обработку этого запроса, -так как поиск location прекратится после первого же сравнения. +Кроме того, с помощью префикса “<value>=</value>” можно задать точное +совпадение URI и location. +При точном совпадении поиск сразу же прекращается. +Например, если запрос “<code>/</code>” случается часто, то +указав “<code>location = /</code>”, можно ускорить обработку +этих запросов, так как поиск прекратится после первого же сравнения. +Очевидно, что такой location не может иметь вложенные location'ы. </para> <para> -В версиях с 0.7.1 по 0.8.41, если запрос точно совпал с обычным location'ом -без префиксов "=" и "^~", то поиск тоже сразу же прекращается и -регулярные выражения также не проверяются. +<note> +В версиях с 0.7.1 по 0.8.41, если запрос точно совпал с префиксным +location'ом без префиксов “<value>=</value>” и “<value>^~</value>”, +то поиск тоже сразу же прекращается и регулярные выражения также +не проверяются. +</note> </para> <para> Проиллюстрируем вышесказанное примером: <example> -location = / { - [ конфигурация A ] +location = / { + [ конфигурация А ] } -location / { - [ конфигурация B ] +location / { + [ конфигурация Б ] } location ^~ /images/ { - [ конфигурация C ] + [ конфигурация В ] } location ~* \.(gif|jpg|jpeg)$ { - [ конфигурация D ] + [ конфигурация Г ] } </example> -Для запроса "/" будет выбрана конфигурация A, -для запроса "/documents/document.html" — конфигурация B, -для запроса "/images/1.gif" — конфигурация C, -для запроса "/documents/1.jpg" — конфигурация D. +Для запроса “<code>/</code>” будет выбрана конфигурация А, +для запроса “<code>/documents/document.html</code>” — конфигурация Б, +для запроса “<code>/images/1.gif</code>” — конфигурация В, +а для запроса “<code>/documents/1.jpg</code>” — конфигурация Г. </para> <para> -Префикс "@" задаёт именованный location. Такой location не используется -при обычной обработке запросов, а предназначен только для перенаправления -в него запросов. +Префикс “<value>@</value>” задаёт именованный location. +Такой location не используется при обычной обработке запросов, а +предназначен только для перенаправления в него запросов. +Такие location'ы не могут быть вложенными и не могут содержать +вложенные location'ы. </para> +<!-- +<migration from="Apache" directive="Location" /> +--> + </directive> <directive name="log_not_found"> -<syntax><value>[on|off]</value></syntax> +<syntax><value>on</value> | <value>off</value></syntax> <default>on</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива разрешает или запрещает записывать в error_log +Разрешает или запрещает записывать в +<link doc="../ngx_core_module.xml" id="error_log"/> ошибки о том, что файл не найден. </para> @@ -835,12 +1275,14 @@ <directive name="log_subrequest"> -<syntax><value>[on|off]</value></syntax> +<syntax><value>on</value> | <value>off</value></syntax> <default>off</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива разрешает или запрещает записывать в +Разрешает или запрещает записывать в <link doc="ngx_http_log_module.xml" id="access_log"/> подзапросы. </para> @@ -848,51 +1290,74 @@ </directive> +<directive name="max_ranges"> +<syntax><argument>число</argument></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Ограничивает максимальное допустимое число диапазонов в запросах с +указанием диапазона запрашиваемых байт (byte-range requests). +Запросы, превышающие указанное ограничение, обрабатываются как +если бы они не содержали указания диапазонов. +По умолчанию ограничения нет. +Значение 0 полностью запрещает поддержку диапазонов. +</para> + +</directive> + + <directive name="merge_slashes"> -<syntax><value>[on|off]</value></syntax> +<syntax><value>on</value> | <value>off</value></syntax> <default>on</default> -<context>http, server</context> +<context>http</context> +<context>server</context> <para> -Директива разрешает или запрещает объединять в URI два и более слэшей в один. +Разрешает или запрещает преобразование URI путём замены двух и более подряд +идущих слэшей (“<code>/</code>”) в один. </para> <para> -Необходимо иметь ввиду, что это объединение необходимо для корректной -проверки location'ов и регулярных выражений. -Например, запрос "//scripts/one.php" не попадает в +Необходимо иметь ввиду, что это преобразование необходимо для корректной +проверки префиксных строк и регулярных выражений. +Если его не делать, то запрос “<code>//scripts/one.php</code>” не попадёт в <example> location /scripts/ { ... } </example> -и может быть обслужен как статический файл, -поэтому он приводится в "/scripts/one.php". +и может быть обслужен как статический файл. +Поэтому он преобразуется к виду “<code>/scripts/one.php</code>”. </para> <para> -Выключение объединения может понадобиться, если в URI используются имена, -закодированные методом base64, который использует символ "/". -Но по соображениям безопасности лучше избегать выключения объединения. +Запрет преобразования может понадобиться, если в URI используются имена, +закодированные методом base64, в котором задействован символ “<code>/</code>”. +Однако по соображениям безопасности лучше избегать отключения преобразования. </para> <para> -Если директива указана на уровне server в сервере по умолчанию, -то её значение распространяется на все виртуальные сервера, слушающие -на том же адресе и порту. +Если директива указана на уровне +<link id="server"/> +в сервере по умолчанию, то её значение распространяется на +все виртуальные сервера, слушающие на том же адресе и порту. </para> </directive> <directive name="msie_padding"> -<syntax><value>[on|off]</value></syntax> +<syntax><value>on</value> | <value>off</value></syntax> <default>on</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива разрешает или запрещает добавлять в ответы для MSIE -со статусом больше 400 +Разрешает или запрещает добавлять в ответы для MSIE со статусом больше 400 комментарий для увеличения размера ответа до 512 байт. </para> @@ -900,26 +1365,33 @@ <directive name="msie_refresh"> -<syntax><value>[on|off]</value></syntax> +<syntax><value>on</value> | <value>off</value></syntax> <default>off</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива разрешает или запрещает выдавать для MSIE refresh'ы вместо -редиректов. +Разрешает или запрещает выдавать для MSIE клиентов refresh'ы вместо +перенаправлений. </para> </directive> <directive name="open_file_cache"> -<syntax><value>max=N [inactive=время]|off</value> +<syntax><value>off</value></syntax> +<syntax> +<parameter>max</parameter>=<argument>N</argument> +[<parameter>inactive</parameter>=<argument>время</argument>] </syntax> <default>off</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива задаёт кэш, в котором могут хранится +Задаёт кэш, в котором могут храниться: <list type="bullet"> <listitem> @@ -931,43 +1403,57 @@ </listitem> <listitem> -информация об ошибках поиска файла — нет файла, нет прав на чтение -и тому подобное. Кэширование ошибок нужно разрешить директивой +информация об ошибках поиска файла — “нет файла”, “нет прав на чтение” +и тому подобное. +<note> +Кэширование ошибок нужно разрешить отдельно директивой <link id="open_file_cache_errors"/>. +</note> </listitem> </list> </para> <para> -Параметры директивы: -<list type="bullet"> - -<listitem> -max — задаёт максимальное число элементов в кэше; +У директивы есть следующие параметры: +<list type="tag"> + +<tag-name> +<parameter>max</parameter> +</tag-name> +<tag-desc> +задаёт максимальное число элементов в кэше; при переполнении кэша удаляются наиболее давно не используемые элементы (LRU); -</listitem> - -<listitem> -inactive — задаёт время, после которого элемент кэша удаляется, -если к нему не было обращений в течение этого времени; -по умолчанию 60 секунд; -</listitem> - -<listitem> -off — запрещает кэш. -</listitem> +</tag-desc> + +<tag-name> +<parameter>inactive</parameter> +</tag-name> +<tag-desc> +задаёт время, после которого элемент кэша удаляется, если к нему +не было обращений в течение этого времени; по умолчанию 60 секунд; +</tag-desc> + +<tag-name> +<value>off</value> +</tag-name> +<tag-desc> +запрещает кэш. +</tag-desc> </list> </para> <para> -Пример использования: +Пример: <example> -open_file_cache max=1000 inactive=20s; +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> @@ -975,100 +1461,167 @@ <directive name="open_file_cache_errors"> -<syntax><value>on|off</value></syntax> +<syntax><value>on</value> | <value>off</value></syntax> <default>off</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива определяет, кэшировать или нет ошибки поиска файлов в +Разрешает или запрещает кэширование ошибок поиска файлов в <link id="open_file_cache"/>. </para> </directive> -<directive name="open_file_cache_min_uses"> -<syntax><value>число</value></syntax> -<default>1</default> -<context>http, server, location</context> +<!-- + +<directive name="open_file_cache_events"> +<syntax><value>on</value> | <value>off</value></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива определяет минимальное число использований файла в течение -времени, заданного параметром inactive в директиве -<link id="open_file_cache"/>, после которого дескриптор файла -будет оставаться открытым в кэше. +Разрешает использование событий ядра для проверки актуальности элементов +<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><argument>число</argument></syntax> +<default>1</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт минимальное <argument>число</argument> обращений к файлу +в течение времени, заданного параметром <parameter>inactive</parameter> +директивы <link id="open_file_cache"/>, после которого дескриптор +файла будет оставаться открытым в кэше. </para> </directive> <directive name="open_file_cache_valid"> -<syntax><value>время</value></syntax> -<default>60</default> -<context>http, server, location</context> +<syntax><argument>время</argument></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива определяет, через какое время нужно проверять актуальность -информации об элементе в <link id="open_file_cache"/>. - +Определяет время, через которое следует проверять актуальность информации +об элементе в +<link id="open_file_cache"/>. +<!-- +При включенном +<link id="open_file_cache_events"/> +открытые дескрипторы файлов проверяются лишь единожды, а затем обновляются +по факту их изменения. +--> </para> </directive> <directive name="optimize_server_names"> -<syntax><value>[on|off]</value></syntax> -<default>on</default> -<context>http, server</context> - -<para> -Устаревшая директива. -</para> +<syntax><value>on</value> | <value>off</value></syntax> +<default>off</default> +<context>http</context> +<context>server</context> <para> -Директива разрешает или запрещает оптимизировать проверку имени хоста -в name-based виртуальных серверах. -Проверка в частности влияет на имя хоста, используемого в редиректах. +Директива устарела, вместо неё следует использовать директиву +<link id="server_name_in_redirect"/>. +</para> + +<!-- +<para> +Разрешает или запрещает оптимизировать проверку имени хоста в name-based +виртуальных серверах. +Проверка в частности влияет на имя хоста, используемого в перенаправлениях. Если оптимизация разрешена и все name-based сервера, слушающие на одной -паре адрес:порт, имеют одинаковую конфигурацию, то во время исполнения -запроса имена не проверяются и в редиректах используется первое имя сервера. -Если в редиректе нужно использовать имя хоста, переданное клиентом, +паре адрес:порт, имеют одинаковую конфигурацию, то во время исполнения запроса +имена не проверяются и в перенаправлениях используется первое имя сервера. +Если в перенаправлении нужно использовать имя хоста, переданное клиентом, то оптимизацию нужно выключить. </para> +--> </directive> <directive name="port_in_redirect"> -<syntax><value>[on|off]</value></syntax> +<syntax><value>on</value> | <value>off</value></syntax> <default>on</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Разрешает или запрещает указывать порт в перенаправлениях, выдаваемых nginx'ом. +</para> <para> -Директива разрешает или запрещает указывать порт в редиректах, -выдаваемых nginx'ом. +См. также директиву <link id="server_name_in_redirect"/>. +</para> + +</directive> + + +<directive name="postpone_output"> +<syntax><argument>размер</argument></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> +<syntax><argument>размер</argument></syntax> <default>0</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива задаёт ядру размер предчтения при работе с файлами. -Под Линуксом используется системный вызов -<example> -posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL); -</example> -поэтому размер игнорируется. +Задаёт ядру размер предчтения при работе с файлами. </para> <para> -Под FreeBSD используется fcntl(O_READAHEAD, размер), появившийся -во FreeBSD-9 CURRENT. Для FreeBSD 7 нужно установить +На Linux используется системный вызов +<code>posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)</code>, +поэтому аргумент <argument>размер</argument> там игнорируется. +</para> + +<para> +На FreeBSD используется системный вызов +<code>fcntl(O_READAHEAD,</code><argument>размер</argument><code>)</code>, +появившийся во FreeBSD 9.0-CURRENT. +Для FreeBSD 7 необходимо установить <link url="http://sysoev.ru/freebsd/patch.readahead.txt">патч</link>. </para> @@ -1076,64 +1629,113 @@ <directive name="recursive_error_pages"> -<syntax><value>[on|off]</value></syntax> +<syntax><value>on</value> | <value>off</value></syntax> <default>off</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива разрешает или запрещает делать несколько перенаправлений через -директиву <link id="error_page"/>. +Разрешает или запрещает делать несколько перенаправлений через директиву +<link id="error_page"/>. +</para> + +</directive> + + +<directive name="request_pool_size"> +<syntax><argument>размер</argument></syntax> +<default>4k</default> +<context>http</context> +<context>server</context> + +<para> +Позволяет производить точную настройку выделений памяти +под конкретные запросы. +Эта директива не оказывает существенного влияния на +производительность и её не следует использовать. </para> </directive> <directive name="reset_timedout_connection"> -<syntax><value>[on|off]</value></syntax> +<syntax> + <value>on</value> | <value>off</value></syntax> <default>off</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива разрешает или запрещает сбрасывать соединение по таймауту. -Сброс делается следующим образом — перед закрытием сокета для него -ставится опция SO_LINGER с таймаутом 0. После чего при закрытии сокета -клиенту отсылается пакет RST, а всё память, связанная с этим сокетом, -освобождается. Это позволяет избежать длительного нахождения уже закрытого -сокета в состоянии FIN_WAIT1 с заполненными буферами. +Разрешает или запрещает сброс соединений по таймауту. +Сброс делается следующим образом — перед закрытием сокета для него +ставится опция +<c-def>SO_LINGER</c-def> +с таймаутом 0. +После чего при закрытии сокета клиенту отсылается TCP RST, а вся память, +связанная с этим сокетом, освобождается. +Это позволяет избежать длительного нахождения уже закрытого сокета в +состоянии FIN_WAIT1 с заполненными буферами. </para> <para> -Необходимо отметить, что соединения, находящиеся в состоянии keepalive, -по истечении таймаута закрываются обычным образом. +Необходимо отметить, что keep-alive соединения по истечении таймаута +закрываются обычным образом. </para> </directive> <directive name="resolver"> -<syntax><value>адрес</value></syntax> +<syntax> +<argument>адрес</argument> ... +[<parameter>valid</parameter>=<argument>время</argument>] +</syntax> <default/> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива задаёт адрес name-сервера, например: +Задаёт серверы DNS, используемые для преобразования имён апстрим серверов +в адреса, например: <example> - resolver 127.0.0.1; +resolver 127.0.0.1 192.0.2.1; </example> +Аргумент <argument>адрес</argument> может быть задан либо +IPv4-адресом, либо именем хоста; +во втором случае используется первый полученный IPv4-адрес. +Серверы DNS опрашиваются циклически. +<note> +До версии 1.1.7 можно было задать лишь один DNS-сервер. +</note> +По умолчанию nginx кэширует ответы, используя значение TTL из ответа. +Необязательный параметр <parameter>valid</parameter> позволяет это +переопределить: +<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> +<syntax><argument>время</argument></syntax> <default>30s</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива задаёт таймаут для определения имени, например: +Задаёт таймаут для преобразования имени в адрес, например: <example> - resolver_timeout 5s; +resolver_timeout 5s; </example> </para> @@ -1141,28 +1743,34 @@ <directive name="root"> -<syntax><value>путь</value></syntax> +<syntax><argument>путь</argument></syntax> <default>html</default> -<context>http, server, location, if в location</context> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if в location</context> <para> -Директива задаёт корневой каталог для запросов. +Задаёт корневой каталог для запросов. Например, при такой конфигурации <example> - location /i/ { - root /data/w3; - } +location /i/ { + root /data/w3; +} </example> -на запрос "/i/top.gif" будет отдан файл "/data/w3/i/top.gif". +в ответ на запрос “<code>/i/top.gif</code>” будет отдан файл +<path>/data/w3/i/top.gif</path>. </para> <para> -В значении пути можно использовать переменные. +В значении аргумента <argument>путь</argument> можно использовать переменные, +кроме <var>$document_root</var> и <var>$realpath_root</var>. </para> <para> -Путь к файлу формируется как простое добавление URI к значению директивы root. -Если же необходима модификация URI, то нужно воспользоваться директивой +Путь к файлу формируется путём простого добавления URI к значению директивы +<code>root</code>. +Если же URI необходимо поменять, следует воспользоваться директивой <link id="alias"/>. </para> @@ -1170,23 +1778,31 @@ <directive name="satisfy"> -<syntax><value>all|any</value></syntax> +<syntax><value>all</value> | <value>any</value></syntax> <default>all</default> +<context>http</context> +<context>server</context> <context>location</context> <para> -Директива разрешает доступ при хотя бы одной успешной проверке, -выполненной модулями <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>: +Разрешает доступ, если оба (<value>all</value>) +или хотя бы один (<value>any</value>) из модулей +<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; + satisfy any; + + allow 192.168.1.0/32; + deny all; + + auth_basic "closed site"; + auth_basic_user_file conf/htpasswd; } </example> </para> @@ -1195,40 +1811,91 @@ <directive name="satisfy_any"> -<syntax><value>on|off</value></syntax> +<syntax><value>on</value> | <value>off</value></syntax> <default>off</default> +<context>http</context> +<context>server</context> <context>location</context> <para> -Директива переименована в директиву <link id="satisfy"/>. +Эта директива была переименована в директиву +<link id="satisfy">satisfy any</link>. +</para> + +</directive> + + +<directive name="send_lowat"> +<syntax><argument>размер</argument></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>60</default> -<context>http, server, location</context> +<syntax><argument>время</argument></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива задаёт таймаут при передаче ответа клиенту. +Задаёт таймаут при передаче ответа клиенту. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями записями. Если по истечении этого времени клиент ничего не примет, -то nginx закрывает соединение. +соединение будет закрыто. </para> </directive> <directive name="sendfile"> -<syntax><value>[on|off]</value></syntax> + +<syntax><value>on</value> | <value>off</value></syntax> <default>off</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if в location</context> <para> -Директива разрешает или запрещает использовать sendfile(). +Разрешает или запрещает использовать +<c-func>sendfile</c-func>. +</para> + +</directive> + + +<directive name="sendfile_max_chunk"> + +<syntax><argument>размер</argument></syntax> +<default>0</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +При установке в ненулевое значение ограничивает объём данных, +который может передан за один вызов <c-func>sendfile</c-func>. +Без этого ограничения одно быстрое соединение может целиком +захватить рабочий процесс. </para> </directive> @@ -1240,14 +1907,14 @@ <context>http</context> <para> -Директива задаёт конфигурацию для виртуального сервера. -Чёткого разделения виртуальных серверов ip-based (на основании ip-адреса) -и name-based (на основании имени, передаваемого в строке "Host" -заголовка запроса), нет. -Вместо этого директивами <link id="listen"/> описываются все адреса -и порты, на которых нужно принимать соединения для этого сервера, -и в директиве <link id="server_name"/> указываются все имена серверов. -Пример конфигурации описан в <link doc="../virtual_hosts.xml"> +Задаёт конфигурацию для виртуального сервера. +Чёткого разделения виртуальных серверов на IP-based (на основании IP-адреса) +и name-based (на основании поля <header>Host</header> заголовка запроса) нет. +Вместо этого директивами <link id="listen"/> описываются все +адреса и порты, на которых нужно принимать соединения для этого сервера, +а в директиве <link id="server_name"/> указываются все имена серверов. +Пример конфигурации описан в документе по +<link doc="../virtual_hosts.xml"> настройке виртуальных серверов</link>. </para> @@ -1255,27 +1922,26 @@ <directive name="server_name"> -<syntax><value>имя [...]</value></syntax> -<default>hostname</default> +<syntax><argument>имя</argument> ...</syntax> +<default>""</default> <context>server</context> <para> -Директива задаёт имена виртуального сервера, например: +Задаёт имена виртуального сервера, например: <example> server { - server_name example.com www.example.com; + server_name example.com www.example.com; } </example> </para> <para> Первое имя становится основным именем сервера. -По умолчанию используется имя машины (hostname). -В именах серверов можно использовать "*" для замены первой или последней -части имени: +В именах серверов можно использовать звёздочку (“<code>*</code>”) +для замены первой или последней части имени: <example> server { - server_name example.com *.example.com www.example.*; + server_name example.com *.example.com www.example.*; } </example> </para> @@ -1284,94 +1950,103 @@ Два первых вышеприведённых имени можно объединить в одно: <example> server { - server_name .example.com; -} -</example> -</para> - -<para> -Кроме того, в качестве имени сервера можно использовать регулярное -выражение, указав перед ним "~": -<example> -server { - server_name www.example.com ~^www\d+\.example\.com$; + server_name .example.com; } </example> </para> <para> -Регулярное выражение может содержать выделения (0.7.40), которые -могут затем использоваться в других директивах: +Если аргумент равен “<var>$hostname</var>” (0.9.4), то +подставляется имя хоста (hostname) машины. +</para> + +<para> +В качестве имени сервера можно также использовать регулярное выражение, +указав перед ним тильду (“<code>~</code>”): <example> server { - server_name ~^(www\.)?(.+)$; + server_name www.example.com ~^www\d+\.example\.com$; +} +</example> +</para> + +<para> +Регулярное выражение может содержать выделения (0.7.40), +которые могут затем использоваться в других директивах: +<example> +server { + server_name ~^(www\.)?(.+)$; location / { - root /sites/$2; + root /sites/$2; } } server { - server_name _; + server_name _; location / { - root /sites/default; + root /sites/default; } } </example> </para> <para> -Начиная с 0.8.25, именованные выделения в регулярном выражении создают -переменные, которые могут затем использоваться в других директивах: +Именованные выделения в регулярном выражении создают переменные (0.8.25), +которые могут затем использоваться в других директивах: <example> server { - server_name ~^(www\.)?(<emphasis>?<domain></emphasis>.+)$; + server_name ~^(www\.)?(?<domain>.+)$; location / { - root /sites/<emphasis>$domain</emphasis>; + root /sites/$domain; } } server { - server_name _; + server_name _; location / { - root /sites/default; + root /sites/default; } } </example> </para> <para> -Начиная с 0.7.11, можно использовать пустое имя "": +Возможно также указать пустое имя сервера (0.7.11): <example> server { - server_name www.example.com ""; + server_name www.example.com ""; } </example> -что позволяет обрабатывать запросы без строки "Host" в заголовке запроса -в этом сервере, а не в сервере по умолчанию для данной пары адрес:порт. +Это позволяет обрабатывать запросы без поля <header>Host</header> заголовка +запроса в этом сервере, а не в сервере по умолчанию для данной пары адрес:порт. +Это настройка по умолчанию. +<note> +До 0.8.48 по умолчанию использовалось имя хоста (hostname) машины. +</note> </para> <para> Порядок проверки имён следующий: -<list type="bullet"> +<list type="enum"> <listitem> -полные имена, +полные имена </listitem> <listitem> -имена с маской в начале имени — *.example.com, +имена с маской в начале имени, например “<code>*.example.com</code>” </listitem> <listitem> -имена с маской в конце имени — mail.*, +имена с маской в конце имени, например “<code>mail.*</code>” </listitem> <listitem> -регулярные выражения. +регулярные выражения </listitem> </list> @@ -1381,71 +2056,81 @@ <directive name="server_name_in_redirect"> -<syntax><value>[on|off]</value></syntax> -<default>on</default> -<context>http, server, location</context> +<syntax><value>on</value> | <value>off</value></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива разрешает или запрещает использовать в редиректах, выдаваемых -nginx'ом, основное имя сервера, задаваемое директивой +Разрешает или запрещает использовать в перенаправлениях, выдаваемых nginx'ом, +основное имя сервера, задаваемое директивой <link id="server_name"/>. -Если использование основного имени запрещено, то используется имя, -указанного в строке "Host" в заголовке запроса. -Если же этой строки нет, то используется IP-адрес сервера. +Если запрещено, то используется имя, указанное в поле <header>Host</header> +заголовка запроса. +Если же этого поля нет, то используется IP-адрес сервера. </para> -</directive> - - -<directive name="server_names_hash_max_size"> -<syntax><value>число</value></syntax> -<default>512</default> -<context>http</context> - <para> -Директива задаёт максимальный размер хэш-таблиц имён серверов. -Подробнее смотри в <link doc="../hash.xml">описании -настройки хэшей</link>. +См. также директиву <link id="port_in_redirect"/>. </para> </directive> <directive name="server_names_hash_bucket_size"> -<syntax><value>число</value></syntax> -<default>32/64/128</default> +<syntax><argument>размер</argument></syntax> +<default>32|64|128</default> <context>http</context> <para> -Директива задаёт размер корзины в хэш-таблицах имён серверов. +Задаёт размер корзины в хэш-таблицах имён серверов. Значение по умолчанию зависит от размера строки кэша процессора. -Подробнее смотри в <link doc="../hash.xml">описании -настройки хэшей</link>. +Подробнее смотрите в документе по +<link doc="../hash.xml">настройке хэшей</link>. +</para> + +</directive> + + +<directive name="server_names_hash_max_size"> +<syntax><argument>размер</argument></syntax> +<default>512</default> +<context>http</context> + +<para> +Задаёт максимальный <argument>размер</argument> хэш-таблиц имён серверов. +Подробнее смотрите в документе по +<link doc="../hash.xml">настройке хэшей</link>. </para> </directive> <directive name="server_tokens"> -<syntax><value>[on|off]</value></syntax> +<syntax><value>on</value> | <value>off</value></syntax> <default>on</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива разрешает или запрещает выдавать версию nginx'а -в сообщениях об ошибках и в строке заголовка ответа "Server". +Разрешает или запрещает выдавать версию nginx'а в сообщениях об ошибках и +в поле <header>Server</header> заголовка ответа. </para> </directive> <directive name="tcp_nodelay"> -<syntax><value>[on|off]</value></syntax> +<syntax><value>on</value> | <value>off</value></syntax> <default>on</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива разрешает или запрещает использовать опцию TCP_NODELAY. +Разрешает или запрещает использование опции <c-def>TCP_NODELAY</c-def>. Опция включаются только при переходе соединения в состояние keep-alive. </para> @@ -1453,24 +2138,27 @@ <directive name="tcp_nopush"> -<syntax><value>[on|off]</value></syntax> +<syntax><value>on</value> | <value>off</value></syntax> <default>off</default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива разрешает или запрещает использовать опции -TCP_NOPUSH во FreeBSD или TCP_CORK в Linux. +Разрешает или запрещает использование опции сокета +<c-def>TCP_NOPUSH</c-def> во FreeBSD или +<c-def>TCP_CORK</c-def> в Linux. Опции включаются только при использовании <link id="sendfile"/>. Включение опции позволяет <list type="bullet"> <listitem> -передавать заголовок ответа и начало файла в одном пакете в Linux -и во FreeBSD 4.x; +передавать заголовок ответа и начало файла в одном пакете +в Linux и во FreeBSD 4.*; </listitem> <listitem> -передавать файл в полных пакетах. +передавать файл полными пакетами. </listitem> </list> @@ -1480,22 +2168,45 @@ <directive name="try_files"> -<syntax><value>файл [файл ...] (uri|=код)</value></syntax> +<syntax> + <argument>файл</argument> ... + <argument>uri</argument> +</syntax> +<syntax> + <argument>файл</argument> ... + =<argument>код</argument> +</syntax> <default/> +<context>server</context> <context>location</context> <para> -Директива проверяет существование файлов в заданном порядке -и использует для обработки запроса первый найденный файл, причём -обработка делается в контексте этого же location'а. -С помощью слэша в конце имени можно задать проверку существования -каталога, например, так — "$uri/". -В случае, если ни один файл не найден, то делается внутренний редирект -на последний параметр. -Последний параметр может быть кодом (0.7.51): +Проверяет существование файлов в заданном порядке и использует +для обработки запроса первый найденный файл, причём обработка +делается в контексте этого же location'а. +Путь к файлу строится из аргумента <argument>файл</argument> +в соответствии с директивами +<link id="root"/> и <link id="alias"/>. +С помощью слэша в конце имени можно проверить существование каталога, +например, “<code>$uri/</code>”. +В случае, если ни один файл не найден, то делается внутреннее +перенаправление на <argument>uri</argument>, заданный последним аргументом. +Например: +<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; + try_files $uri $uri/index.html $uri.html =404; } </example> </para> @@ -1504,13 +2215,13 @@ Пример использования при проксировании Mongrel: <example> location / { - try_files /system/maintenance.html - $uri $uri/index.html $uri.html - @mongrel; + try_files /system/maintenance.html + $uri $uri/index.html $uri.html + @mongrel; } location @mongrel { - proxy_pass http://mongrel; + proxy_pass http://mongrel; } </example> </para> @@ -1519,57 +2230,57 @@ Пример использования вместе с Drupal/FastCGI: <example> location / { - try_files $uri $uri/ @drupal; + 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; + 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_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> -В этом примере директива try_files +В следующем примере директива <code>try_files</code> <example> location / { - try_files $uri $uri/ @drupal; + try_files $uri $uri/ @drupal; } </example> аналогична директивам <example> location / { - error_page 404 = @drupal; - log_not_found off; + 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; + try_files $uri @drupal; + + fastcgi_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; ... } </example> -try_files тестирует существование PHP-файла, +<code>try_files</code> проверяет существование PHP-файла, прежде чем передать запрос FastCGI-серверу. </para> @@ -1577,22 +2288,22 @@ Пример использования вместе с Wordpress и Joomla: <example> location / { - try_files $uri $uri/ @wordpress; + try_files $uri $uri/ @wordpress; } location ~ \.php$ { - try_files $uri @wordpress; - - fastcgi_pass ...; - - fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; + 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_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to/index.php; ... прочие fastcgi_param } </example> @@ -1608,207 +2319,354 @@ image/gif gif; image/jpeg jpg; </default> -<context>http, server, location</context> +<context>http</context> +<context>server</context> +<context>location</context> <para> -Директива задаёт соответствие расширения и MIME-типов ответов. -Одному MIME-типу может соответствовать несколько расширений. +Задаёт соответствие расширений имён файлов и 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> -Достаточно полная таблица соответствий входит в дистрибутив -и находится в файле conf/mime.types. +Для того, чтобы для определённого location'а для всех ответов +выдавался MIME-тип “<code>application/octet-stream</code>”, +можно использовать следующее: +<example> +location /download/ { + types { } + default_type application/octet-stream; +} +</example> </para> +</directive> + + +<directive name="types_hash_bucket_size"> +<syntax><argument>размер</argument></syntax> +<default>32|64|128</default> +<context>http</context> +<context>server</context> +<context>location</context> + <para> -Для того, чтобы для определённого location'а для всех ответов выдавался -MIME-тип "application/octet-stream", можно использовать следующее: -<example> -location /download/ { - types { } - default_type application/octet-stream; -} -</example> +Задаёт размер корзины в хэш-таблицах типов. +Значение по умолчанию зависит от размера строки кэша процессора. +Подробнее смотрите в документе по +<link doc="../hash.xml">настройке хэшей</link>. +</para> + +</directive> + + +<directive name="types_hash_max_size"> +<syntax><argument>размер</argument></syntax> +<default>1024</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт максимальный <argument>размер</argument> хэш-таблиц типов. +Подробнее смотрите в документе по +<link doc="../hash.xml">настройке хэшей</link>. </para> </directive> <directive name="underscores_in_headers"> -<syntax><value>[on|off]</value></syntax> +<syntax><value>on</value> | <value>off</value></syntax> <default>off</default> -<context>http, server</context> +<context>http</context> +<context>server</context> <para> -Директива разрешает или запрещает использование символов подчёркивания -в строках заголовка запроса клиента. +Разрешает или запрещает использование символов подчёркивания в +полях заголовка запроса клиента. +Если запрещено, поля заголовка запроса, в чьих именах есть подчёркивания, +помечаются как недопустимые и подпадают под действие директивы +<link id="ignore_invalid_headers"/>. +</para> + +</directive> + + +<directive name="variables_hash_bucket_size"> +<syntax><argument>размер</argument></syntax> +<default>64</default> +<context>http</context> + +<para> +Задаёт размер корзины в хэш-таблице переменных. +Подробнее смотрите в документе по +<link doc="../hash.xml">настройке хэшей</link>. +</para> + +</directive> + + +<directive name="variables_hash_max_size"> +<syntax><argument>размер</argument></syntax> +<default>512</default> +<context>http</context> + +<para> +Задаёт максимальный <argument>размер</argument> хэш-таблицы переменных. +Подробнее смотрите в документе по +<link doc="../hash.xml">настройке хэшей</link>. </para> </directive> </section> - -<section name="Встроенные переменные" id="variables"> +<section id="variables" name="Встроенные переменные"> <para> -Модуль ngx_http_core_module поддерживает встроенные переменные, имена -которых совпадают с именами переменных в Apache. -Прежде всего, это переменные, представляющие из себя строки заголовка -запроса клиента, например, $http_user_agent, $http_cookie -и тому подобное. Кроме того, есть и другие переменные: -<list type="bullet"> - -<listitem> -$args, эта переменная равна аргументам в строке запроса; -</listitem> - -<listitem> -$arg_<value>name</value>, эта переменная равна аргументу <value>name</value> -в строке запроса; -</listitem> - -<listitem> -$binary_remote_addr, эта переменная равна адресу клиента в бинарном виде, -длина её значения всегда 4 байта; -</listitem> - -<listitem> -$content_length, эта переменная равна строке "Content-Length" в заголовке -запроса; -</listitem> - -<listitem> -$content_type, эта переменная равна строке "Content-Type" в заголовке запроса; -</listitem> - -<listitem> -$cookie_<value>name</value>, эта переменная равна cookie <value>name</value>; -</listitem> - -<listitem> -$document_root, эта переменная равна значению директивы root для -текущего запроса; -</listitem> - -<listitem> -$document_uri, то же самое, что и $uri; -</listitem> - -<listitem> -$host, эта переменная равна строке "Host" в заголовке запроса -или имени сервера, на который пришёл запрос, если этой строки нет; -</listitem> - -<listitem> -$hostname, эта переменная равна имени хоста; -</listitem> - -<listitem> -$http_<value>name</value>, эта переменная равна строке <value>name</value> -в заголовке запроса; -</listitem> - -<listitem> -$is_args, эта переменная равна "?", если в строке запроса есть аргументы, -и пустой строке, если их нет; -</listitem> - -<listitem> -$limit_rate, эта переменная позволяет установить ограничение -скорости соединения; -</listitem> - -<listitem> -$pid, эта переменная равна номеру рабочего процесса; -</listitem> - -<listitem> -$request_method, эта переменная равна методу запроса, -обычно это "GET" или "POST"; -</listitem> - -<listitem> -$remote_addr, эта переменная равна адресу клиента; -</listitem> - -<listitem> -$remote_port, эта переменная равна порту клиента; -</listitem> - -<listitem> -$remote_user, эта переменная равна имени пользователя, используемого -в Basic аутентификации; -</listitem> - -<listitem> -$realpath_root, эта переменная равна значению директивы root для -текущего запроса, при этом все символические ссылки преобразованы -в реальные путь; -</listitem> - -<listitem> -$request_filename, эта переменная равна пути к файлу для текущего -запроса, формируемому из директив root или alias и URI запроса; -</listitem> - -<listitem> -$request_body, эта переменная содержит тело запроса. -Значение переменной появляется в location'ах, обрабатываемых директивами +Модуль <code>ngx_http_core_module</code> поддерживает встроенные переменные, +имена которых совпадают с именами переменных веб-сервера Apache. +Прежде всего, это переменные, представляющие из себя поля заголовка +запроса клиента, такие как <var>$http_user_agent</var>, <var>$http_cookie</var> +и тому подобное. +Кроме того, есть и другие переменные: +<list type="tag"> + +<tag-name><var>$arg_</var><argument>имя</argument></tag-name> +<tag-desc> +аргумент <argument>имя</argument> в строке запроса +</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><argument>имя</argument></tag-name> +<tag-desc> +cookie <argument>имя</argument> +</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><argument>имя</argument></tag-name> +<tag-desc> +поле <argument>имя</argument> заголовка запроса +</tag-desc> + +<tag-name><var>$https</var></tag-name> +<tag-desc> +“<code>on</code>” +если соединение работает в режиме SSL, +либо пустая строка +</tag-desc> + +<tag-name><var>$is_args</var></tag-name> +<tag-desc> +“<code>?</code>”, если в строке запроса есть аргументы, +и пустая строка, если их нет +</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"/>. -</listitem> - -<listitem> -$request_body_file, эта переменная равна имени временного файла, в котором -хранится тело запроса. -По завершению работы файл необходимо удалить. -Для того, чтобы тело запроса клиента всегда записывалось в файл, нужно -указать <link doc="ngx_http_core_module.xml" id="client_body_in_file_only">client_body_in_file_only on</link>. -При передаче имени в проксированном запросе или в запросе к FastCGI-серверу -следует запретить передачу самого тела директивами -"proxy_pass_request_body off" или -"fastcgi_pass_request_body off" соответственно. -</listitem> - -<listitem> -$request_uri, эта переменная равна полному первоначальному URI вместе -с аргументами; -</listitem> - -<listitem> -$query_string, то же самое, что и $args; -</listitem> - -<listitem> -$scheme, эта переменная равна схеме запроса — "http" или "https"; -</listitem> - -<listitem> -$server_protocol, эта переменная равна протоколу запроса, -обычно это "HTTP/1.0" или "HTTP/1.1"; -</listitem> - -<listitem> -$server_addr, эта переменная равна адресу сервера, на который пришёл запрос. -Как правило, для получения значения этой переменной делается один системный -вызов. Для того, чтобы избежать системного вызова, нужно указывать -адреса в директивах listen и использовать параметр bind; -</listitem> - -<listitem> -$server_name, эта переменная равна имени сервера, на который пришёл запрос; -</listitem> - -<listitem> -$server_port, эта переменная равна порту сервера, на который пришёл запрос; -</listitem> - -<listitem> -$uri, эта переменная равна текущему URI в запросе, он -может отличаться от первоначального, например, при внутренних редиректах -или при использовании индексных файлов. -</listitem> +и +<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>. +</para> +</tag-desc> + +<tag-name><var>$request_body_file</var></tag-name> +<tag-desc> +имя временного файла, в котором хранится тело запроса +<para> +По завершению обработки файл необходимо удалить. +Для того, чтобы тело запроса всегда записывалось в файл, +следует указать +<link id="client_body_in_file_only">client_body_in_file_only on</link>. +При передаче имени временного файла в проксированном запросе +или в запросе к FastCGI-серверу следует запретить передачу самого +тела директивами +<link doc="ngx_http_proxy_module.xml" id="proxy_pass_request_body"> +proxy_pass_request_body off</link> +или +<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass_request_body"> +fastcgi_pass_request_body off</link> +соответственно. +</para> +</tag-desc> + +<tag-name><var>$request_completion</var></tag-name> +<tag-desc> +“<code>OK</code>” если запрос завершился, +либо пустая строка +</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> +метод запроса, обычно +“<code>GET</code>” или “<code>POST</code>” +</tag-desc> + +<tag-name><var>$request_uri</var></tag-name> +<tag-desc> +оригинальный URI запроса целиком (с аргументами) +</tag-desc> + +<tag-name><var>$scheme</var></tag-name> +<tag-desc> +схема запроса, “<code>http</code>” или “<code>https</code>” +</tag-desc> + +<tag-name><var>$sent_http_</var><argument>имя</argument></tag-name> +<tag-desc> +поле <argument>имя</argument> заголовка ответа +</tag-desc> + +<tag-name><var>$server_addr</var></tag-name> +<tag-desc> +адрес сервера, принявшего запрос +<para> +Получение значения этой переменной обычно требует одного системного вызова. +Чтобы избежать системного вызова, в директивах <link id="listen"/> +следует указывать адреса и использовать параметр <parameter>bind</parameter>. +</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> +протокол сервера, обычно +“<code>HTTP/1.0</code>” +или +“<code>HTTP/1.1</code>” +</tag-desc> + +<tag-name><var>$uri</var></tag-name> +<tag-desc> +текущий URI запроса +<para> +Он может отличаться от первоначального, например, при внутренних +перенаправлениях или при использовании индексных файлов. +</para> +</tag-desc> </list> </para>