Модуль ngx_http_rewrite_module

• Директивы
• break
• if
• return
• rewrite
• rewrite_log
• set
• uninitialized_variable_warn
• Внутренняя реализация

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

Директивы break, if, return, rewrite и set обрабатываются в следующем порядке:

• директивы этого модуля, указанные на уровне server, выполняются последовательно;
• многократно:
  • ищется location на основе URI запроса;
  • директивы этого модуля, указанные внутри найденного location, выполняются последовательно;
  • цикл повторяется, если URI запроса был переписан, но не более 10 раз.

Директивы

Останавливает обработку текущего набора директивы ngx_http_rewrite_module.

Если директива указана внутри location, дальнейшая обработка запроса продолжается в этом location.

Пример:

if ($slow) {
    limit_rate 10k;
    break;
}

Указанное condition выражение оценивается. Если оно истинно, директивы этого модуля, указанные внутри фигурных скобок, выполняются, и запросу назначается конфигурация внутри директивы if. Конфигурации внутри директивы if наследуются из предыдущего уровня конфигурации.

Условие может быть любым из следующих:

• имя переменной; ложно, если значение переменной является пустой строкой или «0»;

  До версии 1.0.1, любая строка, начинающаяся с «0», считалась ложным значением.

• сравнение переменной со строкой с помощью операторов «=» и «!=»;
• сопоставление переменной с регулярным выражением с помощью операторов «~» (для чувствительного к регистру сопоставления) и «~*» (для нечувствительного к регистру сопоставления). Регулярные выражения могут содержать захват, который становится доступным для повторного использования в переменных $1..$9. Также доступны отрицательные операторы «!~» и «!~*». Если регулярное выражение включает символы «}» или «;», все выражение должно быть заключено в одинарные или двойные кавычки.
• проверка существования файла с операторами «-f» и «!-f»;
• проверка существования каталога с операторами «-d» и «!-d»;
• проверка существования файла, каталога или символической ссылки с операторами «-e» и «!-e»;
• проверка существования исполняемого файла с операторами «-x» и «!-x».

Примеры:

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;
}

Значение встроенной переменной $invalid_referer устанавливается директивой valid_referers.

Останавливает обработку и возвращает указанный code ответ клиенту. Нестандартный код 444 закрывает соединение без отправки заголовка ответа.

Начиная с версии 0.8.42, можно указать либо URL редиректа (для кодов 301, 302, 303, 307 и 308), либо тело ответа text (для других кодов). Текст тела ответа и URL редиректа могут содержать переменные. В качестве специального случая, URL редиректа можно указать как URI, локальный для данного сервера, в этом случае полный URL редиректа формируется в соответствии со схемой запроса ($scheme) и директивами server_name_in_redirect и port_in_redirect.

Кроме того, для временного редиректа с кодом 302 может быть указан URL в качестве единственного параметра. Такой параметр должен начинаться со строки «http://», «https://» или «$scheme». URL может содержать переменные.

До версии 0.7.51 могли возвращаться только следующие коды: 204, 400, 402 — 406, 408, 410, 411, 413, 416 и 500 — 504.

Код 307 не обрабатывался как редирект до версий 1.1.16 и 1.0.13.

Код 308 не обрабатывался как редирект до версии 1.13.0.

См. также директиву error_page.

Если указанное регулярное выражение соответствует URI запроса, URI изменяется, как указано в строке replacement. Директивы rewrite выполняются последовательно в порядке их появления в файле конфигурации. Можно прекратить дальнейшую обработку директив с помощью флагов. Если строка замены начинается со строки «http://», «https://» или «$scheme», обработка прекращается, и клиенту возвращается редирект.

Необязательный параметр flag может быть одним из:

last

останавливает обработку текущего набора директив ngx_http_rewrite_module и начинает поиск нового location, соответствующего изменённому URI;

break

останавливает обработку текущего набора директив ngx_http_rewrite_module аналогично директиве break;

redirect

возвращает временный редирект с кодом 302; используется, если строка замены не начинается со строки «http://», «https://» или «$scheme»;

permanent

возвращает постоянный редирект с кодом 301.

Полный URL редиректа формируется в соответствии со схемой запроса ($scheme) и директивами server_name_in_redirect и port_in_redirect.

Пример:

server {
    ...
    rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last;
    rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra  last;
    return  403;
    ...
}

Но если эти директивы помещены внутри location «/download/», флаг last должен быть заменён на break, иначе nginx сделает 10 циклов и вернёт ошибку 500:

location /download/ {
    rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
    rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra  break;
    return  403;
}

Если строка replacement содержит новые аргументы запроса, предыдущие аргументы запроса добавляются после них. Если этого не требуется, в конце строки замены ставится вопросительный знак, чтобы не добавлять их, например:

rewrite ^/users/(.*)$ /show?user=$1? last;

Если регулярное выражение включает символы «}» или «;», все выражение должно быть заключено в одинарные или двойные кавычки.

Включает или отключает логирование результатов обработки директив модуля ngx_http_rewrite_module в error_log на уровне notice.

Устанавливает value для указанной variable. value может содержать текст, переменные и их комбинацию.

Управляет включением или выключением логирования предупреждений об инициализированных переменных.

Внутренняя реализация

Директивы модуля ngx_http_rewrite_module компилируются на стадии конфигурации во внутренние инструкции, которые интерпретируются во время обработки запросов. Интерпретатор — это простая виртуальная машина стека.

Например, директивы

location /download/ {
    if ($forbidden) {
        return 403;
    }

    if ($slow) {
        limit_rate 10k;
    }

    rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
}

будут преобразованы в эти инструкции:

variable $forbidden
check against zero
    return 403
    end of code
variable $slow
check against zero
match of regular expression
copy "/"
copy $1
copy "/mp3/"
copy $2
copy ".mp3"
end of regular expression
end of code

Обратите внимание, что для директивы limit_rate выше нет инструкций, так как она не связана с модулем ngx_http_rewrite_module. Отдельная конфигурация создаётся для блока if. Если условие истинно, запросу назначается эта конфигурация, где limit_rate равно 10k.

Директива

rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;

может быть сокращена на одну инструкцию, если первый слэш в регулярном выражении поместить в скобки:

rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;

Соответствующие инструкции будут выглядеть так:

match of regular expression
copy $1
copy "/mp3/"
copy $2
copy ".mp3"
end of regular expression
end of code