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レベルに指定された、このモジュールのディレクティブは順番に実行されます;
- 再帰的:
ディレクティブ
構文: |
break; |
---|---|
デフォルト: | - |
コンテキスト: |
server , location , if |
現在のngx_http_rewrite_module
ディレクティブのセットの処理を停止する。
もしディレクティブがlocationの中で定義されていると、このlocationでリクエストの更なる処理が続きます。
例:
if ($slow) { limit_rate 10k; break; }
構文: |
if ( |
---|---|
デフォルト: | - |
コンテキスト: |
server , location |
指定されたcondition
が評価されます。trueの場合、括弧の中で指定されたこのモジュールのディレクティブが実行され、リクエストはif
ディレクティブの中の設定に割り当てられます。if
ディレクティブの中の設定は上の設定レベルから継承されます。
条件は以下のいずれかです:
-
変数名; もし変数の値が空文字あるいは"
0
"であれば falseバージョン1.0.1より前では、"
0
"から始まるどのような文字列もfalse値と見なされました。 -
"
=
"と"!=
"演算子を使った文字列と 変数の比較; -
"
~
"を使った正規表現(大文字小文字を区別する)と"~*
"(大文字小文字を区別しない)識別子を使った正規表現と変数とのマッチング正規表現にはキャプチャを含むことができ、それらは後で$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 return |
---|---|
デフォルト: | - |
コンテキスト: |
server , location , if |
処理を停止し、指定されたcode
をクライアントに返します。非標準のコード 444 は応答ヘッダを送信せずに接続を閉じます。
バージョン 0.8.42から、リダイレクトURL(コード 301, 302, 303, 307 および 308)か応答ボディtext
(その他のコード) のどちらかを指定することができます。応答ボディテキストとリダイレクトURLには変数を含むことができます。特別な場合として、リダイレクトURLはこのサーバへのローカルなURLとして指定することができます。この場合、完全なリダイレクト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, and 500 — 504.
コード 307はバージョン1.1.16と1.0.13までリダイレクトとして扱われませんでした。
コード 308 はバージョン 1.13.0までリダイレクトとして扱われませんでした。
error_page ディレクティブも見てください。
構文: |
rewrite
|
---|---|
デフォルト: | - |
コンテキスト: |
server , location , if |
指定された正規表現がリクエストURIに一致した場合、URIはreplacement
文字列で指定されたように変更されます。rewrite
ディレクティブは設定ファイル中に現れた順番で順次実行されます。 フラグを使ってそれ以上のディレクティブの実行を終わらせることができます。置き換え文字列が"http://
", "https://
" または "$scheme
"で始まる場合、処理は停止し、リダイレクトがクライアントに返されます。
任意のパラメータ flag
は次のいずれかです:
last
-
現在の
ngx_http_rewrite_module
ディレクティブのセットの処理を停止し、変更されたURIに一致する新しいlocationの検索を開始します; break
-
breakと同じように、現在の
ngx_http_rewrite_module
ディレクティブのセットの処理を停止します; 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; ... }
しかし、もしこれらのディレクティブが"/download/
" locationの中に配置される場合は、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;
正規表現に"}
"または";
"文字が含まれる場合、表現全体はシングルまたはダブルクォートで囲まれていなければなりません。
構文: |
rewrite_log |
---|---|
デフォルト: |
rewrite_log off; |
コンテキスト: |
http , server , location , if |
ngx_http_rewrite_module
モジュールのディレクティブの処理結果をnotice
レベルでerror_log に記録することを有効または無効にします。
構文: |
set |
---|---|
デフォルト: | - |
コンテキスト: |
server , location , if |
指定されたvariable
の値を設定します。value
にはテキスト、変数、それらの組み合わせを含めることができます。
構文: |
uninitialized_variable_warn |
---|---|
デフォルト: |
uninitialized_variable_warn on; |
コンテキスト: |
http , server , location , if |
初期化されていない変数のwarningを記録するかどうかを制御します。
内部実装
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 ブロックのために作成されます。もし条件がtrueであれば、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