モジュール ngx_http_rewrite_module

ngx_http_rewrite_module モジュールは、PCRE 正規表現を使用してリクエスト URI を変更し、リダイレクトを返し、条件付きで設定を選択するために使用されます。

break、if、return、rewrite、および set ディレクティブは、以下の順序で処理されます。

• server レベルで指定されたこのモジュールのディレクティブは、順番に実行されます。
• 繰り返し
  • リクエスト URI に基づいて location が検索されます。
  • 見つかった location 内で指定されたこのモジュールのディレクティブは、順番に実行されます。
  • リクエスト URI が rewrite された場合、ループは繰り返されますが、10回を超えることはありません。

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

ディレクティブが location 内で指定されている場合、リクエストのさらなる処理はこの location で続行されます。

例

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

指定された 条件 が評価されます。 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 ディレクティブによって設定されます。

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

バージョン 0.8.42 以降、リダイレクト URL（コード 301、302、303、307、および 308 の場合）またはレスポンス本文 テキスト（他のコードの場合）のいずれかを指定できます。レスポンス本文テキストとリダイレクト URL には変数を含めることができます。特別な場合として、リダイレクト URL をこのサーバーのローカル URI として指定できます。この場合、完全なリダイレクト 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、および 500〜504。

コード 307 は、バージョン 1.1.16 および 1.0.13 まではリダイレクトとして扱われませんでした。

コード 308 は、バージョン 1.13.0 まではリダイレクトとして扱われませんでした。

error_page ディレクティブも参照してください。

指定された正規表現がリクエスト URI と一致する場合、URI は 置換文字列 で指定されたとおりに変更されます。 rewrite ディレクティブは、設定ファイルでの出現順に順番に実行されます。フラグを使用してディレクティブのさらなる処理を終了することができます。置換文字列が「http://」、「https://」、または「$scheme」で始まる場合、処理は停止し、リダイレクトがクライアントに返されます。

オプションの フラグ パラメーターは、次のいずれかになります。

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

置換文字列 に新しいリクエスト引数が含まれている場合、以前のリクエスト引数がそれらの後に追加されます。これが望ましくない場合は、置換文字列の末尾に疑問マークを付けることで、追加されないようにすることができます。例：

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

正規表現に「}」または「;」文字が含まれている場合、式全体を一重引用符または二重引用符で囲む必要があります。

rewrite_log off;

ngx_http_rewrite_module モジュールディレクティブの処理結果の error_log へのロギングを notice レベルで有効または無効にします。

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

uninitialized_variable_warn on;

初期化されていない変数に関する警告をログに記録するかどうかを制御します。

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;

は、正規表現の最初のスラッシュをかっこ内に配置すると、命令を 1 つ減らすことができます。

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