Mercurial > hg > nginx-site
changeset 382:b838f6e9192e
Revision.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Tue, 31 Jan 2012 16:29:31 +0000 |
parents | 8ad9df891e23 |
children | a73fa21add8a |
files | xml/ru/docs/http/ngx_http_rewrite_module.xml |
diffstat | 1 files changed, 175 insertions(+), 143 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/ru/docs/http/ngx_http_rewrite_module.xml +++ b/xml/ru/docs/http/ngx_http_rewrite_module.xml @@ -2,47 +2,50 @@ <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> -<module name="Директивы модуля ngx_http_rewrite_module" +<module name="Модуль ngx_http_rewrite_module" link="/ru/docs/http/ngx_http_rewrite_module.html" lang="ru"> <section id="summary"> <para> -Модуль ngx_http_rewrite_module позволяет изменять URI с помощью -регулярных выражений, делать перенаправления и выбирать конфигурацию -в зависимости от переменных. Если директивы этого модуля описаны -на уровне сервера, то они выполняются до того, как определяется -location для запроса. Если в выбранном location тоже есть -директивы модуля ngx_http_rewrite_module, то они также выполняются. +Модуль <literal>ngx_http_rewrite_module</literal> позволяет +изменять URI с помощью регулярных выражений, делать перенаправления +и выбирать конфигурацию в зависимости от переменных. +Если директивы этого модуля описаны на уровне сервера, то они +выполняются до того, как определяется location для запроса. +Если в выбранном location тоже есть директивы модуля +<literal>ngx_http_rewrite_module</literal>, то они также выполняются. Если URI изменился в результате исполнения директив внутри location, -то снова определяется location для уже нового URI. Этот цикл может -повторяться до 10 раз, после чего nginx возвращает ошибку -"Server Internal Error" (500). +то снова определяется location для уже нового URI. +Этот цикл может повторяться до 10 раз, после чего nginx возвращает +ошибку <http-status code="500" text="Internal Server Error"/>. </para> </section> -<section name="Директивы" id="directives"> +<section id="directives" name="Директивы"> <directive name="break"> <syntax/> <default/> -<context>server, location, if</context> +<context>server</context> +<context>location</context> +<context>if</context> <para> -Директива завершает обработку текущего набора директив -ngx_http_rewrite_module. +Завершает обработку текущего набора директив модуля +<literal>ngx_http_rewrite_module</literal>. </para> <para> -Пример использования: +Пример: <example> - if ($slow) { - limit_rate 10k; - break; - } +if ($slow) { + limit_rate 10k; + break; +} </example> </para> @@ -52,13 +55,16 @@ ngx_http_rewrite_module. <directive name="if"> <syntax block="yes">(<value>условие</value>)</syntax> <default/> -<context>server, location</context> +<context>server</context> +<context>location</context> <para> -Директива if проверяет истинность условия, если оно истинно, +Проверяет истинность условия. +Если оно истинно, то выполняется указанный в фигурных скобках код и запрос обрабатывается в соответствии с заданной там же конфигурацией. -Конфигурация внутри директивы if наследуется из предыдущего уровня. +Конфигурация внутри директивы <literal>if</literal> наследуется с +предыдущего уровня. </para> <para> @@ -66,69 +72,75 @@ ngx_http_rewrite_module. <list type="bullet"> <listitem> -имя переменной; ложными значениями переменной являются пустая строка "" -или любая строка, начинающиеся на "0"; +имя переменной; ложными значениями переменной являются пустая строка “” +или любая строка, начинающаяся на “<literal>0</literal>”; </listitem> <listitem> -сравнение переменной со строкой с помощью операторов "=" и "!="; +сравнение переменной со строкой с помощью операторов +“<literal>=</literal>” и “<literal>!=</literal>”; </listitem> <listitem> -проверка переменной с помощью регулярного выражения без учёта -регистра символов — "~*" и с учётом — "~". +проверка переменной с помощью регулярного выражения с учётом +регистра символов — “<literal>~</literal>” и без него — “<literal>~*</literal>”. В регулярных выражениях можно использовать выделения, которые затем -доступны в виде переменных $1 — $9. -Также можно использовать отрицательные операторы "!~" и "!~*". -Если в регулярном выражении встречаются символы "}" или ";", то -всё выражение нужно заключить в одинарные или двойные кавычки. +доступны в виде переменных <var>$1</var> — <var>$9</var>. +Также можно использовать отрицательные операторы “<literal>!~</literal>” +и “<literal>!~*</literal>”. +Если в регулярном выражении встречаются символы “<literal>}</literal>” +или “<literal>;</literal>”, то всё выражение нужно заключить в одинарные +или двойные кавычки. </listitem> <listitem> -проверка существования файла с помощью операторов "-f" и "!-f"; +проверка существования файла с помощью операторов “<literal>-f</literal>” +и “<literal>!-f</literal>”; </listitem> <listitem> -проверка существования каталога с помощью операторов "-d" и "!-d"; +проверка существования каталога с помощью операторов “<literal>-d</literal>” +и “<literal>!-d</literal>”; </listitem> <listitem> проверка существования файла, каталога или символической ссылки -с помощью операторов "-e" и "!-e"; +с помощью операторов “<literal>-e</literal>” и “<literal>!-e</literal>”; </listitem> <listitem> -проверка исполняемости файла с помощью операторов "-x" и "!-x". +проверка исполняемости файла с помощью операторов “<literal>-x</literal>” +и “<literal>!-x</literal>”. </listitem> </list> </para> <para> -Примеры использования: +Примеры: <example> - if ($http_user_agent ~ MSIE) { - rewrite ^(.*)$ /msie/$1 break; - } +if ($http_user_agent ~ MSIE) { + rewrite ^(.*)$ /msie/$1 break; +} - if ($http_cookie ~* "id=([^;]+)(?:;|$)" ) { - set $id $1; - } +if ($http_cookie ~* "id=([^;]+)(?:;|$)") { + set $id $1; +} - if ($request_method = POST ) { - return 405; - } +if ($request_method = POST) { + return 405; +} - if ($slow) { - limit_rate 10k; - } +if ($slow) { + limit_rate 10k; +} - if ($invalid_referer) { - return 403; - } +if ($invalid_referer) { + return 403; +} </example> -Значение встроенной переменной $invalid_referer задаётся директивой +Значение встроенной переменной <var>$invalid_referer</var> задаётся директивой <link doc="ngx_http_referer_module.xml" id="valid_referers"/>. </para> @@ -138,11 +150,13 @@ ngx_http_rewrite_module. <directive name="return"> <syntax><value>код</value></syntax> <default/> -<context>server, location, if</context> +<context>server</context> +<context>location</context> +<context>if</context> <para> -Директива return завершает исполнение кода и возвращает клиенту -указанный код. Можно использовать следующие значения: 204, 400, +Завершает исполнение кода и возвращает клиенту указанный код. +Можно использовать следующие значения: 204, 400, 402 — 406, 408, 410, 411, 413, 416 и 500 — 504. Кроме того, нестандартный код 444 закрывает соединение без передачи заголовка ответа. @@ -152,93 +166,104 @@ 402 — 406, 408, 410, 411, 413, 416 и 500 — 504. <directive name="rewrite"> -<syntax><value>regex</value> <value>замена</value> <value>флаг</value></syntax> +<syntax> + <value>regex</value> + <value>замена</value> + [<value>флаг</value>]</syntax> <default/> -<context>server, location, if</context> +<context>server</context> +<context>location</context> +<context>if</context> <para> -Директива rewrite изменяет URI в соответствии с регулярным выражением -и строкой замены. Директивы выполняются в порядке их следования в -конфигурационном файле. С помощью флагов можно досрочно прекратить -исполнение директив. Если строка замены начинается с "http://", то -клиенту будет возвращено перенаправление и обработка директив также завершается. +Изменяет URI в соответствии с регулярным выражением и строкой замены. +Директивы выполняются в порядке их следования в конфигурационном файле. +С помощью флагов можно досрочно прекратить исполнение директив. +Если строка замены начинается с “<literal>http://</literal>”, то клиенту +будет возвращено перенаправление и обработка директив также завершается. </para> <para> Флаги могут быть следующими: -<list type="bullet"> +<list type="tag"> -<listitem> -last — завершает обработку текущего набора директив -ngx_http_rewrite_module, после чего ищется соответствие URI и location; -</listitem> +<tag-name><literal>last</literal></tag-name> +<tag-desc> +завершает обработку текущего набора директив модуля +<literal>ngx_http_rewrite_module</literal>, +после чего ищется соответствие URI и location; +</tag-desc> -<listitem> -break — завершает обработку текущего набора директив -ngx_http_rewrite_module; -</listitem> +<tag-name><literal>break</literal></tag-name> +<tag-desc> +завершает обработку текущего набора директив модуля +<literal>ngx_http_rewrite_module</literal>; +</tag-desc> -<listitem> -redirect — возвращает временное перенаправление с кодом 302; -используется, если заменяющая строка не начинается с "http://"; -</listitem> +<tag-name><literal>redirect</literal></tag-name> +<tag-desc> +возвращает временное перенаправление с кодом 302; +используется, если заменяющая строка не начинается с +“<literal>http://</literal>”; +</tag-desc> -<listitem> -permanent — возвращает постоянное перенаправление с кодом 301. -</listitem> +<tag-name><literal>permanent</literal></tag-name> +<tag-desc> +возвращает постоянное перенаправление с кодом 301. +</tag-desc> </list> </para> <para> -</para> - -<para> -Пример использования: +Пример: <example> - rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last; - rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last; - return 403; +rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last; +rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last; +return 403; </example> </para> <para> -Если же эти директивы поместить в location /download/, то нужно -заменить флаг last на break, иначе nginx сделает 10 циклов и вернёт -ошибку 500: +Если же эти директивы поместить в location “<literal>/download/</literal>”, +то нужно заменить флаг <literal>last</literal> на <literal>break</literal>, +иначе nginx сделает 10 циклов и вернёт ошибку 500: <example> - location /download/ { - rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; - rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra break; - return 403; - } +location /download/ { + rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; + rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra break; + return 403; +} </example> </para> <para> Если в строке замены указаны аргументы, то предыдущие аргументы запроса -добавляются после них. Можно отказаться от этого добавления, указав -в конце строки замены знак вопроса: +добавляются после них. +Можно отказаться от этого добавления, указав в конце строки замены знак вопроса: <example> - rewrite ^/users/(.*)$ /show?user=$1? last; +rewrite ^/users/(.*)$ /show?user=$1? last; </example> </para> <para> -Если в регулярном выражении встречаются символы "}" или ";", то -всё выражение нужно заключить в одинарные или двойные кавычки. +Если в регулярном выражении встречаются символы “<literal>}</literal>” +или “<literal>;</literal>”, то всё выражение нужно заключить в одинарные +или двойные кавычки. </para> </directive> <directive name="set"> -<syntax><value>переменная</value> <value>значение</value></syntax> +<syntax><value>переменная</value> <value>значение</value></syntax> <default/> -<context>server, location, if</context> +<context>server</context> +<context>location</context> +<context>if</context> <para> -Директива устанавливает значение для указанной переменной. +Устанавливает значение для указанной переменной. В качестве значения можно использовать текст, переменные и их комбинации. </para> @@ -248,10 +273,13 @@ permanent — возвращает постоянное перенаправление с кодом 301. <directive name="uninitialized_variable_warn"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>on</default> -<context>http, server, location, if</context> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if</context> <para> -Директива определяет, нужно ли писать в лог предупреждение +Определяет, нужно ли писать в лог предупреждение о неинициализированной переменной. </para> @@ -260,76 +288,80 @@ permanent — возвращает постоянное перенаправление с кодом 301. </section> -<section name="Внутреннее устройство" id="internals"> +<section id="internals" name="Внутреннее устройство"> <para> -Директивы модуля ngx_http_rewrite_module компилируется на стадии -конфигурирования во внутренние коды, исполняемые во время запроса -интерпретатором. Интерпретатор представляет из себя простую -стековую виртуальную машину. +Директивы модуля <literal>ngx_http_rewrite_module</literal> +компилируются на стадии конфигурации во внутренние коды, +исполняемые во время запроса интерпретатором. +Интерпретатор представляет из себя простую стековую виртуальную машину. </para> <para> Например, директивы <example> - location /download/ { - if ($forbidden) { - return 403; - } +location /download/ { + if ($forbidden) { + return 403; + } - if ($slow) { - limit_rate 10k; - } + if ($slow) { + limit_rate 10k; + } - rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; - } + rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; +} </example> будет скомпилированы в такие коды: <example> - переменная $forbidden - проверка на ноль - возврат 403 - завершение всего кода - переменная $slow - проверка на ноль - проверка регулярного выражения - копирование "/" - копирование $1 - копирование "/mp3/" - копирование $2 - копирование ".mp3" - завершение регулярного выражения +переменная $forbidden +проверка на ноль + возврат 403 завершение всего кода +переменная $slow +проверка на ноль +проверка регулярного выражения +копирование "/" +копирование $1 +копирование "/mp3/" +копирование $2 +копирование ".mp3" +завершение регулярного выражения +завершение всего кода </example> </para> <para> -Обратите внимание, что кода для директивы limit_rate нет, поскольку -она не имеет отношения к модулю ngx_http_rewrite_module. Для блока -if создаётся такая же конфигурация, как и для блока location. +Обратите внимание, что кода для директивы +<link doc="ngx_http_core_module.xml" id="limit_rate"/> +нет, поскольку она не имеет отношения к модулю +<literal>ngx_http_rewrite_module</literal>. +Для блока <link id="if"/> создаётся такая же конфигурация, как и для блока +<link doc="ngx_http_core_module.xml" id="location"/>. Если условие истинно, то запрос получает конфигурацию, соответствующую -блоку if, и в этой конфигурации limit_rate равен 10k. +блоку <literal>if</literal>, +и в этой конфигурации <literal>limit_rate</literal> равен 10k. </para> <para> Директиву <example> - rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; +rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; </example> можно сделать на один код меньше, если в регулярном выражении включить первый слэш в скобки: <example> - rewrite ^(<emphasis>/</emphasis>download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; +rewrite ^(<emphasis>/</emphasis>download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; </example> тогда её коды будут выглядеть так: <example> - проверка регулярного выражения - копирование $1 - копирование "/mp3/" - копирование $2 - копирование ".mp3" - завершение регулярного выражения - завершение всего кода +проверка регулярного выражения +копирование $1 +копирование "/mp3/" +копирование $2 +копирование ".mp3" +завершение регулярного выражения +завершение всего кода </example> </para>