Mercurial > hg > nginx-site
diff xml/ru/docs/http/ngx_http_rewrite_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_rewrite_module.xml @@ -0,0 +1,340 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_rewrite_module" + link="/ru/docs/http/ngx_http_rewrite_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_rewrite_module позволяет изменять URI с помощью +регулярных выражений, делать редиректы и выбирать конфигурацию +в зависимости от переменных. Если директивы этого модуля описаны +на уровне сервера, то они выполняются до того, как определяется +location для запроса. Если в выбранном location тоже есть +директивы модуля ngx_http_rewrite_module, то они также выполняются. +Если URI изменился в результате исполнения директив внутри location, +то снова определяется location для уже нового URI. Этот цикл может +повторяться до 10 раз, после чего nginx возвращает ошибку +"Server Internal Error" (500). +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="break"> +<syntax>break</syntax> +<default>нет</default> +<context>server, location, if</context> + +<para> +Директива завершает обработку текущего набора директив +ngx_http_rewrite_module. +</para> + +<para> +Пример использования: +<example> + if ($slow) { + limit_rate 10k; + break; + } +</example> +</para> + +</directive> + + +<directive name="if"> +<syntax>if (<value>условие</value>) { ... }</syntax> +<default>нет</default> +<context>server, location</context> + +<para> +Директива if проверяет истинность условия, если оно истинно, +то выполняется указанный в фигурных скобках код и запрос обрабатывается +в соответствии с заданной там же конфигурацией. +Конфигурация внутри директивы if наследуется из предыдущего уровня. +</para> + +<para> +В качестве условия могут быть заданы: +<list type="bullet"> + +<listitem> +имя переменной; ложными значениями переменной являются пустая строка "" +или любая строка, начинающиеся на "0"; +</listitem> + +<listitem> +сравнение переменной со строкой с помощью операторов "=" и "!="; +</listitem> + +<listitem> +проверка переменной с помощью регулярного выражения без учёта +регистра символов — "~*" и с учётом — "~". +В регулярных выражениях можно использовать выделения, которые затем +доступны в виде переменных $1 — $9. +Также можно использовать отрицательные операторы "!~" и "!~*". +Если в регулярном выражении встречаются символы "}" или ";", то +всё выражение нужно заключить в одинарные или двойные кавычки. +</listitem> + +<listitem> +проверка существования файла с помощью операторов "-f" и "!-f"; +</listitem> + +<listitem> +проверка существования каталога с помощью операторов "-d" и "!-d"; +</listitem> + +<listitem> +проверка существования файла, каталога или символической ссылки +с помощью операторов "-e" и "!-e"; +</listitem> + +<listitem> +проверка исполняемости файла с помощью операторов "-x" и "!-x". +</listitem> + +</list> +</para> + +<para> +Примеры использования: +<example> + if ($http_user_agent ~ MSIE) { + rewrite ^(.*)$ /msie/$1 break; + } + + if ($http_cookie ~* "id=([^;]+)(?:;|$)" ) { + set $id $1; + } + + if ($request_method = POST ) { + return 405; + } + + + if ($slow) { + limit_rate 10k; + } + + if ($invalid_referer) { + return 403; + } +</example> +Значение встроенной переменной $invalid_referer задаётся директивой <link doc="ngx_http_referer_module.xml#valid_referers">valid_referers</link>. +</para> + +</directive> + + +<directive name="return"> +<syntax>return <value>код</value></syntax> +<default>нет</default> +<context>server, location, if</context> + +<para> +Директива return завершает исполнение кода и возвращает клиенту +указанный код. Можно использовать следующие значения: 204, 400, +402 — 406, 408, 410, 411, 413, 416 и 500 — 504. +Кроме того, нестандартный код 444 закрывает соединение без передачи +заголовка ответа. +</para> + +</directive> + + +<directive name="rewrite"> +<syntax>rewrite <value>regex</value> <value>замена</value> + <value>флаг</value> +</syntax> +<default>нет</default> +<context>server, location, if</context> + +<para> +Директива rewrite изменяет URI в соответствии с регулярным выражением +и строкой замены. Директивы выполняются в порядке их следования в +конфигурационном файле. С помощью флагов можно досрочно прекратить +исполнение директив. Если строка замены начинается с "http://", то +клиенту будет возвращён редирект и обработка директив также завершается. +</para> + +<para> +Флаги могут быть следующими: +<list type="bullet"> + +<listitem> +last — завершает обработку текущего набора директив +ngx_http_rewrite_module, после чего ищется соответствие URI и location; +</listitem> + +<listitem> +break — завершает обработку текущего набора директив +ngx_http_rewrite_module; +</listitem> + +<listitem> +redirect — возвращает временный редирект с кодом 302; +используется, если заменяющая строка не начинается с "http://"; +</listitem> + +<listitem> +permanent — возвращает постоянный редирект с кодом 301. +</listitem> + +</list> +</para> + +<para> +</para> + +<para> +Пример использования: +<example> + 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: +<example> + 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; +</example> +</para> + +<para> +Если в регулярном выражении встречаются символы "}" или ";", то +всё выражение нужно заключить в одинарные или двойные кавычки. +</para> + +</directive> + + +<directive name="set"> +<syntax>set <value>переменная</value> <value>значение</value> +</syntax> +<default>нет</default> +<context>server, location, if</context> + +<para> +Директива устанавливает значение для указанной переменной. +В качестве значения можно использовать текст, переменные и их комбинации. +</para> + +</directive> + + +<directive name="uninitialized_variable_warn"> +<syntax>uninitialized_variable_warn <value>on|off</value></syntax> +<default>uninitialized_variable_warn on</default> +<context>http, server, location, if</context> + +<para> +Директива определяет, нужно ли писать в лог предупреждение +о неинициализированной переменной. +</para> + +</directive> + +</section> + + +<section name="Внутреннее устройство" id="internals"> + +<para> +Директивы модуля ngx_http_rewrite_module компилируется на стадии +конфигурирования во внутренние коды, исполняемые во время запроса +интерпретатором. Интерпретатор представляет из себя простую +стековую виртуальную машину. +</para> + +<para> +Например, директивы +<example> + location /download/ { + if ($forbidden) { + return 403; + } + + if ($slow) { + limit_rate 10k; + } + + rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; + } +</example> +будет скомпилированы в такие коды: +<example> + переменная $forbidden + проверка на ноль + возврат 403 + завершение всего кода + переменная $slow + проверка на ноль + проверка регулярного выражения + копирование "/" + копирование $1 + копирование "/mp3/" + копирование $2 + копирование ".mp3" + завершение регулярного выражения + завершение всего кода +</example> +</para> + +<para> +Обратите внимание, что кода для директивы limit_rate нет, поскольку +она не имеет отношения к модулю ngx_http_rewrite_module. Для блока +if создаётся такая же конфигурация, как и для блока location. +Если условие истинно, то запрос получает конфигурацию, соответствующую +блоку if, и в этой конфигурации limit_rate равен 10k. +</para> + +<para> +Директиву +<example> + rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; +</example> +можно сделать на один код меньше, если в регулярном выражении включить +первый слэш в скобки: +<example> + rewrite ^(<emphasis>/</emphasis>download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; +</example> +тогда её коды будут выглядеть так: +<example> + проверка регулярного выражения + копирование $1 + копирование "/mp3/" + копирование $2 + копирование ".mp3" + завершение регулярного выражения + завершение всего кода +</example> +</para> + +</section> + +</module>