Mercurial > hg > nginx-site
diff xml/ru/docs/http/ngx_http_core_module.xml @ 76:4a4caa566120
Russian documentation import.
Changes in module.dtd: <example> now allowed to contain <value> and
<emphasis> elements (we need this to show important parts in examples),
less strict checking of <directive> syntax (we don't want to fully
document some directives, notably deprecated ones).
Known issues:
1. <syntax> elements are preserved as is, they will require manual conversion
(likely to some not-yet-existed format a la DocBook cmdsynopsis, as
currently used one seems to be incomplete);
2. <value> no longer corresponds to replaceable content, and it's use in
examples isn't correct;
3. <link doc="document#fragment"> doesn't work with current xslt, either
should be supported or changed to <link doc="document" id="fragment">.
The following files are intentionally omitted: maillists.xml (support.xml
should be used instead), experimental.xml (obsolete), faq.xml (conflicts
with existing one, needs discussion).
Not yet linked to site.
author | Maxim Dounin <mdounin@mdounin.ru> |
---|---|
date | Tue, 11 Oct 2011 12:57:50 +0000 |
parents | |
children | 0a45870d0160 |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/xml/ru/docs/http/ngx_http_core_module.xml @@ -0,0 +1,1819 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_core_module" + link="/ru/docs/http/ngx_http_core_module.html" + lang="ru"> + +<section name="Директивы" id="directives"> + +<directive name="aio"> +<syntax>aio <value>[on|off|sendfile]</value></syntax> +<default>aio off</default> +<context>http, server, location</context> + +<para> +Директива (0.8.11) разрешает или запрещает использовать файловый AIO +во FreeBSD и Linux. +</para> + +<para> +Во FreeBSD AIO можно использовать, начиная с FreeBSD 4.3 версии. +AIO можно собрать в ядре статически +<example> +options VFS_AIO +</example> +или же подгрузить динамически +<example> +kldload aio +</example> +</para> + +<para> +Во FreeBSD 5 и 6 при включении AIO статически или динамически на стадии +загрузки ядра вся сетевая подсистема будет использовать GiantLock, +что может негативно сказаться на производительности системы в целом. +Эта зависимость устранена во FreeBSD-6.4 STABLE от 2009 года и во FreeBSD 7. +Однако, начиная с FreeBSD 5.3, есть возможность включать AIO, +не связывая сетевую подсистему GiantLock'ом — для этого модуль AIO +нужно подгружать уже после загрузки ядра. +В этом случае в /var/log/messages появится сообщение +<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 только для работы с диском, то проблем +не возникает. +</note> +</para> + +<para> +Для работы AIO нужно выключить sendfile: +<example> +location /video/ { + sendfile off; + aio on; + output_buffers 1 64k; +} +</example> +</para> + +<para> +Кроме того, начиная с FreeBSD 5.2.1 и nginx-0.8.12, AIO также можно +использовать для подгрузки данных для sendfile(): +<example> +location /video/ { + sendfile on; + tcp_nopush on; + aio sendfile; +} +</example> +В такой конфигурации используется флаг SF_NODISKIO и sendfile() +не блокируется на диске, а сообщает об отсутствии данных в памяти, +после чего nginx инициирует асинхронную подгрузку данных, +читая только один байт. При этом ядро FreeBSD подгружает в память +первые 128K файла, однако при последующих чтениях файл подгружается +частями только по 16K. Изменить это можно с помощью директивы +<link id="read_ahead">read_ahead</link>. +</para> + +<para> +В Linux AIO можно использовать, только начиная с версии ядра 2.6.22, +и, кроме того, ещё необходимо дополнительно включать +<link id="directio">directio</link>, иначе чтение будет блокирующимся: +<example> +location /video/ { + aio on; + directio 512; + output_buffers 1 128k; +} +</example> +</para> + +<para> +Поскольку directio в Linux можно использовать только для чтения блоков, +выравненных по 512 байт (или 4К для XFS), то невыравненный конец файла +будет читаться блокировано. То же относится к запросам части ответа +byte-ranges и к запросам FLV не с начала файла: чтение невыровненных начала +и конца ответа будет блокирующимся. sendfile выключать не нужно, так +как при использовании directio он выключается сам. +</para> + +</directive> + + +<directive name="alias"> +<syntax>alias <value>путь</value></syntax> +<default>нет</default> +<context>location</context> + +<para> +Директива задаёт замену для указанного location'а. +Например, при такой конфигурации +<example> +location /i/ { + alias /data/w3/images/; +} +</example> +на запрос "/i/top.gif" будет отдан файл "/data/w3/images/top.gif". +</para> + +<para> +В значении пути можно использовать переменные. +</para> + +<para> +Если директива alias используется внутри location'а, заданного +регулярным выражением, то регулярное выражение должно содержать выделения, +а директива alias — ссылки на эти выделения (0.7.40), например: +<example> +location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { + alias /data/w3/images/$1; +} +</example> +</para> + +<para> +Если location и последняя часть значения директивы совпадают: +<example> +location /images/ { + alias /data/w3/images/; +} +</example> +то лучше воспользоваться директивой <link id="root"/>: +<example> +location /images/ { + root /data/w3; +} +</example> +</para> + +</directive> + + +<directive name="client_body_in_file_only"> +<syntax>client_body_in_file_only <value>on|clean|off</value></syntax> +<default>client_body_in_file_only off</default> +<context>http, server, location</context> + +<para> +Директива определяет, сохранять ли всё тело запроса клиента в файл. +Директиву можно использовать для отладки и при использовании +переменной $request_body_file или метода <link doc="ngx_http_perl_module.xml#methods">$r->request_body_file</link> +модуля ngx_http_perl_module. +</para> + +<para> +При использовании параметра "on" временные файлы по окончании +обработки запроса не удаляется. +</para> + +<para> +Параметр "clean" разрешает удалять временные файлы, оставшиеся по окончании +обработки запроса. +</para> + +</directive> + + +<directive name="client_body_in_single_buffer"> +<syntax>client_body_in_single_buffer <value>on|off</value></syntax> +<default>client_body_in_single_buffer off</default> +<context>http, server, location</context> + +<para> +Директива определяет, хранить ли всё тело запроса клиента в одном буфере. +Директива рекомендуется при использовании переменной $request_body +для уменьшения операций копирования. +</para> + +</directive> + + +<directive name="client_body_buffer_size"> +<syntax>client_body_buffer_size <value>размер</value></syntax> +<default>client_body_buffer_size 8k/16k</default> +<context>http, server, location</context> + +<para> +Директива задаёт размер буфера для чтения тела запроса клиента. +Если тело запроса больше заданного буфера, то всё тело запроса или только +его часть записывается во временный файл. +По умолчанию размер одного буфера равен двум размерам страницы, в зависимости +от платформы это или 8K, или 16K. +</para> + +</directive> + + +<directive name="client_body_temp_path"> +<syntax>client_body_temp_path <value>путь [ уровень1 [ уровень2 [ уровень3 ] ] ] +</value></syntax> +<default>client_body_temp_path client_body_temp</default> +<context>http, server, location</context> + +<para> +Директива задаёт имя каталога для хранения временных файлов с телом запроса +клиента. +В каталоге может использоваться иерархия подкаталогов до трёх уровней. +Например, при такой конфигурации +<example> +client_body_temp_path /spool/nginx/client_temp 1 2; +</example> +имя временного будет такого вида: +<example> +/spool/nginx/client_temp/7/45/00000123457 +</example> +</para> + +</directive> + + +<directive name="client_body_timeout"> +<syntax>client_body_timeout <value>время</value></syntax> +<default>client_body_timeout 60</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут при чтении тела запроса клиента. +Таймаут устанавливается не на всю передачу тела запроса, +а только между двумя операциями чтения. +Если по истечении этого времени клиент ничего не передаст, +то ему возвращается ошибка "Request time out" (408). +</para> + +</directive> + + +<directive name="client_header_buffer_size"> +<syntax>client_header_buffer_size <value>размер</value></syntax> +<default>client_header_buffer_size 1k</default> +<context>http, server</context> + +<para> +Директива задаёт размер буфера для чтения заголовка запроса клиента. +Для подавляющего большинства запросов вполне достаточно буфера размером в 1K. +Однако если в запросе есть большие cookies или же запрос пришёл +от wap-клиента, то он может не поместиться в 1K. +Поэтому, если строка запроса или строка заголовка запроса не помещается +полностью в этот буфер, то выделяются большие буферы, задаваемые директивой +<link id="large_client_header_buffers"/>. +</para> + +</directive> + + +<directive name="client_header_timeout"> +<syntax>client_header_timeout <value>время</value></syntax> +<default>client_header_timeout 60</default> +<context>http, server</context> + +<para> +Директива задаёт таймаут при чтении заголовка запроса клиента. +Если по истечении этого времени клиент не передаст полностью заголовок +запроса, то ему возвращается ошибка "Request time out" (408). +</para> + +</directive> + + +<directive name="client_max_body_size"> +<syntax>client_max_body_size <value>размер</value></syntax> +<default>client_max_body_size 1m</default> +<context>http, server, location</context> + +<para> +Директива задаёт максимально допустимый размер тела запроса клиента, +указываемый в строке "Content-Length" в заголовке запроса. +Если размер больше заданного, то клиенту возвращается ошибка +"Request Entity Too Large" (413). Следует иметь в виду, что +<link url="http://sysoev.ru/web/upload.html">браузеры не умеют +корректно показывать эту ошибку</link>. +</para> + +</directive> + + +<directive name="default_type"> +<syntax>default_type <value>MIME-тип</value></syntax> +<default>default_type text/plain</default> +<context>http, server, location</context> + +<para> +Директива задаёт MIME-тип ответов по умолчанию. +</para> + +</directive> + + +<directive name="directio"> +<syntax>directio <value>[размер|off]</value></syntax> +<default>directio off</default> +<context>http, server, location</context> + +<para> +Директива (0.7.7) разрешает использовать флаги +O_DIRECT (FreeBSD, Linux), F_NOCACHE (Mac OS X) или функцию directio() (Solaris) +при чтении файлов, размер которых больше либо равен указанному. +Директива автоматически запрещает (0.7.15) использование +<link id="sendfile">sendfile'а</link> для данного запроса. +Рекомендуется использовать для больших файлов: +<example> +directio 4m; +</example> +или при использовании <link id="aio">aio</link> в Linux. +</para> + +</directive> + + +<directive name="directio_alignment"> +<syntax>directio_alignment <value>размер</value></syntax> +<default>directio_alignment 512</default> +<context>http, server, location</context> + +<para> +Директива (0.8.11) устанавливает выравнивание для +<link id="directio">directio</link>. +В большинстве случае достаточно выравнивания 512 байт, однако +при использовании XFS под Linux его нужно увеличить до 4K. +</para> + +</directive> + + +<directive name="error_page"> +<syntax>error_page <value>код [код ...] [=|=ответ] uri</value> +</syntax> +<default>нет</default> +<context>http, server, location, if в location</context> + +<para> +Директива задаёт URI, который будет показываться для указанных ошибок. +Директивы наследуются с предыдущего уровня при условии, что на данном +уровне не описаны свои директивы error_page. +В URI можно использовать переменные. +</para> + +<para> +Пример использования: +<example> +error_page 404 /404.html; +error_page 502 503 504 /50x.html; +error_page 403 http://example.com/forbidden.html; +</example> +</para> + +<para> +Кроме того, можно поменять код ответа на другой, например: +<example> +error_page 404 =200 /empty.gif; +</example> +</para> + +<para> +Если ошибочный ответ обрабатывается проксированным сервером или +FastCGI-сервером и этот сервер может вернуть разные коды ответов, +например, 200, 302, 401 или 404, то можно выдавать возвращаемый код: +<example> +error_page 404 = /404.php; +</example> +</para> + +<para> +Если при перенаправлении не нужно менять URI, то можно перенаправить +обработку ошибки в именованный location: +<example> +location / { + error_page 404 = @fallback; +} + +location @fallback { + proxy_pass http://backend; +} +</example> +</para> + +</directive> + + +<directive name="if_modified_since"> +<syntax>if_modified_since <value>[off|exact|before]</value></syntax> +<default>if_modified_since exact</default> +<context>http, server, location</context> + +<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> + +</list> +</para> + +</directive> + + +<directive name="internal"> +<syntax>internal</syntax> +<default>нет</default> +<context>location</context> + +<para> +Директива указывает, что данный location может использоваться только +для внутренних запросов. +Для внешних запросов будет возвращаться ошибка "Not found" (404). +Внутренними запросами являются +<list type="bullet"> + +<listitem> +запросы, перенаправленные директивой error_page; +</listitem> + +<listitem> +подзапросы, формируемые командой include virtual модуля ngx_http_ssi_module; +</listitem> + +<listitem> +запросы, изменённые директивой rewrite модуля ngx_http_rewrite_module. +</listitem> + +</list> +</para> + +<para> +Пример использования: +<example> +error_page 404 /404.html; + +location /404.html { + internal; +} +</example> +</para> + +</directive> + + +<directive name="keepalive_requests"> +<syntax>keepalive_requests <value>число</value></syntax> +<default>keepalive_requests 100</default> +<context>http, server, location</context> + +<para> +Директива (0.8.0) задаёт максимальное число запросов, которые можно +сделать по одному keep-alive соединению. +</para> + +</directive> + + +<directive name="keepalive_timeout"> +<syntax>keepalive_timeout <value>время [время]</value></syntax> +<default>keepalive_timeout 75</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут, в течение которого keep-alive соединение +с клиентом не будет закрыто со стороны сервера. +Второй параметр задаёт значение в строке "Keep-Alive: timeout=время" +в заголовке ответа. Параметры могут отличаться друг от друга. +Строку "Keep-Alive: timeout=время" понимают Mozilla и Konqueror. +MSIE сам закрывает keep-alive соединение примерно через 60 секунд. +</para> + +</directive> + + +<directive name="large_client_header_buffers"> +<syntax>large_client_header_buffers <value>число размер</value> +</syntax> +<default>large_client_header_buffers 4 4k/8k</default> +<context>http, server</context> + +<para> +Директива задаёт максимальное число и размер буферов для чтения +большого заголовка запроса клиента. +Строка запроса должна быть не больше размера одного буфера, иначе клиенту +возвращается ошибка "Request URI too large" (414). +Длинная строка заголовка запроса также должна быть не больше размера одного +буфера, иначе клиенту возвращается ошибка "Bad request" (400). +Буферы выделяются только по мере необходимости. +По умолчанию размер одного буфера равен размеру страницы, в зависимости +от платформы это или 4K, или 8K. +Если по окончании обработки запроса соединение переходит в состояние +keep-alive, то эти буферы освобождаются. +</para> + +</directive> + + +<directive name="limit_except"> +<syntax>limit_except <value>методы</value> { ... }</syntax> +<default>нет</default> +<context>location</context> + +<para> +Директива ограничивает HTTP-методы, доступные внутри location. +Метод GET также включает в себя метод HEAD. +Для ограничения могут использоваться директивы модулей <link doc="ngx_http_access_module.xml">ngx_http_access_module</link> +и <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>: +<example> +limit_except GET { + allow 192.168.1.0/32; + deny all; +} +</example> +Обратите внимание, что данное ограничение будет выполняться для всех методов, +<value>кроме</value> методов GET и HEAD. +</para> + +</directive> + + +<directive name="limit_rate"> + +<syntax>limit_rate <value>скорость</value></syntax> +<default>нет</default> +<context>http, server, location, if в location</context> + +<para> +Директива задаёт скорость передачи ответа клиенту. +Скорость задаётся в байтах в секунду. + +Ограничение работает только для одного соединения, то есть, +если клиент откроет 2 соединения, то суммарная скорость будет в 2 раза +выше ограниченной. +</para> + +<para> +Если необходимо ограничить скорость для части клиентов на уровне сервера, +то директива limit_rate для этого не подходит. Вместо этого следует +задать нужную скорость переменной $limit_rate: +<example> +server { + + if ($slow) { + set $limit_rate 4k; + } + + ... +} +</example> +</para> + +</directive> + + +<directive name="limit_rate_after"> +<syntax>limit_rate_after <value>размер</value></syntax> +<default>нет</default> +<context>http, server, location, if в location</context> + +<para> +Директива (0.8.0) задаёт объём данных, после передачи которого +начинает ограничиваться скорость передачи ответа клиенту, например: +<example> +location /flv/ { + flv; + limit_rate_after 500k; + limit_rate 50k; +} +</example> +</para> + +</directive> + + +<directive name="listen"> +<syntax>listen <value>адрес:порт + [default|default_server| + [backlog=число | + rcvbuf=размер | + sndbuf=размер | + accept_filter=фильтр | + deferred | + bind | + ipv6only=[on|off] | + ssl]] +</value></syntax> +<default>listen *:80 | *:8000</default> +<context>server</context> + +<para> +Директива задаёт адрес и порт, на которых сервер принимает запросы. +Можно указать только адрес или только порт, кроме того, адрес может +быть именем сервера, например: +<example> +listen 127.0.0.1:8000; +listen 127.0.0.1; +listen 8000; +listen *:8000; +listen localhost:8000; +</example> +адреса IPv6 (0.7.36) задаются в квадратных скобках: +<example> +listen [::]:8000; +listen [fe80::1]; +</example> +</para> + +<para> +Если указан только адрес, то используется порт 80. +</para> + +<para> +Если директива не указана, то используется порт *:80, если nginx работает +с правами пользователя root, или порт *:8000. +</para> + +<para> +Если у директивы есть параметр default, то сервер, в котором описана +эта директива, будет сервером по умолчанию для указанной пары адрес:порт. +Если же директив с параметром default нет, то сервером по умолчанию +будет первый сервер, в котором описана пара адрес:порт. +Начиная с версии 0.8.21, можно использовать параметр default_server. +</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 +для слушающего сокета. +Установить этот параметр можно только один раз на старте. +</listitem> + +<listitem> +ssl — параметр (0.7.14) не имеет отношения к системным вызовам +listen(2) и bind(2), а позволяет указать, что все соединения, +принимаемые на этом порту, должны работать в режиме SSL. +Это позволяет задать компактную конфигурацию для сервера, +работающего сразу в двух режимах — HTTP и HTTPS. +<example> +listen 80; +listen 443 default ssl; +</example> +</listitem> + +</list> +</para> + +<para> +Пример использования параметров: +<example> +listen 127.0.0.1 default accept_filter=dataready backlog=1024; +</example> +</para> + +</directive> + + +<directive name="location"> +<syntax>location [<value>=|~|~*|^~|@</value>] <value>/uri/</value> +{ ... }</syntax> +<default>нет</default> +<context>server</context> + +<para> +Директива устанавливает конфигурацию в зависимости от URI запроса. +location можно задать обычной строкой или регулярным выражением. +Регулярные выражения задаются префиксом "~*" — без учёта регистра +символов, и "~" — с учётом. +Для определения соответствия location'а и запроса +сначала проверяются location'ы, заданные обычными строками. +Среди них ищется максимальное совпадение. +Затем проверяются регулярные выражения. +В отличие от обычных строк, они не сортируются, а проверяются в порядке +их следования в конфигурационном файле. +Проверка регулярных выражений прекращается после первого же совпадения. +Если совпадение с регулярным выражением не найдено, то используется +конфигурация максимально совпавшего location'а. +</para> + +<para> +Для операционных систем, не чувствительных к регистру символов, таких +как Mac OS X и Cygwin, проверка обычных строк делается без учёта +регистра (0.7.7). +Однако, сравнение ограничено только однобайтными locale'ями. +</para> + +<para> +Регулярное выражение может содержать выделения (0.7.40), которые +могут затем использоваться в других директивах. +</para> + +<para> +Если нужно запретить проверку регулярных выражений после проверки +обычных строк, то это можно сделать с помощью префикса "^~". +Если у максимально совпавшего location'а есть этот префикс, то +регулярные выражения не проверяются. +</para> + +<para> +Кроме того, с помощью префикса "=" можно задать точное совпадение +URI и location. При совпадении поиск сразу же прекращается, так как +дальше искать не имеет смысла. Например, если запрос "/" очень частый, +то указав "location = /", можно ускорить обработку этого запроса, +так как поиск location прекратится после первого же сравнения. +</para> + +<para> +В версиях с 0.7.1 по 0.8.41, если запрос точно совпал с обычным location'ом +без префиксов "=" и "^~", то поиск тоже сразу же прекращается и +регулярные выражения также не проверяются. +</para> + +<para> +Проиллюстрируем вышесказанное примером: +<example> +location = / { + [ конфигурация A ] +} + +location / { + [ конфигурация B ] +} + +location ^~ /images/ { + [ конфигурация C ] +} + +location ~* \.(gif|jpg|jpeg)$ { + [ конфигурация D ] +} +</example> +Для запроса "/" будет выбрана конфигурация A, +для запроса "/documents/document.html" — конфигурация B, +для запроса "/images/1.gif" — конфигурация C, +для запроса "/documents/1.jpg" — конфигурация D. +</para> + +<para> +Префикс "@" задаёт именованный location. Такой location не используется +при обычной обработке запросов, а предназначен только для перенаправления +в него запросов. +</para> + +</directive> + + +<directive name="log_not_found"> +<syntax>log_not_found <value>[on|off]</value></syntax> +<default>log_not_found on</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает записывать в error_log +ошибки о том, что файл не найден. +</para> + +</directive> + + +<directive name="log_subrequest"> +<syntax>log_subrequest <value>[on|off]</value></syntax> +<default>log_subrequest off</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает записывать в <link doc="ngx_http_log_module.xml#access_log">access_log</link> +подзапросы. +</para> + +</directive> + + +<directive name="merge_slashes"> +<syntax>merge_slashes <value>[on|off]</value></syntax> +<default>merge_slashes on</default> +<context>http, server</context> + +<para> +Директива разрешает или запрещает объединять в URI два и более слэшей в один. +</para> + +<para> +Необходимо иметь ввиду, что это объединение необходимо для корректной +проверки location'ов и регулярных выражений. +Например, запрос "//scripts/one.php" не попадает в +<example> +location /scripts/ { + ... +} +</example> +и может быть обслужен как статический файл, +поэтому он приводится в "/scripts/one.php". +</para> + +<para> +Выключение объединения может понадобиться, если в URI используются имена, +закодированные методом base64, который использует символ "/". +Но по соображениям безопасности лучше избегать выключения объединения. +</para> + +<para> +Если директива указана на уровне server в сервере по умолчанию, +то её значение распространяется на все виртуальные сервера, слушающие +на том же адресе и порту. +</para> + +</directive> + + +<directive name="msie_padding"> +<syntax>msie_padding <value>[on|off]</value></syntax> +<default>msie_padding on</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает добавлять в ответы для MSIE +со статусом больше 400 +комментарий для увеличения размера ответа до 512 байт. +</para> + +</directive> + + +<directive name="msie_refresh"> +<syntax>msie_refresh <value>[on|off]</value></syntax> +<default>msie_refresh off</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает выдавать для MSIE refresh'ы вместо +редиректов. +</para> + +</directive> + + +<directive name="open_file_cache"> +<syntax>open_file_cache <value>max=N [inactive=время]|off</value> +</syntax> +<default>open_file_cache off</default> +<context>http, server, location</context> + +<para> +Директива задаёт кэш, в котором могут хранится +<list type="bullet"> + +<listitem> +дескрипторы открытых файлов, информация об их размерах и времени модификации; +</listitem> + +<listitem> +информация о существовании каталогов; +</listitem> + +<listitem> +информация об ошибках поиска файла — нет файла, нет прав на чтение +и тому подобное. Кэширование ошибок нужно разрешить директивой +<link id="open_file_cache_errors"/>. +</listitem> + +</list> +</para> + +<para> +Параметры директивы: +<list type="bullet"> + +<listitem> +max — задаёт максимальное число элементов в кэше; +при переполнении кэша удаляются наиболее давно не используемые элементы (LRU); +</listitem> + +<listitem> +inactive — задаёт время, после которого элемент кэша удаляется, +если к нему не было обращений в течение этого времени; +по умолчанию 60 секунд; +</listitem> + +<listitem> +off — запрещает кэш. +</listitem> + +</list> +</para> + +<para> +Пример использования: +<example> +open_file_cache max=1000 inactive=20s; +open_file_cache_valid 30s; +open_file_cache_min_uses 2; +open_file_cache_errors on; +</example> +</para> + +</directive> + + +<directive name="open_file_cache_errors"> +<syntax>open_file_cache_errors <value>on|off</value></syntax> +<default>open_file_cache_errors off</default> +<context>http, server, location</context> + +<para> +Директива определяет, кэшировать или нет ошибки поиска файлов в +<link id="open_file_cache"/>. +</para> + +</directive> + + +<directive name="open_file_cache_min_uses"> +<syntax>open_file_cache_min_uses <value>число</value></syntax> +<default>open_file_cache_min_uses 1</default> +<context>http, server, location</context> + +<para> +Директива определяет минимальное число использований файла в течение +времени, заданного параметром inactive в директиве +<link id="open_file_cache"/>, после которого дескриптор файла +будет оставаться открытым в кэше. +</para> + +</directive> + + +<directive name="open_file_cache_valid"> +<syntax>open_file_cache_valid <value>время</value></syntax> +<default>open_file_cache_valid 60</default> +<context>http, server, location</context> + +<para> +Директива определяет, через какое время нужно проверять актуальность +информации об элементе в <link id="open_file_cache"/>. + +</para> + +</directive> + + +<directive name="optimize_server_names"> +<syntax>optimize_server_names <value>[on|off]</value></syntax> +<default>optimize_server_names on</default> +<context>http, server</context> + +<para> +Устаревшая директива. +</para> + +<para> +Директива разрешает или запрещает оптимизировать проверку имени хоста +в name-based виртуальных серверах. +Проверка в частности влияет на имя хоста, используемого в редиректах. +Если оптимизация разрешена и все name-based сервера, слушающие на одной +паре адрес:порт, имеют одинаковую конфигурацию, то во время исполнения +запроса имена не проверяются и в редиректах используется первое имя сервера. +Если в редиректе нужно использовать имя хоста, переданное клиентом, +то оптимизацию нужно выключить. +</para> + +</directive> + + +<directive name="port_in_redirect"> +<syntax>port_in_redirect <value>[on|off]</value></syntax> +<default>port_in_redirect on</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает указывать порт в редиректах, +выдаваемых nginx'ом. +</para> + +</directive> + + +<directive name="read_ahead"> +<syntax>read_ahead <value>размер</value></syntax> +<default>read_ahead 0</default> +<context>http, server, location</context> + +<para> +Директива задаёт ядру размер предчтения при работе с файлами. +Под Линуксом используется системный вызов +<example> +posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL); +</example> +поэтому размер игнорируется. +</para> + +<para> +Под FreeBSD используется fcntl(O_READAHEAD, размер), появившийся +во FreeBSD-9 CURRENT. Для FreeBSD 7 нужно установить +<link url="http://sysoev.ru/freebsd/patch.readahead.txt">патч</link>. +</para> + +</directive> + + +<directive name="recursive_error_pages"> +<syntax>recursive_error_pages <value>[on|off]</value></syntax> +<default>recursive_error_pages off</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает делать несколько перенаправлений через +директиву <link id="error_page"/>. +</para> + +</directive> + + +<directive name="reset_timedout_connection"> +<syntax>reset_timedout_connection <value>[on|off]</value></syntax> +<default>reset_timedout_connection off</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает сбрасывать соединение по таймауту. +Сброс делается следующим образом — перед закрытием сокета для него +ставится опция SO_LINGER с таймаутом 0. После чего при закрытии сокета +клиенту отсылается пакет RST, а всё память, связанная с этим сокетом, +освобождается. Это позволяет избежать длительного нахождения уже закрытого +сокета в состоянии FIN_WAIT1 с заполненными буферами. +</para> + +<para> +Необходимо отметить, что соединения, находящиеся в состоянии keepalive, +по истечении таймаута закрываются обычным образом. +</para> + +</directive> + + +<directive name="resolver"> +<syntax>resolver <value>адрес</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт адрес name-сервера, например: +<example> + resolver 127.0.0.1; +</example> +</para> + +</directive> + + +<directive name="resolver_timeout"> +<syntax>resolver_timeout <value>время</value></syntax> +<default>resolver_timeout 30s</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут для определения имени, например: +<example> + resolver_timeout 5s; +</example> +</para> + +</directive> + + +<directive name="root"> +<syntax>root <value>путь</value></syntax> +<default>root html</default> +<context>http, server, location, if в location</context> + +<para> +Директива задаёт корневой каталог для запросов. +Например, при такой конфигурации +<example> + location /i/ { + root /data/w3; + } +</example> +на запрос "/i/top.gif" будет отдан файл "/data/w3/i/top.gif". +</para> + +<para> +В значении пути можно использовать переменные. +</para> + +<para> +Путь к файлу формируется как простое добавление URI к значению директивы root. +Если же необходима модификация URI, то нужно воспользоваться директивой +<link id="alias"/>. +</para> + +</directive> + + +<directive name="satisfy"> +<syntax>satisfy <value>all|any</value></syntax> +<default>satisfy all</default> +<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>: +<example> +location / { + satisfy any; + + allow 192.168.1.0/32; + deny all; + + auth_basic "closed site"; + auth_basic_user_file conf/htpasswd; +} +</example> +</para> + +</directive> + + +<directive name="satisfy_any"> +<syntax>satisfy_any <value>on|off</value></syntax> +<default>satisfy_any off</default> +<context>location</context> + +<para> +Директива переименована в директиву <link id="satisfy"/>. +</para> + +</directive> + + +<directive name="send_timeout"> +<syntax>send_timeout <value>время</value></syntax> +<default>send_timeout 60</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут при передаче ответа клиенту. +Таймаут устанавливается не на всю передачу ответа, +а только между двумя операциями записями. +Если по истечении этого времени клиент ничего не примет, +то nginx закрывает соединение. +</para> + +</directive> + + +<directive name="sendfile"> +<syntax>sendfile <value>[on|off]</value></syntax> +<default>sendfile off</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает использовать sendfile(). +</para> + +</directive> + + +<directive name="server"> +<syntax>server { ... }</syntax> +<default>нет</default> +<context>http</context> + +<para> +Директива задаёт конфигурацию для виртуального сервера. +Чёткого разделения виртуальных серверов ip-based (на основании ip-адреса) +и name-based (на основании имени, передаваемого в строке "Host" +заголовка запроса), нет. +Вместо этого директивами <link id="listen"/> описываются все адреса +и порты, на которых нужно принимать соединения для этого сервера, +и в директиве <link id="server_name"/> указываются все имена серверов. +Пример конфигурации описан в <link doc="../virtual_hosts.xml"> +настройке виртуальных серверов</link>. +</para> + +</directive> + + +<directive name="server_name"> +<syntax>server_name <value>имя [...]</value></syntax> +<default>server_name hostname</default> +<context>server</context> + +<para> +Директива задаёт имена виртуального сервера, например: +<example> +server { + server_name example.com www.example.com; +} +</example> +</para> + +<para> +Первое имя становится основным именем сервера. +По умолчанию используется имя машины (hostname). +В именах серверов можно использовать "*" для замены первой или последней +части имени: +<example> +server { + server_name example.com *.example.com www.example.*; +} +</example> +</para> + +<para> +Два первых вышеприведённых имени можно объединить в одно: +<example> +server { + server_name .example.com; +} +</example> +</para> + +<para> +Кроме того, в качестве имени сервера можно использовать регулярное +выражение, указав перед ним "~": +<example> +server { + server_name www.example.com ~^www\d+\.example\.com$; +} +</example> +</para> + +<para> +Регулярное выражение может содержать выделения (0.7.40), которые +могут затем использоваться в других директивах: +<example> +server { + server_name ~^(www\.)?(.+)$; + + location / { + root /sites/$2; + } +} + +server { + server_name _; + + location / { + root /sites/default; + } +} +</example> +</para> + +<para> +Начиная с 0.8.25, именованные выделения в регулярном выражении создают +переменные, которые могут затем использоваться в других директивах: +<example> +server { + server_name ~^(www\.)?(<emphasis>?<domain></emphasis>.+)$; + + location / { + root /sites/<emphasis>$domain</emphasis>; + } +} + +server { + server_name _; + + location / { + root /sites/default; + } +} +</example> +</para> + +<para> +Начиная с 0.7.11, можно использовать пустое имя "": +<example> +server { + server_name www.example.com ""; +} +</example> +что позволяет обрабатывать запросы без строки "Host" в заголовке запроса +в этом сервере, а не в сервере по умолчанию для данной пары адрес:порт. +</para> + +<para> +Порядок проверки имён следующий: +<list type="bullet"> + +<listitem> +полные имена, +</listitem> + +<listitem> +имена с маской в начале имени — *.example.com, +</listitem> + +<listitem> +имена с маской в конце имени — mail.*, +</listitem> + +<listitem> +регулярные выражения. +</listitem> + +</list> +</para> + +</directive> + + +<directive name="server_name_in_redirect"> +<syntax>server_name_in_redirect <value>[on|off]</value></syntax> +<default>server_name_in_redirect on</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает использовать в редиректах, выдаваемых +nginx'ом, основное имя сервера, задаваемое директивой +<link id="server_name"/>. +Если использование основного имени запрещено, то используется имя, +указанного в строке "Host" в заголовке запроса. +Если же этой строки нет, то используется IP-адрес сервера. +</para> + +</directive> + + +<directive name="server_names_hash_max_size"> +<syntax>server_names_hash_max_size <value>число</value></syntax> +<default>server_names_hash_max_size 512</default> +<context>http</context> + +<para> +Директива задаёт максимальный размер хэш-таблиц имён серверов. +Подробнее смотри в <link doc="../hash.xml">описании +настройки хэшей</link>. +</para> + +</directive> + + +<directive name="server_names_hash_bucket_size"> +<syntax>server_names_hash_bucket_size <value>число</value></syntax> +<default>server_names_hash_bucket_size 32/64/128</default> +<context>http</context> + +<para> +Директива задаёт размер корзины в хэш-таблицах имён серверов. +Значение по умолчанию зависит от размера строки кэша процессора. +Подробнее смотри в <link doc="../hash.xml">описании +настройки хэшей</link>. +</para> + +</directive> + + +<directive name="server_tokens"> +<syntax>server_tokens <value>[on|off]</value></syntax> +<default>server_tokens on</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает выдавать версию nginx'а +в сообщениях об ошибках и в строке заголовка ответа "Server". +</para> + +</directive> + + +<directive name="tcp_nodelay"> +<syntax>tcp_nodelay <value>[on|off]</value></syntax> +<default>tcp_nodelay on</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает использовать опцию TCP_NODELAY. +Опция включаются только при переходе соединения в состояние keep-alive. +</para> + +</directive> + + +<directive name="tcp_nopush"> +<syntax>tcp_nopush <value>[on|off]</value></syntax> +<default>tcp_nopush off</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает использовать опции +TCP_NOPUSH во FreeBSD или TCP_CORK в Linux. +Опции включаются только при использовании <link id="sendfile"/>. +Включение опции позволяет +<list type="bullet"> + +<listitem> +передавать заголовок ответа и начало файла в одном пакете в Linux +и во FreeBSD 4.x; +</listitem> + +<listitem> +передавать файл в полных пакетах. +</listitem> + +</list> +</para> + +</directive> + + +<directive name="try_files"> +<syntax>try_files <value>файл [файл ...] (uri|=код)</value></syntax> +<default>нет</default> +<context>location</context> + +<para> +Директива проверяет существование файлов в заданном порядке +и использует для обработки запроса первый найденный файл, причём +обработка делается в контексте этого же location'а. +С помощью слэша в конце имени можно задать проверку существования +каталога, например, так — "$uri/". +В случае, если ни один файл не найден, то делается внутренний редирект +на последний параметр. +Последний параметр может быть кодом (0.7.51): +<example> +location / { + try_files $uri $uri/index.html $uri.html =404; +} +</example> +</para> + +<para> +Пример использования при проксировании Mongrel: +<example> +location / { + try_files /system/maintenance.html + $uri $uri/index.html $uri.html + @mongrel; +} + +location @mongrel { + proxy_pass http://mongrel; +} +</example> +</para> + +<para> +Пример использования вместе с Drupal/FastCGI: +<example> +location / { + try_files $uri $uri/ @drupal; +} + +location ~ \.php$ { + try_files $uri @drupal; + + fastcgi_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; + fastcgi_param SCRIPT_NAME $fastcgi_script_name; + fastcgi_param QUERY_STRING $args; + + ... прочие fastcgi_param +} + +location @drupal { + fastcgi_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to/index.php; + fastcgi_param SCRIPT_NAME /index.php; + fastcgi_param QUERY_STRING q=$uri&$args; + + ... прочие fastcgi_param +} +</example> +В этом примере директива try_files +<example> +location / { + try_files $uri $uri/ @drupal; +} +</example> +аналогична директивам +<example> +location / { + error_page 404 = @drupal; + log_not_found off; +} +</example> +А здесь +<example> +location ~ \.php$ { + try_files $uri @drupal; + + fastcgi_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; + + ... +} +</example> +try_files тестирует существование PHP-файла, +прежде чем передать запрос FastCGI-серверу. +</para> + +<para> +Пример использования вместе с Wordpress и Joomla: +<example> +location / { + try_files $uri $uri/ @wordpress; +} + +location ~ \.php$ { + try_files $uri @wordpress; + + fastcgi_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; + ... прочие fastcgi_param +} + +location @wordpress { + fastcgi_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to/index.php; + ... прочие fastcgi_param +} +</example> +</para> + +</directive> + + +<directive name="types"> +<syntax>types <value>{ ... }</value></syntax> +<default>see below</default> +<context>http, server, location</context> + +<para> +Директива задаёт соответствие расширения и MIME-типов ответов. +Одному MIME-типу может соответствовать несколько расширений. +По умолчанию используется такие соответствия: +<example> +types { + text/html html; + image/gif gif; + image/jpeg jpg; +} +</example> +</para> + +<para> +Достаточно полная таблица соответствий входит в дистрибутив +и находится в файле conf/mime.types. +</para> + +<para> +Для того, чтобы для определённого location'а для всех ответов выдавался +MIME-тип "application/octet-stream", можно использовать следующее: +<example> +location /download/ { + types { } + default_type application/octet-stream; +} +</example> +</para> + +</directive> + + +<directive name="underscores_in_headers"> +<syntax>underscores_in_headers <value>[on|off]</value></syntax> +<default>underscores_in_headers off</default> +<context>http, server</context> + +<para> +Директива разрешает или запрещает использование символов подчёркивания +в строках заголовка запроса клиента. +</para> + +</directive> + +</section> + + +<section name="Встроенные переменные" id="variables"> + +<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'ах, обрабатываемых директивами +<link doc="ngx_http_proxy_module.xml#proxy_pass">proxy_pass</link> +и <link doc="ngx_http_fastcgi_module.xml#fastcgi_pass">fastcgi_pass</link>. +</listitem> + +<listitem> +$request_body_file, эта переменная равна имени временного файла, в котором +хранится тело запроса. +По завершению работы файл необходимо удалить. +Для того, чтобы тело запроса клиента всегда записывалось в файл, нужно +указать <link doc="ngx_http_core_module.xml#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> + +</list> +</para> + +</section> + +</module>