Mercurial > hg > nginx-site
view xml/ru/docs/http/ngx_http_rewrite_module.xml @ 382:b838f6e9192e
Revision.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Tue, 31 Jan 2012 16:29:31 +0000 |
parents | 4c6d2c614d2c |
children | 1702722eca07 |
line wrap: on
line source
<?xml version="1.0"?> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Модуль ngx_http_rewrite_module" link="/ru/docs/http/ngx_http_rewrite_module.html" lang="ru"> <section id="summary"> <para> Модуль <literal>ngx_http_rewrite_module</literal> позволяет изменять URI с помощью регулярных выражений, делать перенаправления и выбирать конфигурацию в зависимости от переменных. Если директивы этого модуля описаны на уровне сервера, то они выполняются до того, как определяется location для запроса. Если в выбранном location тоже есть директивы модуля <literal>ngx_http_rewrite_module</literal>, то они также выполняются. Если URI изменился в результате исполнения директив внутри location, то снова определяется location для уже нового URI. Этот цикл может повторяться до 10 раз, после чего nginx возвращает ошибку <http-status code="500" text="Internal Server Error"/>. </para> </section> <section id="directives" name="Директивы"> <directive name="break"> <syntax/> <default/> <context>server</context> <context>location</context> <context>if</context> <para> Завершает обработку текущего набора директив модуля <literal>ngx_http_rewrite_module</literal>. </para> <para> Пример: <example> if ($slow) { limit_rate 10k; break; } </example> </para> </directive> <directive name="if"> <syntax block="yes">(<value>условие</value>)</syntax> <default/> <context>server</context> <context>location</context> <para> Проверяет истинность условия. Если оно истинно, то выполняется указанный в фигурных скобках код и запрос обрабатывается в соответствии с заданной там же конфигурацией. Конфигурация внутри директивы <literal>if</literal> наследуется с предыдущего уровня. </para> <para> В качестве условия могут быть заданы: <list type="bullet"> <listitem> имя переменной; ложными значениями переменной являются пустая строка “” или любая строка, начинающаяся на “<literal>0</literal>”; </listitem> <listitem> сравнение переменной со строкой с помощью операторов “<literal>=</literal>” и “<literal>!=</literal>”; </listitem> <listitem> проверка переменной с помощью регулярного выражения с учётом регистра символов — “<literal>~</literal>” и без него — “<literal>~*</literal>”. В регулярных выражениях можно использовать выделения, которые затем доступны в виде переменных <var>$1</var> — <var>$9</var>. Также можно использовать отрицательные операторы “<literal>!~</literal>” и “<literal>!~*</literal>”. Если в регулярном выражении встречаются символы “<literal>}</literal>” или “<literal>;</literal>”, то всё выражение нужно заключить в одинарные или двойные кавычки. </listitem> <listitem> проверка существования файла с помощью операторов “<literal>-f</literal>” и “<literal>!-f</literal>”; </listitem> <listitem> проверка существования каталога с помощью операторов “<literal>-d</literal>” и “<literal>!-d</literal>”; </listitem> <listitem> проверка существования файла, каталога или символической ссылки с помощью операторов “<literal>-e</literal>” и “<literal>!-e</literal>”; </listitem> <listitem> проверка исполняемости файла с помощью операторов “<literal>-x</literal>” и “<literal>!-x</literal>”. </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> Значение встроенной переменной <var>$invalid_referer</var> задаётся директивой <link doc="ngx_http_referer_module.xml" id="valid_referers"/>. </para> </directive> <directive name="return"> <syntax><value>код</value></syntax> <default/> <context>server</context> <context>location</context> <context>if</context> <para> Завершает исполнение кода и возвращает клиенту указанный код. Можно использовать следующие значения: 204, 400, 402 — 406, 408, 410, 411, 413, 416 и 500 — 504. Кроме того, нестандартный код 444 закрывает соединение без передачи заголовка ответа. </para> </directive> <directive name="rewrite"> <syntax> <value>regex</value> <value>замена</value> [<value>флаг</value>]</syntax> <default/> <context>server</context> <context>location</context> <context>if</context> <para> Изменяет URI в соответствии с регулярным выражением и строкой замены. Директивы выполняются в порядке их следования в конфигурационном файле. С помощью флагов можно досрочно прекратить исполнение директив. Если строка замены начинается с “<literal>http://</literal>”, то клиенту будет возвращено перенаправление и обработка директив также завершается. </para> <para> Флаги могут быть следующими: <list type="tag"> <tag-name><literal>last</literal></tag-name> <tag-desc> завершает обработку текущего набора директив модуля <literal>ngx_http_rewrite_module</literal>, после чего ищется соответствие URI и location; </tag-desc> <tag-name><literal>break</literal></tag-name> <tag-desc> завершает обработку текущего набора директив модуля <literal>ngx_http_rewrite_module</literal>; </tag-desc> <tag-name><literal>redirect</literal></tag-name> <tag-desc> возвращает временное перенаправление с кодом 302; используется, если заменяющая строка не начинается с “<literal>http://</literal>”; </tag-desc> <tag-name><literal>permanent</literal></tag-name> <tag-desc> возвращает постоянное перенаправление с кодом 301. </tag-desc> </list> </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 “<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; } </example> </para> <para> Если в строке замены указаны аргументы, то предыдущие аргументы запроса добавляются после них. Можно отказаться от этого добавления, указав в конце строки замены знак вопроса: <example> rewrite ^/users/(.*)$ /show?user=$1? last; </example> </para> <para> Если в регулярном выражении встречаются символы “<literal>}</literal>” или “<literal>;</literal>”, то всё выражение нужно заключить в одинарные или двойные кавычки. </para> </directive> <directive name="set"> <syntax><value>переменная</value> <value>значение</value></syntax> <default/> <context>server</context> <context>location</context> <context>if</context> <para> Устанавливает значение для указанной переменной. В качестве значения можно использовать текст, переменные и их комбинации. </para> </directive> <directive name="uninitialized_variable_warn"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>on</default> <context>http</context> <context>server</context> <context>location</context> <context>if</context> <para> Определяет, нужно ли писать в лог предупреждение о неинициализированной переменной. </para> </directive> </section> <section id="internals" name="Внутреннее устройство"> <para> Директивы модуля <literal>ngx_http_rewrite_module</literal> компилируются на стадии конфигурации во внутренние коды, исполняемые во время запроса интерпретатором. Интерпретатор представляет из себя простую стековую виртуальную машину. </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> Обратите внимание, что кода для директивы <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"/>. Если условие истинно, то запрос получает конфигурацию, соответствующую блоку <literal>if</literal>, и в этой конфигурации <literal>limit_rate</literal> равен 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>