<?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>