Mercurial > hg > nginx-site
view xml/ru/docs/http/ngx_http_rewrite_module.xml @ 290:15f81ed48a43
Documented regex captures in the "if" SSI command.
author | Valentin Bartenev <vbart@nginx.com> |
---|---|
date | Wed, 28 Dec 2011 13:27:29 +0000 |
parents | 4c6d2c614d2c |
children | b838f6e9192e |
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> Модуль 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/> <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 block="yes">(<value>условие</value>)</syntax> <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" id="valid_referers"/>. </para> </directive> <directive name="return"> <syntax><value>код</value></syntax> <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><value>regex</value> <value>замена</value> <value>флаг</value></syntax> <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><value>переменная</value> <value>значение</value></syntax> <default/> <context>server, location, if</context> <para> Директива устанавливает значение для указанной переменной. В качестве значения можно использовать текст, переменные и их комбинации. </para> </directive> <directive name="uninitialized_variable_warn"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>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>