Тестер nginx location — почему побеждает этот блок

Сопоставление nginx location: краткие ответы

Что такое блок location в nginx?

# From the nginx documentation. Which block serves each request?
server {
    location = /                   { }   # A
    location /                     { }   # B
    location /documents/           { }   # C
    location ^~ /images/           { }   # D
    location ~* \.(gif|jpg|jpeg)$  { }   # E
}

#   /                        -> A   exact match, search ends here
#   /index.html              -> B   no regex matched, longest prefix used
#   /documents/document.html -> C   longer prefix than B
#   /images/1.gif            -> D   ^~ won the prefix stage, regex skipped
#   /documents/1.jpg         -> E   regex beats the longer prefix C

# The last two lines are the whole lesson: identical-looking prefixes
# behave differently because only one of them carries ^~.

Основные возможности

Другие способы ответить на этот вопрос

Примеры сопоставления nginx location

location /documents/  ·  location ~* \.(gif|jpg|jpeg)$  ·  GET /documents/1.jpg

~* \.(gif|jpg|jpeg)$ wins

location /uploads/  ·  location ~ \.php$ { fastcgi_pass ... }  ·  GET /uploads/evil.php

~ \.php$ wins — the upload lands in the interpreter

location ^~ /a/  ·  location /a/b/  ·  location ~ \.php$  ·  GET /a/b/x.php

~ \.php$ wins — the ^~ never applied

location /static  ·  location /static/  ·  GET /staticfoo

/static wins

location ~ ^/a  ·  location ~ ^/a/b/c$  ·  GET /a/b/c

~ ^/a wins; ~ ^/a/b/c$ is unreachable

location /a/  ·  location /b/  ·  GET /a/b%2F..%2Fzz

$uri becomes /a/zz, so /a/ wins

Как пользоваться тестером nginx location

1. 1

   Вставьте блок server

   Закиньте целый блок server или только те блоки location, о которых вы рассуждаете. Вложенные location распознаются, а исходные номера строк сохраняются, чтобы таблица совпадала с вашим файлом.

2. 2

   Введите URI запроса

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

3. 3

   Прочитайте победителя, затем проигравших

   Карточка вердикта называет выбранный блок и однострочную причину. Таблица решения под ней объясняет каждый остальной блок: на каком этапе он выбыл и почему.

4. 4

   Проверьте диагностику

   Незаякоренные регулярные выражения, префиксы без завершающего слеша, ^~ с шаблоном регулярного выражения, недостижимые дубликаты и каталоги загрузок, достижимые PHP-регуляркой, — всё это выводится в отчёт.

5. 5

   Поделитесь точным состоянием

   Копирование ссылки кодирует конфигурацию и URI во фрагмент URL, так что коллега откроет ровно то, что видите вы. Фрагменты никогда не передаются на сервер.

Частые ошибки с nginx location

location ^~ /a/ { }
location /a/b/ { }
location ~ \.php$ { }
# /a/b/x.php -> ~ \.php$

location ^~ /a/ { }
location ^~ /a/b/ { }
location ~ \.php$ { }
# /a/b/x.php -> ^~ /a/b/

location /static { root /var/www; }
# also serves /staticfoo and /static-backup

location /static/ { root /var/www; }
location = /static { return 301 /static/; }

location ~ ^/api { }
location ~ ^/api/v2/users$ { }
# the second is unreachable

location ~ ^/api/v2/users$ { }
location ~ ^/api { }

location ^~ "\.php$" { deny all; }

location ~ \.php$ { deny all; }

location /search?q= { }
# never matches anything

location /search {
    if ($arg_q = "") { return 400; }
}

Что можно сделать тестером nginx location

Проверить конфигурацию до того, как она попадёт в прод

Разберитесь с маршрутизацией блока server, который вы отредактировали, но ещё не выкатили. Отлавливается тут та поломка, что проявляется только на определённой форме URI, — ровно та, которую дымовой тест после перезагрузки обычно пропускает.

Выяснить, почему правило перестало работать

Регулярное выражение, которое раньше отрабатывало, а теперь нет, почти всегда жертва порядка: что-то совпало раньше или выше появился ^~. Таблица помечает блок как недостижимый и называет блок, который забрал запрос.

Проверить каталог загрузок или медиафайлов

Загрузите пресет, который воспроизводит схему «загрузка с исполнением», а затем вставьте свои пути. Если PHP-регулярка забирает запросы внутри каталога, доступного на запись, диагностика скажет об этом и назовёт оба блока.

