Модуль 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 раз.

Директивы

Синтаксис: break;
Умолчание: —
Контекст: server, location, if

Завершает обработку текущего набора директив модуля ngx_http_rewrite_module.

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

Пример: 

if ($slow) {
 limit_rate 10k;
 break;
}
Синтаксис: if (условие) { ... }
Умолчание: —
Контекст: server, location

Проверяется указанное условие. Если оно истинно, то выполняются указанные в фигурных скобках директивы этого модуля и запросу назначается конфигурация, указанная внутри директивы 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.
Синтаксис: return код [текст];
return код URL;
return URL;
Умолчание: —
Контекст: server, location, if

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

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

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

До версии 0.7.51 можно было возвращать только следующие коды: 204, 400, 402 — 406, 408, 410, 411, 413, 416 и 500 — 504.
До версий 1.1.16 и 1.0.13 код 307 не обрабатывался как перенаправление.
До версии 1.13.0 код 308 не обрабатывался как перенаправление.

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

Синтаксис: rewrite regex замена [флаг];
Умолчание: —
Контекст: server, location, if

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

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

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

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

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

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

Синтаксис: rewrite_log on | off;
Умолчание: 
rewrite_log off;
Контекст: http, server, location, if

Разрешает или запрещает записывать в error_log на уровне notice результаты обработки директив модуля ngx_http_rewrite_module.

Синтаксис: set $переменная значение;
Умолчание: —
Контекст: server, location, if

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

Синтаксис: uninitialized_variable_warn on | off;
Умолчание: 
uninitialized_variable_warn on;
Контекст: http, server, location, if

Определяет, нужно ли писать в лог предупреждения о неинициализированных переменных.

Внутреннее устройство

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

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

location /download/ {
 if ($forbidden) {
 return 403;
 }
 if ($slow) {
 limit_rate 10k;
 }
 rewrite ^/(download/.*)/media/(.*)\..*$ /1ドル/mp3/2ドル.mp3 break;
}

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

переменная $forbidden
проверка на ноль
 возврат 403
 завершение всего кода
переменная $slow
проверка на ноль
проверка регулярного выражения
копирование "/"
копирование 1ドル
копирование "/mp3/"
копирование 2ドル
копирование ".mp3"
завершение регулярного выражения
завершение всего кода

Обратите внимание, что инструкций для директивы 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;

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

проверка регулярного выражения
копирование 1ドル
копирование "/mp3/"
копирование 2ドル
копирование ".mp3"
завершение регулярного выражения
завершение всего кода

AltStyle によって変換されたページ (->オリジナル) /