ngx_http_rewrite_module.xml

<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Модуль ngx_http_rewrite_module"
        link="/ru/docs/http/ngx_http_rewrite_module.html"
        lang="ru"
        rev="9">

<section id="summary">

<para>
Модуль <literal>ngx_http_rewrite_module</literal> позволяет
изменять URI запроса с помощью регулярных выражений PCRE, делать перенаправления
и выбирать конфигурацию по условию.
</para>

<para>
Директивы <link id="break"/>, <link id="if"/>, <link id="return"/>,
<link id="rewrite"/> и <link id="set"/>
обрабатываются в следующем порядке:
<list type="bullet">

<listitem>
последовательно выполняются директивы этого модуля, описанные на уровне
<link doc="ngx_http_core_module.xml" id="server"/>;
</listitem>

<listitem>
в цикле:
<list type="bullet">

<listitem>
ищется
<link doc="ngx_http_core_module.xml" id="location"/>
по URI запроса;
</listitem>

<listitem>
последовательно выполняются директивы этого модуля,
описанные в найденном location;
</listitem>

<listitem>
цикл повторяется, если URI запроса <link id="rewrite">изменялся</link>,
но не более
<link doc="ngx_http_core_module.xml" id="internal">10 раз</link>.
</listitem>

</list>
</listitem>

</list>
</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>
Если директива указана внутри
<link doc="ngx_http_core_module.xml" id="location"/>,
дальнейшая обработка запроса продолжается в этом location.
</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>
Проверяется указанное <value>условие</value>.
Если оно истинно, то выполняются указанные в фигурных скобках директивы
этого модуля и запросу назначается конфигурация, указанная внутри
директивы <literal>if</literal>.
Конфигурации внутри директив <literal>if</literal> наследуются с
предыдущего уровня конфигурации.
</para>

<para>
В качестве условия могут быть заданы:
<list type="bullet">

<listitem>
имя переменной; ложными значениями переменной являются пустая строка
или “<literal>0</literal>”;
<note>
До версии 1.0.1 ложным значением также являлась любая строка,
начинающаяся на “<literal>0</literal>”.
</note>
</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>
<note>
Значение встроенной переменной <var>$invalid_referer</var> задаётся директивой
<link doc="ngx_http_referer_module.xml" id="valid_referers"/>.
</note>
</para>

</directive>


<directive name="return">
<syntax><value>код</value> [<value>текст</value>]</syntax>
<syntax><value>код</value> <value>URL</value></syntax>
<syntax><value>URL</value></syntax>
<default/>
<context>server</context>
<context>location</context>
<context>if</context>

<para>
Завершает обработку и возвращает клиенту указанный <value>код</value>.
Нестандартный код 444 закрывает соединение без передачи
заголовка ответа.
</para>

<para>
Начиная с версии 0.8.42 можно задать
либо URL перенаправления (для кодов 301, 302, 303, 307 и 308)
либо <value>текст</value> тела ответа (для остальных кодов).
В тексте тела ответа и URL перенаправления можно использовать переменные.
Как частный случай, URL перенаправления может быть задан как URI,
локальный для данного сервера, при этом полный URL перенаправления
формируется согласно схеме запроса (<var>$scheme</var>) и директивам
<link doc="ngx_http_core_module.xml" id="server_name_in_redirect"/> и
<link doc="ngx_http_core_module.xml" id="port_in_redirect"/>.
</para>

<para>
Кроме того, в качестве единственного параметра можно указать
<value>URL</value> для временного перенаправления с кодом 302.
Такой параметр должен начинаться со строк “<literal>http://</literal>”,
“<literal>https://</literal>” или “<literal>$scheme</literal>”.
В <value>URL</value> можно использовать переменные.
</para>

<para>
<note>
До версии 0.7.51 можно было возвращать только следующие коды:
204, 400, 402 — 406, 408, 410, 411, 413, 416 и 500 — 504.
</note>

<note>
До версий 1.1.16 и 1.0.13 код 307 не обрабатывался как перенаправление.
</note>

<note>
До версии 1.13.0 код 308 не обрабатывался как перенаправление.
</note>
</para>

<para>
См. также директиву <link doc="ngx_http_core_module.xml" id="error_page"/>.
</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 запроса, URI изменяется
в соответствии со строкой замены.
Директивы <literal>rewrite</literal> выполняются последовательно,
в порядке их следования в конфигурационном файле.
С помощью флагов можно прекратить дальнейшую обработку директив.
Если строка замены начинается с “<literal>http://</literal>”,
“<literal>https://</literal>” или “<literal>$scheme</literal>”,
то обработка завершается и клиенту возвращается перенаправление.
</para>

<para>
Необязательный параметр <value>флаг</value> может быть одним из:
<list type="tag">

<tag-name><literal>last</literal></tag-name>
<tag-desc>
завершает обработку текущего набора директив модуля
<literal>ngx_http_rewrite_module</literal>,
после чего ищется новый location, соответствующий изменённому URI;
</tag-desc>

<tag-name><literal>break</literal></tag-name>
<tag-desc>
завершает обработку текущего набора директив модуля
<literal>ngx_http_rewrite_module</literal>
аналогично директиве <link id="break"/>;
</tag-desc>

<tag-name><literal>redirect</literal></tag-name>
<tag-desc>
возвращает временное перенаправление с кодом 302;
используется, если заменяющая строка не начинается с
“<literal>http://</literal>”, “<literal>https://</literal>”
или “<literal>$scheme</literal>”;
</tag-desc>

<tag-name><literal>permanent</literal></tag-name>
<tag-desc>
возвращает постоянное перенаправление с кодом 301.
</tag-desc>

</list>
Полный URL перенаправлений формируется согласно
схеме запроса (<var>$scheme</var>) и директив
<link doc="ngx_http_core_module.xml" id="server_name_in_redirect"/> и
<link doc="ngx_http_core_module.xml" id="port_in_redirect"/>.
</para>

<para>
Пример:
<example>
server {
    ...
    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="rewrite_log">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if</context>

<para>
Разрешает или запрещает записывать в
<link doc="../ngx_core_module.xml" id="error_log"/>
на уровне <literal>notice</literal>
результаты обработки директив модуля <literal>ngx_http_rewrite_module</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"/> создаётся отдельная конфигурация.
Если условие истинно, запрос получает эту конфигурацию,
и в ней <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>