nginx location テスター — なぜそのブロックが勝つのか

nginx location マッチ：早わかり

nginx の location ブロックとは？

# 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. 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 フラグメントに入ります。これをプルリクエストに貼れば、優先順位をめぐる議論を、誰でも再実行できる判定テーブルに置き換えられます。

選択アルゴリズムを教える

2つのリファレンステーブルは静的でクロール可能な資料なので、そのまま指し示せます。プリセットは、サーバーを壊さずに各トラップを実演します。とくに ^~ の例は、議論を手早く終わらせがちです。

nginx の location 選択はどう動くか

正規化は location を見に行く前に済んでいる

URI はパーセントデコードされ、. と .. のセグメントが解決され、連続スラッシュがまとめられ、そのあとで初めて location が選ばれます。デコードされた %2F は本物の区切りになってこの解決に参加するので、/a/b%2F..%2Fzz は /a/zz としてマッチします。デコード後も文字どおり残る例外が3つあります。%25、%23、%3F です——だから /a%3Fx=1 はパスに疑問符を持ち、クエリ文字列は空になります。ここでの + は空白ではありません。空白になるのは %20 だけです。ルートより上へ登るトラバーサルと不正なエスケープは、どちらもマッチが始まる前に 400 で拒否されます。

決めるのは前方一致の長さで、設定の順序ではない

マッチした前方一致 location はすべて比較され、ファイルの先頭にあろうと末尾にあろうと最長のものが勝ちます。比較はパスの区切りではなく文字単位なので、/static は /staticfoo にマッチします。勝者はすぐ使われるのではなく覚えられます。正規表現フェーズがまだ上書きし得るからです。

^~ は正規表現を抑えるだけで、優先度は上げない

この修飾子が見られるのは、すでに長さで勝った前方一致に対してだけです。より長い修飾子なしの前方一致もマッチしていれば覚えられるのはそちらで、正規表現フェーズはいつもどおり走ります——その ^~ ブロックはこのリクエストに何の効果もありません。ネストした location に ^~ を付けても外側で宣言された正規表現からは守れませんし、自分のブロックの中にネストした正規表現を抑えることもありません。

正規表現はファイル順に走り、最初のマッチで探索が終わる

nginx は正規表現 location を書かれた順のまま保持し、並べ替えません。限定度、長さ、アンカーの有無はどれが先に試されるかに影響しないので、広いパターンの下に置いた厳密なパターンは死んだ設定です。マッチした正規表現 location にも降りていくため、そのネストした location はその後に探索されます。

PCRE と ECMAScript は同じ言語ではない

nginx は location の正規表現を PCRE でコンパイルし、UTF モードも複数行モードも使わないため、パターンはバイト単位で動き、^ は URI の先頭だけにアンカーします。1つの違いはセキュリティに直結します。PCRE の $ は末尾の改行の直前にもマッチするので、%0A で終わる URI は JavaScript エンジンなら拒むところを \.php$ に依然として一致します。この挙動はここで再現して報告します。拡張子を鍵にしたルールをすり抜ける既知の手口だからです。

nginx location の書き方：ベストプラクティス

書き込み可能なディレクトリは修飾子なしではなく ^~ で守る

アップロードを受け付けるディレクトリには location ^~ /uploads/ が必要です。そうすれば正規表現フェーズが保存済みファイルをインタプリタへ渡せません。修飾子なしの前方一致は同等に見えて、同等ではありません。

ディレクトリの前方一致には末尾スラッシュを付ける

/staticfoo や /static-backup まで同じブロックで配信したいのでなければ、location /static ではなく location /static/ と書きます。スラッシュなしのパスも扱う必要があるなら、別に location = /static を足します。

正規表現は限定的なものから順に並べる

最初のマッチが勝つので、広いパターンを厳密なものの上に置くと厳密なほうが到達不能になります。正規表現を少なく保ち、順序を意図的に決めるほうが、後から重なりを推理するより保守しやすくなります。

パスの先頭に当てたい正規表現にはアンカーを付ける

location ~ /admin は URI のどこでも探すので /public/admin/x にもマッチします。先頭のつもりなら ~ ^/admin と書きます。末尾だけにアンカーするのは拡張子ルーティングでは普通で、正しい書き方です。

並べ替えたら必ずルーティングを確認し直す

ブロックの移動は前方一致には安全ですが、正規表現では挙動を変えます。行を入れ替えただけの差分はレビューでは無害に見えるので、影響する URI を流し直すのがいちばん安上がりな押さえ方です。

nginx location テスター よくある質問