Mercurial > hg > nginx-site
view xml/ru/docs/http/ngx_http_core_module.xml @ 120:da8bd4d2290f
registered trade mark sign added to DTD
author | Sergey Budnevitch <sb@waeme.net> |
---|---|
date | Thu, 20 Oct 2011 15:31:16 +0000 |
parents | 72524ae53106 |
children | bfe3eff81d04 |
line wrap: on
line source
<?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><value>[on|off|sendfile]</value></syntax> <default>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"/>. </para> <para> В Linux AIO можно использовать, только начиная с версии ядра 2.6.22, и, кроме того, ещё необходимо дополнительно включать <link id="directio"/>, иначе чтение будет блокирующимся: <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><value>путь</value></syntax> <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><value>on|clean|off</value></syntax> <default>off</default> <context>http, server, location</context> <para> Директива определяет, сохранять ли всё тело запроса клиента в файл. Директиву можно использовать для отладки и при использовании переменной $request_body_file или метода <link doc="ngx_http_perl_module.xml" id="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><value>on|off</value></syntax> <default>off</default> <context>http, server, 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. </para> </directive> <directive name="client_body_temp_path"> <syntax><value>путь [ уровень1 [ уровень2 [ уровень3 ] ] ] </value></syntax> <default>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><value>время</value></syntax> <default>60</default> <context>http, server, location</context> <para> Директива задаёт таймаут при чтении тела запроса клиента. Таймаут устанавливается не на всю передачу тела запроса, а только между двумя операциями чтения. Если по истечении этого времени клиент ничего не передаст, то ему возвращается ошибка "Request time out" (408). </para> </directive> <directive name="client_header_buffer_size"> <syntax><value>размер</value></syntax> <default>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><value>время</value></syntax> <default>60</default> <context>http, server</context> <para> Директива задаёт таймаут при чтении заголовка запроса клиента. Если по истечении этого времени клиент не передаст полностью заголовок запроса, то ему возвращается ошибка "Request time out" (408). </para> </directive> <directive name="client_max_body_size"> <syntax><value>размер</value></syntax> <default>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><value>MIME-тип</value></syntax> <default>text/plain</default> <context>http, server, location</context> <para> Директива задаёт MIME-тип ответов по умолчанию. </para> </directive> <directive name="directio"> <syntax><value>[размер|off]</value></syntax> <default>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"/> в Linux. </para> </directive> <directive name="directio_alignment"> <syntax><value>размер</value></syntax> <default>512</default> <context>http, server, location</context> <para> Директива (0.8.11) устанавливает выравнивание для <link id="directio"/>. В большинстве случае достаточно выравнивания 512 байт, однако при использовании XFS под Linux его нужно увеличить до 4K. </para> </directive> <directive name="error_page"> <syntax><value>код [код ...] [=|=ответ] uri</value> </syntax> <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><value>[off|exact|before]</value></syntax> <default>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/> <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><value>число</value></syntax> <default>100</default> <context>http, server, location</context> <para> Директива (0.8.0) задаёт максимальное число запросов, которые можно сделать по одному keep-alive соединению. </para> </directive> <directive name="keepalive_timeout"> <syntax><value>время [время]</value></syntax> <default>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><value>число размер</value> </syntax> <default>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 block="yes"><value>методы</value></syntax> <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><value>скорость</value></syntax> <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><value>размер</value></syntax> <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><value>адрес:порт [default|default_server| [backlog=число | rcvbuf=размер | sndbuf=размер | accept_filter=фильтр | deferred | bind | ipv6only=[on|off] | ssl]] </value></syntax> <default>*: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 block="yes">[<value>=|~|~*|^~|@</value>] <value>/uri/</value> </syntax> <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><value>[on|off]</value></syntax> <default>on</default> <context>http, server, location</context> <para> Директива разрешает или запрещает записывать в error_log ошибки о том, что файл не найден. </para> </directive> <directive name="log_subrequest"> <syntax><value>[on|off]</value></syntax> <default>off</default> <context>http, server, location</context> <para> Директива разрешает или запрещает записывать в <link doc="ngx_http_log_module.xml" id="access_log"/> подзапросы. </para> </directive> <directive name="merge_slashes"> <syntax><value>[on|off]</value></syntax> <default>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><value>[on|off]</value></syntax> <default>on</default> <context>http, server, location</context> <para> Директива разрешает или запрещает добавлять в ответы для MSIE со статусом больше 400 комментарий для увеличения размера ответа до 512 байт. </para> </directive> <directive name="msie_refresh"> <syntax><value>[on|off]</value></syntax> <default>off</default> <context>http, server, location</context> <para> Директива разрешает или запрещает выдавать для MSIE refresh'ы вместо редиректов. </para> </directive> <directive name="open_file_cache"> <syntax><value>max=N [inactive=время]|off</value> </syntax> <default>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><value>on|off</value></syntax> <default>off</default> <context>http, server, 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> <para> Директива определяет минимальное число использований файла в течение времени, заданного параметром inactive в директиве <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> <para> Директива определяет, через какое время нужно проверять актуальность информации об элементе в <link id="open_file_cache"/>. </para> </directive> <directive name="optimize_server_names"> <syntax><value>[on|off]</value></syntax> <default>on</default> <context>http, server</context> <para> Устаревшая директива. </para> <para> Директива разрешает или запрещает оптимизировать проверку имени хоста в name-based виртуальных серверах. Проверка в частности влияет на имя хоста, используемого в редиректах. Если оптимизация разрешена и все name-based сервера, слушающие на одной паре адрес:порт, имеют одинаковую конфигурацию, то во время исполнения запроса имена не проверяются и в редиректах используется первое имя сервера. Если в редиректе нужно использовать имя хоста, переданное клиентом, то оптимизацию нужно выключить. </para> </directive> <directive name="port_in_redirect"> <syntax><value>[on|off]</value></syntax> <default>on</default> <context>http, server, location</context> <para> Директива разрешает или запрещает указывать порт в редиректах, выдаваемых nginx'ом. </para> </directive> <directive name="read_ahead"> <syntax><value>размер</value></syntax> <default>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><value>[on|off]</value></syntax> <default>off</default> <context>http, server, location</context> <para> Директива разрешает или запрещает делать несколько перенаправлений через директиву <link id="error_page"/>. </para> </directive> <directive name="reset_timedout_connection"> <syntax><value>[on|off]</value></syntax> <default>off</default> <context>http, server, location</context> <para> Директива разрешает или запрещает сбрасывать соединение по таймауту. Сброс делается следующим образом — перед закрытием сокета для него ставится опция SO_LINGER с таймаутом 0. После чего при закрытии сокета клиенту отсылается пакет RST, а всё память, связанная с этим сокетом, освобождается. Это позволяет избежать длительного нахождения уже закрытого сокета в состоянии FIN_WAIT1 с заполненными буферами. </para> <para> Необходимо отметить, что соединения, находящиеся в состоянии keepalive, по истечении таймаута закрываются обычным образом. </para> </directive> <directive name="resolver"> <syntax><value>адрес</value></syntax> <default/> <context>http, server, location</context> <para> Директива задаёт адрес name-сервера, например: <example> resolver 127.0.0.1; </example> </para> </directive> <directive name="resolver_timeout"> <syntax><value>время</value></syntax> <default>30s</default> <context>http, server, location</context> <para> Директива задаёт таймаут для определения имени, например: <example> resolver_timeout 5s; </example> </para> </directive> <directive name="root"> <syntax><value>путь</value></syntax> <default>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><value>all|any</value></syntax> <default>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><value>on|off</value></syntax> <default>off</default> <context>location</context> <para> Директива переименована в директиву <link id="satisfy"/>. </para> </directive> <directive name="send_timeout"> <syntax><value>время</value></syntax> <default>60</default> <context>http, server, location</context> <para> Директива задаёт таймаут при передаче ответа клиенту. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями записями. Если по истечении этого времени клиент ничего не примет, то nginx закрывает соединение. </para> </directive> <directive name="sendfile"> <syntax><value>[on|off]</value></syntax> <default>off</default> <context>http, server, location</context> <para> Директива разрешает или запрещает использовать sendfile(). </para> </directive> <directive name="server"> <syntax block="yes"/> <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><value>имя [...]</value></syntax> <default>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><value>[on|off]</value></syntax> <default>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><value>число</value></syntax> <default>512</default> <context>http</context> <para> Директива задаёт максимальный размер хэш-таблиц имён серверов. Подробнее смотри в <link doc="../hash.xml">описании настройки хэшей</link>. </para> </directive> <directive name="server_names_hash_bucket_size"> <syntax><value>число</value></syntax> <default>32/64/128</default> <context>http</context> <para> Директива задаёт размер корзины в хэш-таблицах имён серверов. Значение по умолчанию зависит от размера строки кэша процессора. Подробнее смотри в <link doc="../hash.xml">описании настройки хэшей</link>. </para> </directive> <directive name="server_tokens"> <syntax><value>[on|off]</value></syntax> <default>on</default> <context>http, server, location</context> <para> Директива разрешает или запрещает выдавать версию nginx'а в сообщениях об ошибках и в строке заголовка ответа "Server". </para> </directive> <directive name="tcp_nodelay"> <syntax><value>[on|off]</value></syntax> <default>on</default> <context>http, server, location</context> <para> Директива разрешает или запрещает использовать опцию TCP_NODELAY. Опция включаются только при переходе соединения в состояние keep-alive. </para> </directive> <directive name="tcp_nopush"> <syntax><value>[on|off]</value></syntax> <default>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><value>файл [файл ...] (uri|=код)</value></syntax> <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 block="yes"/> <default> text/html html; image/gif gif; image/jpeg jpg; </default> <context>http, server, location</context> <para> Директива задаёт соответствие расширения и MIME-типов ответов. Одному MIME-типу может соответствовать несколько расширений. </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><value>[on|off]</value></syntax> <default>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" 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> </list> </para> </section> </module>