Закрыть замечание на ревью доказательством

Копирование ссылки фиксирует точную конфигурацию и URI во фрагменте URL. Такая ссылка в pull request заменяет спор о приоритетах таблицей решения, которую каждый может прогнать сам.

Объяснить алгоритм выбора

Две справочные таблицы — это статический, индексируемый материал, на который можно сослаться, а кнопки пресетов показывают каждую ловушку без необходимости что-то ломать на сервере. Особенно пример с ^~ обычно быстро завершает спор.

Как работает выбор location в nginx

Нормализация происходит до обращения к любому location

URI раскодируется из процентных последовательностей, сегменты . и .. разрешаются, повторяющиеся слеши схлопываются — и только затем выбирается location. Раскодированный %2F становится настоящим разделителем и участвует в этом разрешении, поэтому /a/b%2F..%2Fzz сопоставляется как /a/zz. Три раскодированных символа — исключение и остаются буквальными: %25, %23 и %3F, из-за чего у /a%3Fx=1 в пути стоит знак вопроса, а строка запроса пуста. Знак + здесь не пробел; пробелом является только %20. Выход выше корня и некорректное экранирование отклоняются с кодом 400 ещё до начала сопоставления.

Решает длина префикса, а не порядок в конфигурации

Сравниваются все совпавшие префиксные location, и побеждает самый длинный — независимо от того, стоит он в файле первым или последним. Сравнение идёт по символам, а не по сегментам пути, поэтому /static совпадает с /staticfoo. Победитель запоминается, а не используется сразу, потому что этап регулярных выражений ещё может его перебить.

^~ подавляет регулярные выражения, а не повышает приоритет

Модификатор проверяется только у того префикса, который уже победил по длине. Если совпадает и более длинный обычный префикс, запоминается именно он, а этап регулярных выражений идёт как обычно — блок ^~ не влияет на запрос вообще. ^~ на вложенном location не защищает от регулярного выражения, объявленного на внешнем уровне, и никогда не подавляет регулярные выражения, вложенные внутрь самого блока.

Регулярные выражения идут в порядке файла, и первое совпадение завершает поиск

nginx хранит регулярные location в том порядке, в каком они были написаны, и не сортирует их. Точность, длина и якоря никак не влияют на то, какое будет проверено первым, поэтому точный шаблон, поставленный ниже широкого, — мёртвая конфигурация. Внутрь совпавшего регулярного location тоже происходит спуск, поэтому вложенные в него location просматриваются следом.

PCRE и ECMAScript — не один и тот же язык

nginx компилирует регулярные выражения location через PCRE, без режимов UTF и multiline, поэтому шаблоны работают с байтами, а ^ привязывается только к началу URI. Одно различие имеет вес для безопасности: $ в PCRE совпадает и прямо перед завершающим переводом строки, поэтому URI, оканчивающийся на %0A, всё равно удовлетворяет \.php$, хотя движок JavaScript отказал бы. Это поведение здесь эмулируется и отмечается, потому что это известный способ проскочить мимо правил, завязанных на расширение файла.

Хорошие практики для nginx location

Защищайте каталоги с записью через ^~, а не обычным префиксом

Любому каталогу, принимающему загрузки, нужен location ^~ /uploads/, чтобы этап регулярных выражений не смог отдать сохранённый файл интерпретатору. Обычный префикс выглядит равнозначным, но таковым не является.

Ставьте завершающий слеш у префиксов каталогов

Пишите location /static/, а не location /static, если только вы намеренно не хотите, чтобы тот же блок обслуживал /staticfoo и /static-backup. Добавьте отдельный location = /static, когда голый путь тоже нужно обработать.

Располагайте регулярные выражения от самого точного к самому широкому

Побеждает первое совпадение, поэтому широкий шаблон выше точного делает точный недостижимым. Держать регулярных выражений мало и осознанно их упорядочивать проще в сопровождении, чем потом разбираться с пересечениями.

Ставьте якорь регулярным выражениям, которые должны совпадать с началом пути

location ~ /admin ищет в любом месте URI и совпадает с /public/admin/x. Пишите ~ ^/admin, когда имеете в виду начало. Якорь только в конце — нормальная и правильная практика для маршрутизации по расширению.

Перепроверяйте маршрутизацию после любой перестановки

Перенос блоков безопасен для префиксов и меняет поведение регулярных выражений. Поскольку диф, который только переставляет строки, выглядит на ревью безобидно, прогнать затронутые URI заново — самый дешёвый способ это поймать.

Частые вопросы о тестере nginx location