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 ディレクティブは次の順番で処理されます:

ディレクティブ

構文: break;
デフォルト: -
コンテキスト: server, location, if

現在のngx_http_rewrite_module ディレクティブのセットの処理を停止する。

もしディレクティブがlocationの中で定義されていると、このlocationでリクエストの更なる処理が続きます。

例:

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

構文: if (condition) { ... }
デフォルト: -
コンテキスト: server, location

指定されたcondition が評価されます。trueの場合、括弧の中で指定されたこのモジュールのディレクティブが実行され、リクエストはifディレクティブの中の設定に割り当てられます。if ディレクティブの中の設定は上の設定レベルから継承されます。

条件は以下のいずれかです:

例:

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 code [text];
return code URL;
return URL;
デフォルト: -
コンテキスト: server, location, if

処理を停止し、指定されたcodeをクライアントに返します。非標準のコード 444 は応答ヘッダを送信せずに接続を閉じます。

バージョン 0.8.42から、リダイレクトURL(コード 301, 302, 303, 307 および 308)か応答ボディtext (その他のコード) のどちらかを指定することができます。応答ボディテキストとリダイレクトURLには変数を含むことができます。特別な場合として、リダイレクトURLはこのサーバへのローカルなURLとして指定することができます。この場合、完全なリダイレクトURLはリクエストスキーム($scheme) と server_name_in_redirectport_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 regex replacement [flag];
デフォルト: -
コンテキスト: 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_redirectport_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 on | off;
デフォルト:
rewrite_log off;
コンテキスト: http, server, location, if

ngx_http_rewrite_module モジュールのディレクティブの処理結果をnotice レベルでerror_log に記録することを有効または無効にします。

構文: set $variable value;
デフォルト: -
コンテキスト: server, location, if

指定されたvariableの値を設定します。valueにはテキスト、変数、それらの組み合わせを含めることができます。

構文: uninitialized_variable_warn on | off;
デフォルト:
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_ratengx_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

TOP
inserted by FC2 system