モジュール ngx_http_proxy_module

ngx_http_proxy_moduleモジュールは、リクエストを別のサーバーに渡すことができます。

location / {
    proxy_pass       http://localhost:8000;
    proxy_set_header Host      $host;
    proxy_set_header X-Real-IP $remote_addr;
}

プロキシされたサーバーへの発信接続を、指定されたローカルIPアドレスとオプションのポート（1.11.2）から発信するようにします。パラメーター値には変数を含めることができます（1.3.12）。特殊値off（1.3.12）は、前の設定レベルから継承されたproxy_bindディレクティブの効果をキャンセルし、システムがローカルIPアドレスとポートを自動的に割り当てることができます。

transparentパラメーター（1.11.0）を使用すると、プロキシされたサーバーへの発信接続は、非ローカルIPアドレス（例：クライアントの実際のIPアドレス）から発信されます。

proxy_bind $remote_addr transparent;

このパラメーターを機能させるには、通常、nginxワーカープロセスをスーパーユーザー権限で実行する必要があります。Linuxでは、transparentパラメーターが指定されている場合、ワーカープロセスはマスタープロセスからCAP_NET_RAW機能を継承するため、必要ありません（1.13.8）。プロキシされたサーバーからのネットワークトラフィックをインターセプトするには、カーネルルーティングテーブルの設定も必要です。

proxy_buffer_size 4k|8k;

プロキシされたサーバーから受信した応答の最初の部分を読み取るために使用されるバッファーのサイズを設定します。この部分は通常、小さな応答ヘッダーが含まれています。デフォルトでは、バッファーサイズは1つのメモリページと同じです。これはプラットフォームに応じて4Kまたは8Kです。ただし、小さくすることもできます。

proxy_buffering on;

プロキシされたサーバーからの応答のバッファリングを有効または無効にします。

バッファリングが有効になっている場合、nginxはproxy_buffer_sizeおよびproxy_buffersディレクティブによって設定されたバッファーに保存することで、できるだけ早くプロキシされたサーバーから応答を受信します。応答全体がメモリに収まらない場合、その一部はディスク上の一時ファイルに保存される可能性があります。一時ファイルへの書き込みは、proxy_max_temp_file_sizeおよびproxy_temp_file_write_sizeディレクティブによって制御されます。

バッファリングが無効になっている場合、応答は受信されるとすぐに、同期的にクライアントに渡されます。nginxはプロキシされたサーバーから応答全体を読み取ろうとしません。nginxがサーバーから一度に受信できるデータの最大サイズは、proxy_buffer_sizeディレクティブによって設定されます。

バッファリングは、「X-Accel-Buffering」応答ヘッダーフィールドに「yes」または「no」を渡すことによっても有効または無効にできます。この機能は、proxy_ignore_headersディレクティブを使用して無効にできます。

proxy_buffers 8 4k|8k;

単一の接続に対して、プロキシされたサーバーからの応答を読み取るために使用されるバッファーの数とサイズを設定します。デフォルトでは、バッファーサイズは1つのメモリページと同じです。これはプラットフォームに応じて4Kまたは8Kです。

proxy_busy_buffers_size 8k|16k;

プロキシされたサーバーからの応答のバッファリングが有効になっている場合、応答がまだ完全に読み取られていない間に、クライアントへの応答の送信にビジー状態になることができるバッファーの合計サイズを制限します。その間、残りのバッファーは応答の読み取りに使用でき、必要に応じて、応答の一部を一時ファイルにバッファリングできます。デフォルトでは、サイズは、proxy_buffer_sizeおよびproxy_buffersディレクティブによって設定された2つのバッファーのサイズによって制限されます。

proxy_cache off;

キャッシングに使用される共有メモリゾーンを定義します。同じゾーンを複数の場所で使用する事ができます。パラメーター値には変数を含めることができます（1.7.9）。offパラメーターは、前の設定レベルから継承されたキャッシングを無効にします。

proxy_cache_background_update off;

期限切れのキャッシュアイテムを更新するためのバックグラウンドサブリクエストを開始できます。古いキャッシュされた応答がクライアントに返される間、バックグラウンドで更新が行われます。許可されている場合、古いキャッシュされた応答の使用が可能です。

応答がキャッシュから取得されない条件を定義します。文字列パラメーターの値の少なくとも1つが空でない場合、または「0」と等しくない場合、応答はキャッシュから取得されません。

proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
proxy_cache_bypass $http_pragma    $http_authorization;

proxy_no_cacheディレクティブと共に使用できます。

proxy_cache_convert_head on;

キャッシングのために「HEAD」メソッドを「GET」に変換するかどうかを有効または無効にします。変換が無効になっている場合、キャッシュキーに$request_methodを含める必要があります。

proxy_cache_key $scheme$proxy_host$request_uri;

キャッシングのキーを定義します。例:

proxy_cache_key "$host$request_uri $cookie_user";

デフォルトでは、ディレクティブの値は次の文字列に近いです。

proxy_cache_key $scheme$proxy_host$uri$is_args$args;

proxy_cache_lock off;

有効にすると、一度に1つのリクエストだけが、proxy_cache_keyディレクティブに従って識別された新しいキャッシュ要素に、プロキシされたサーバーへのリクエストを渡すことで、データを格納できます。同じキャッシュ要素の他のリクエストは、応答がキャッシュに表示されるまで、またはこの要素のキャッシュロックがproxy_cache_lock_timeoutディレクティブで設定された時間まで解放されるまで待ちます。

proxy_cache_lock_age 5s;

新しいキャッシュ要素を格納するためにプロキシされたサーバーに渡された最後のリクエストが、指定された時間内に完了していない場合、プロキシされたサーバーにさらに1つのリクエストを渡すことができます。

proxy_cache_lock_timeout 5s;

proxy_cache_lockのタイムアウトを設定します。時間が経過すると、リクエストはプロキシされたサーバーに渡されますが、応答はキャッシュされません。

1.7.8以前は、応答をキャッシュできました。

バイト範囲リクエストのオフセットをバイト単位で設定します。範囲がオフセットを超えている場合、範囲リクエストはプロキシされたサーバーに渡され、応答はキャッシュされません。

proxy_cache_methods GET HEAD;

クライアントのリクエストメソッドがこのディレクティブにリストされている場合、応答はキャッシュされます。「GET」と「HEAD」メソッドは常にリストに追加されますが、明示的に指定することをお勧めします。proxy_no_cacheディレクティブも参照してください。

proxy_cache_min_uses 1;

応答がキャッシュされるまでのリクエスト数を設定します。

キャッシュのパスと他のパラメーターを設定します。キャッシュデータはファイルに保存されます。キャッシュ内のファイル名は、キャッシュキーにMD5関数を適用した結果です。levelsパラメーターは、キャッシュの階層レベル（1〜3）を定義します。各レベルは1または2の値を取ります。例えば、次の設定では

proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;

キャッシュ内のファイル名は、次のようになります。

/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c

キャッシュされたレスポンスは、最初に一時ファイルに書き込まれ、その後、ファイル名が変更されます。バージョン0.8.9以降、一時ファイルとキャッシュは異なるファイルシステムに配置できます。ただし、この場合、安価な名前変更操作ではなく、ファイルが2つのファイルシステム間でコピーされることに注意してください。したがって、特定の場所について、キャッシュと一時ファイル保持ディレクトリの両方を同じファイルシステムに配置することをお勧めします。一時ファイルのディレクトリは、use_temp_path パラメータ (1.7.10) に基づいて設定されます。このパラメータが省略されているか、onに設定されている場合、指定された場所のproxy_temp_pathディレクティブによって設定されたディレクトリが使用されます。値がoffに設定されている場合、一時ファイルはキャッシュディレクトリに直接配置されます。

さらに、すべてのアクティブなキーとデータに関する情報は、keys_zoneパラメータで設定されたnameとsizeを持つ共有メモリゾーンに格納されます。1メガバイトのゾーンには、約8,000個のキーを格納できます。

商用サブスクリプションの一部として、共有メモリゾーンには拡張キャッシュ情報も格納されるため、同じ数のキーに対してより大きなゾーンサイズを指定する必要があります。たとえば、1メガバイトのゾーンには、約4,000個のキーを格納できます。

inactiveパラメータで指定された時間内にアクセスされなかったキャッシュデータは、その新鮮さに関係なくキャッシュから削除されます。デフォルトでは、inactiveは10分に設定されています。

特別な「キャッシュマネージャ」プロセスは、max_sizeパラメータで設定された最大キャッシュサイズと、キャッシュを含むファイルシステムでmin_free (1.19.1) パラメータで設定された最小空き容量を監視します。サイズを超過した場合、または空き容量が不足している場合、最近使用されていないデータが削除されます。データは、manager_files、manager_threshold、およびmanager_sleepパラメータ (1.11.5) で設定された反復処理で削除されます。1回の反復処理では、manager_filesアイテム（デフォルトは100）を超えるアイテムは削除されません。1回の反復処理の時間は、manager_thresholdパラメータ（デフォルトは200ミリ秒）によって制限されます。反復処理間には、manager_sleepパラメータ（デフォルトは50ミリ秒）で設定された一時停止が行われます。

開始後1分後に、特別な「キャッシュローダー」プロセスがアクティブになります。これは、ファイルシステムに保存されている以前にキャッシュされたデータに関する情報をキャッシュゾーンにロードします。ロードも反復処理で行われます。1回の反復処理では、loader_filesアイテム（デフォルトは100）を超えるアイテムはロードされません。また、1回の反復処理の時間は、loader_thresholdパラメータ（デフォルトは200ミリ秒）によって制限されます。反復処理間には、loader_sleepパラメータ（デフォルトは50ミリ秒）で設定された一時停止が行われます。

さらに、次のパラメータは商用サブスクリプションの一部として利用できます。

purger=on|off

ワイルドカードキーに一致するキャッシュエントリがキャッシュパージャー (1.7.12) によってディスクから削除されるかどうかを指示します。パラメータをonに設定すると（デフォルトはoff）、すべてのキャッシュエントリを繰り返し処理し、ワイルドカードキーに一致するエントリを永久的に削除する「キャッシュパージャー」プロセスがアクティブになります。

purger_files=数値

1回の反復処理中にスキャンされるアイテム数を設定します (1.7.12)。デフォルトでは、purger_filesは10に設定されています。

purger_threshold=数値

1回の反復処理の時間を設定します (1.7.12)。デフォルトでは、purger_thresholdは50ミリ秒に設定されています。

purger_sleep=数値

反復処理間の休止時間を設定します (1.7.12)。デフォルトでは、purger_sleepは50ミリ秒に設定されています。

バージョン1.7.3、1.7.7、および1.11.10では、キャッシュヘッダーの形式が変更されました。以前キャッシュされたレスポンスは、新しいnginxバージョンにアップグレードした後、無効と見なされます。

リクエストをキャッシュパージリクエストと見なす条件を定義します。文字列パラメータの値の少なくとも1つが空ではなく「0」と等しくない場合、対応するキャッシュキーを持つキャッシュエントリが削除されます。成功した操作の結果は、204（No Content）レスポンスを返すことで示されます。

パージリクエストのキャッシュキーがアスタリスク（「*」）で終わる場合、ワイルドカードキーに一致するすべてのキャッシュエントリがキャッシュから削除されます。ただし、これらのエントリは、非アクティブのために削除されるか、キャッシュパージャー (1.7.12) によって処理されるか、クライアントがアクセスしようとするまで、ディスクに残ります。

設定例

proxy_cache_path /data/nginx/cache keys_zone=cache_zone:10m;

map $request_method $purge_method {
    PURGE   1;
    default 0;
}

server {
    ...
    location / {
        proxy_pass http://backend;
        proxy_cache cache_zone;
        proxy_cache_key $uri;
        proxy_cache_purge $purge_method;
    }
}

この機能は商用サブスクリプションの一部として利用できます。

proxy_cache_revalidate off;

「If-Modified-Since」および「If-None-Match」ヘッダーフィールドを使用した条件付きリクエストを使用して、期限切れのキャッシュアイテムの再検証を有効にします。

proxy_cache_use_stale off;

proxy_next_upstreamディレクティブのパラメータと一致する、プロキシされたサーバーとの通信中に古いキャッシュされたレスポンスを使用できる場合を決定します。

errorパラメータは、リクエストを処理するプロキシサーバーを選択できない場合にも、古いキャッシュされたレスポンスの使用を許可します。

さらに、updatingパラメータは、現在更新中の場合に古いキャッシュされたレスポンスの使用を許可します。これにより、キャッシュデータを更新するときのプロキシサーバーへのアクセスの回数を最小限に抑えることができます。

古いキャッシュされたレスポンスの使用は、レスポンスが古くなった後、指定された秒数でレスポンスヘッダーで直接有効にすることもできます (1.11.10)。これは、ディレクティブパラメータを使用するよりも優先順位が低くなります。

• 「stale-while-revalidate」の「Cache-Control」ヘッダーフィールドの拡張機能は、現在更新中の場合に古いキャッシュレスポンスの使用を許可します。
• 「stale-if-error」の「Cache-Control」ヘッダーフィールドの拡張機能は、エラーが発生した場合に古いキャッシュされたレスポンスの使用を許可します。

新しいキャッシュ要素を移入するときのプロキシサーバーへのアクセスの回数を最小限に抑えるために、proxy_cache_lockディレクティブを使用できます。

さまざまなレスポンスコードのキャッシュ時間を設定します。たとえば、次のディレクティブ

proxy_cache_valid 200 302 10m;
proxy_cache_valid 404      1m;

は、コード200と302のレスポンスに対して10分のキャッシュ、コード404のレスポンスに対して1分のキャッシュを設定します。

キャッシュ時間のみが指定されている場合

proxy_cache_valid 5m;

は、200、301、および302のレスポンスのみがキャッシュされます。

さらに、任意のレスポンスをキャッシュするためにanyパラメータを指定できます。

proxy_cache_valid 200 302 10m;
proxy_cache_valid 301      1h;
proxy_cache_valid any      1m;

キャッシュのパラメータは、レスポンスヘッダーで直接設定することもできます。これは、ディレクティブを使用してキャッシュ時間を設定するよりも優先順位が高くなります。

• 「X-Accel-Expires」ヘッダーフィールドは、レスポンスのキャッシュ時間を秒単位で設定します。ゼロの値は、レスポンスのキャッシュを無効にします。値が@プレフィックスで始まる場合、エポックからの秒単位の絶対時間を設定し、その時間までレスポンスをキャッシュできます。
• ヘッダーに「X-Accel-Expires」フィールドが含まれていない場合、キャッシュのパラメータは「Expires」または「Cache-Control」ヘッダーフィールドに設定できます。
• ヘッダーに「Set-Cookie」フィールドが含まれている場合、そのようなレスポンスはキャッシュされません。
• ヘッダーに特別な値「*」を含む「Vary」フィールドが含まれている場合、そのようなレスポンスはキャッシュされません (1.7.7)。ヘッダーに別の値を含む「Vary」フィールドが含まれている場合、そのようなレスポンスは、対応するリクエストヘッダーフィールドを考慮してキャッシュされます (1.7.7)。

これらのレスポンスヘッダーフィールドの1つ以上を処理することは、proxy_ignore_headersディレクティブを使用して無効にできます。

proxy_connect_timeout 60s;

プロキシされたサーバーとの接続確立のタイムアウトを定義します。通常、このタイムアウトは75秒を超えることはできません。

proxy_cookie_domain off;

プロキシされたサーバーレスポンスの「Set-Cookie」ヘッダーフィールドのdomain属性で変更する必要があるテキストを設定します。プロキシされたサーバーが「domain=localhost」属性を持つ「Set-Cookie」ヘッダーフィールドを返したとします。このディレクティブは

proxy_cookie_domain localhost example.org;

この属性を「domain=example.org」に書き換えます。

ドメインおよび置換文字列文字列の先頭にあるドットとdomain属性は無視されます。照合は大文字と小文字を区別しません。

ドメインおよび置換文字列文字列には変数を含めることができます。

proxy_cookie_domain www.$host $host;

このディレクティブは、正規表現を使用して指定することもできます。この場合、ドメインは「〜」記号で始まる必要があります。正規表現には、名前付きキャプチャと位置指定キャプチャを含めることができ、置換文字列はそれらを参照できます。

proxy_cookie_domain ~\.(?P<sl_domain>[-0-9a-z]+\.[a-z]+)$ $sl_domain;

同じレベルに複数のproxy_cookie_domainディレクティブを指定できます。

proxy_cookie_domain localhost example.org;
proxy_cookie_domain ~\.([a-z]+\.[a-z]+)$ $1;

複数のディレクティブをクッキーに適用できる場合、最初に一致するディレクティブが選択されます。

offパラメータは、前の設定レベルから継承されたproxy_cookie_domainディレクティブの効果をキャンセルします。

proxy_cookie_flags off;

クッキーに1つ以上のフラグを設定します。クッキーには、テキスト、変数、およびそれらの組み合わせを含めることができます。フラグには、テキスト、変数、およびそれらの組み合わせを含めることができます (1.19.8)。secure、httponly、samesite=strict、samesite=lax、samesite=noneパラメータは、対応するフラグを追加します。nosecure、nohttponly、nosamesiteパラメータは、対応するフラグを削除します。

クッキーは、正規表現を使用して指定することもできます。この場合、クッキーは「〜」記号で始まる必要があります。

同じ設定レベルに複数のproxy_cookie_flagsディレクティブを指定できます。

proxy_cookie_flags one httponly;
proxy_cookie_flags ~ nosecure samesite=strict;

複数のディレクティブをクッキーに適用できる場合、最初に一致するディレクティブが選択されます。例では、httponlyフラグがクッキーoneに追加され、他のすべてのクッキーにはsamesite=strictフラグが追加され、secureフラグが削除されます。

offパラメータは、前の設定レベルから継承されたproxy_cookie_flagsディレクティブの効果をキャンセルします。

proxy_cookie_path off;

プロキシされたサーバーレスポンスの「Set-Cookie」ヘッダーフィールドのpath属性で変更する必要があるテキストを設定します。プロキシされたサーバーが「path=/two/some/uri/」属性を持つ「Set-Cookie」ヘッダーフィールドを返したとします。このディレクティブは

proxy_cookie_path /two/ /;

この属性を「path=/some/uri/」に書き換えます。

パスおよび置換文字列文字列には変数を含めることができます。

proxy_cookie_path $uri /some$uri;

このディレクティブは、正規表現を使用して指定することもできます。この場合、パスは大文字と小文字を区別する照合の場合は「〜」記号で、大文字と小文字を区別しない照合の場合は「〜*」記号で始まる必要があります。正規表現には、名前付きキャプチャと位置指定キャプチャを含めることができ、置換文字列はそれらを参照できます。

proxy_cookie_path ~*^/user/([^/]+) /u/$1;

同じレベルに複数のproxy_cookie_pathディレクティブを指定できます。

proxy_cookie_path /one/ /;
proxy_cookie_path / /two/;

複数のディレクティブをクッキーに適用できる場合、最初に一致するディレクティブが選択されます。

offパラメータは、前の設定レベルから継承されたproxy_cookie_pathディレクティブの効果をキャンセルします。

proxy_force_ranges off;

これらのレスポンスの「Accept-Ranges」フィールドに関係なく、プロキシされたサーバーからのキャッシュされたレスポンスとキャッシュされていないレスポンスの両方のバイト範囲サポートを有効にします。

proxy_headers_hash_bucket_size 64;

proxy_hide_headerおよびproxy_set_headerディレクティブで使用されるハッシュテーブルのバケットサイズを設定します。ハッシュテーブルの設定の詳細については、別のドキュメントに記載されています。

proxy_headers_hash_max_size 512;

proxy_hide_header ディレクティブと proxy_set_header ディレクティブで使用されるハッシュテーブルの最大sizeを設定します。ハッシュテーブルの設定の詳細については、別のドキュメントに記載されています。

デフォルトでは、nginx はプロキシされたサーバーのレスポンスから「Date」、「Server」、「X-Pad」、「X-Accel-...」ヘッダーフィールドをクライアントに渡しません。proxy_hide_header ディレクティブは、渡されない追加のフィールドを設定します。逆に、フィールドの渡しが許可される必要がある場合は、proxy_pass_header ディレクティブを使用できます。

proxy_http_version 1.0;

プロキシのHTTPプロトコルバージョンを設定します。デフォルトではバージョン1.0が使用されます。バージョン1.1は、キープアライブ接続とNTLM認証と共に使用することをお勧めします。

proxy_ignore_client_abort off;

クライアントがレスポンスを待たずに接続を閉じるときに、プロキシされたサーバーとの接続を閉じるかどうかを決定します。

プロキシされたサーバーからの特定のレスポンスヘッダーフィールドの処理を無効にします。「X-Accel-Redirect」、「X-Accel-Expires」、「X-Accel-Limit-Rate」(1.1.6)、「X-Accel-Buffering」(1.1.6)、「X-Accel-Charset」(1.1.6)、「Expires」、「Cache-Control」、「Set-Cookie」(0.8.44)、「Vary」(1.7.7) のフィールドを無視できます。

無効にされていない場合、これらのヘッダーフィールドの処理は次の効果があります。

• 「X-Accel-Expires」、「Expires」、「Cache-Control」、「Set-Cookie」、「Vary」は、レスポンスのキャッシングパラメータを設定します。
• 「X-Accel-Redirect」は、指定されたURIへの内部リダイレクトを実行します。
• 「X-Accel-Limit-Rate」は、クライアントへのレスポンス送信のレート制限を設定します。
• 「X-Accel-Buffering」は、レスポンスのバッファリングを有効または無効にします。
• 「X-Accel-Charset」は、レスポンスの目的の文字セットを設定します。

proxy_intercept_errors off;

300以上のコードを持つプロキシされたレスポンスをクライアントに渡すか、インターセプトしてnginxにリダイレクトしてerror_pageディレクティブで処理するかどうかを決定します。

proxy_limit_rate 0;

プロキシされたサーバーからのレスポンスの読み取り速度を制限します。rateは、秒あたりのバイト数で指定されます。ゼロ値はレート制限を無効にします。制限はリクエストごとに設定されるため、nginxがプロキシされたサーバーに同時に2つの接続を開くと、全体レートは指定された制限の2倍になります。バッファリングが有効になっている場合のみ、制限が機能します。パラメータ値には変数を含めることができます(1.27.0)。

proxy_max_temp_file_size 1024m;

バッファリングが有効になっている場合、レスポンス全体がproxy_buffer_sizeおよびproxy_buffersディレクティブで設定されたバッファに収まらない場合、レスポンスの一部を一時ファイルに保存できます。このディレクティブは、一時ファイルの最大sizeを設定します。一度に一時ファイルに書き込まれるデータのサイズは、proxy_temp_file_write_sizeディレクティブで設定されます。

ゼロ値は、レスポンスの一時ファイルへのバッファリングを無効にします。

この制限は、ディスクにキャッシュまたは保存されるレスポンスには適用されません。

クライアントリクエストからのメソッドではなく、プロキシされたサーバーに転送されるリクエストで使用するHTTPmethodを指定します。パラメータ値には変数を含めることができます(1.11.6)。

proxy_next_upstream error timeout;

リクエストを次のサーバーに渡す場合を指定します。

error

サーバーとの接続確立、リクエストの送信、またはレスポンスヘッダーの読み取り中にエラーが発生した場合。

timeout

サーバーとの接続確立、リクエストの送信、またはレスポンスヘッダーの読み取り中にタイムアウトが発生した場合。

invalid_header

サーバーが空または無効なレスポンスを返した場合。

http_500

サーバーがコード500のレスポンスを返した場合。

http_502

サーバーがコード502のレスポンスを返した場合。

http_503

サーバーがコード503のレスポンスを返した場合。

http_504

サーバーがコード504のレスポンスを返した場合。

http_403

サーバーがコード403のレスポンスを返した場合。

http_404

サーバーがコード404のレスポンスを返した場合。

http_429

サーバーがコード429のレスポンスを返した場合 (1.11.13)。

non_idempotent

通常、べき等でないメソッド (POST、LOCK、PATCH) を持つリクエストは、アップストリームサーバーにリクエストが送信されている場合、次のサーバーに渡されません (1.9.13)。このオプションを明示的に有効にすると、そのようなリクエストの再試行が許可されます。

off

リクエストを次のサーバーに渡すことを無効にします。

クライアントにまだ何も送信されていない場合のみ、リクエストを次のサーバーに渡すことができることに注意してください。つまり、レスポンスの転送中にエラーまたはタイムアウトが発生した場合、修正することはできません。

このディレクティブは、サーバーとの通信の失敗した試行と見なされるものを定義します。error、timeout、invalid_header の場合は、ディレクティブに指定されていなくても常に失敗した試行と見なされます。http_500、http_502、http_503、http_504、http_429 の場合は、ディレクティブに指定されている場合のみ失敗した試行と見なされます。http_403 と http_404 の場合は、決して失敗した試行とは見なされません。

リクエストを次のサーバーに渡すことは、試行回数と時間によって制限できます。

proxy_next_upstream_timeout 0;

次のサーバーにリクエストを渡すことができる時間を制限します。0値はこの制限をオフにします。

proxy_next_upstream_tries 0;

次のサーバーにリクエストを渡すことができる試行回数を制限します。0値はこの制限をオフにします。

レスポンスがキャッシュに保存されない条件を定義します。文字列パラメータの値が少なくとも1つ空ではなく「0」と等しくない場合、レスポンスは保存されません。

proxy_no_cache $cookie_nocache $arg_nocache$arg_comment;
proxy_no_cache $http_pragma    $http_authorization;

proxy_cache_bypassディレクティブと併用できます。

プロキシされたサーバーのプロトコルとアドレス、およびロケーションをマッピングするオプションのURIを設定します。プロトコルとして「http」または「https」を指定できます。アドレスはドメイン名またはIPアドレス、およびオプションのポートとして指定できます。

proxy_pass http://localhost:8000/uri/;

または、「unix」の後に指定され、コロンで囲まれたUNIXドメインソケットパスとして指定できます。

proxy_pass http://unix:/tmp/backend.socket:/uri/;

ドメイン名が複数のアドレスに解決される場合、それらはすべてラウンドロビン方式で使用されます。さらに、アドレスはサーバーグループとして指定できます。

パラメータ値には変数を含めることができます。この場合、アドレスがドメイン名として指定されていると、その名前は記述されているサーバーグループ内で検索され、見つからない場合はresolverを使用して決定されます。

リクエストURIは次のようにサーバーに渡されます。

• proxy_passディレクティブがURI付きで指定されている場合、リクエストがサーバーに渡されるときに、ロケーションに一致する正規化されたリクエストURIの部分が、ディレクティブで指定されたURIに置き換えられます。

  location /name/ {
      proxy_pass http://127.0.0.1/remote/;
  }
  

• proxy_passがURIなしで指定されている場合、リクエストURIは、元のリクエストが処理されるときにクライアントによって送信されたのと同じ形式でサーバーに渡されます。または、変更されたURIの処理時に完全な正規化されたリクエストURIが渡されます。

  location /some/path/ {
      proxy_pass http://127.0.0.1;
  }
  

  バージョン1.1.12より前では、proxy_passがURIなしで指定されている場合、変更されたURIの代わりに元のリクエストURIが渡される可能性があります。

場合によっては、置き換えられるリクエストURIの部分を決定できない場合があります。

• 正規表現を使用してロケーションが指定されている場合、および名前付きロケーション内にも指定されている場合。

  これらの場合、proxy_passはURIなしで指定する必要があります。

• rewriteディレクティブを使用してプロキシされたロケーション内でURIが変更され、同じ設定がリクエストの処理に使用される場合 (break)。

  location /name/ {
      rewrite    /name/([^/]+) /users?name=$1 break;
      proxy_pass http://127.0.0.1;
  }
  

  この場合、ディレクティブで指定されたURIは無視され、変更された完全なリクエストURIがサーバーに渡されます。

• proxy_passで変数が使用されている場合。

  location /name/ {
      proxy_pass http://127.0.0.1$request_uri;
  }
  

  この場合、ディレクティブでURIが指定されていると、元のリクエストURIを置き換えて、そのままサーバーに渡されます。

WebSocketプロキシには特別な設定が必要であり、バージョン1.3.13以降でサポートされています。

プロキシされたサーバーからクライアントに無効化されたヘッダーフィールドを渡すことを許可します。

proxy_pass_request_body on;

元のリクエストボディがプロキシされたサーバーに渡されるかどうかを示します。

location /x-accel-redirect-here/ {
    proxy_method GET;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";

    proxy_pass ...
}

proxy_set_headerおよびproxy_pass_request_headersディレクティブも参照してください。

proxy_pass_request_headers on;

元のリクエストのヘッダーフィールドがプロキシされたサーバーに渡されるかどうかを示します。

location /x-accel-redirect-here/ {
    proxy_method GET;
    proxy_pass_request_headers off;
    proxy_pass_request_body off;

    proxy_pass ...
}

proxy_set_headerおよびproxy_pass_request_bodyディレクティブも参照してください。

proxy_pass_trailers off;

プロキシされたサーバーからクライアントへのトレーラーフィールドの受け渡しを許可します。

HTTP/1.1のトレーラーセクションは明示的に有効化されています。

location / {
    proxy_http_version 1.1;
    proxy_set_header Connection "te";
    proxy_set_header TE "trailers";
    proxy_pass_trailers on;

    proxy_pass ...
}

proxy_read_timeout 60s;

プロキシされたサーバーからのレスポンスの読み取りのタイムアウトを定義します。タイムアウトは、2つの連続した読み取り操作の間でのみ設定され、レスポンス全体の送信には設定されません。プロキシされたサーバーがこの時間内に何も送信しないと、接続が閉じられます。

proxy_redirect default;

プロキシされたサーバーレスポンスの「Location」と「Refresh」ヘッダーフィールドで変更する必要があるテキストを設定します。プロキシされたサーバーが「Location: http://localhost:8000/two/some/uri/」ヘッダーフィールドを返したとします。ディレクティブ

proxy_redirect http://localhost:8000/two/ http://frontend/one/;

は、この文字列を「Location: http://frontend/one/some/uri/」に書き換えます。

replacement文字列では、サーバー名を省略できます。

proxy_redirect http://localhost:8000/two/ /;

その場合、80とは異なる場合、プライマリサーバーの名前とポートが挿入されます。

defaultパラメータで指定されたデフォルトの置換は、locationおよびproxy_passディレクティブのパラメータを使用します。したがって、以下の2つの設定は同等です。

location /one/ {
    proxy_pass     http://upstream:port/two/;
    proxy_redirect default;

location /one/ {
    proxy_pass     http://upstream:port/two/;
    proxy_redirect http://upstream:port/two/ /one/;

変数を使用してproxy_passが指定されている場合は、defaultパラメータは許可されません。

replacement文字列には変数を含めることができます。

proxy_redirect http://localhost:8000/ http://$host:$server_port/;

redirectにも変数を含めることができます (1.1.11)。

proxy_redirect http://$proxy_host:8000/ /;

このディレクティブは、正規表現を使用して指定できます(1.1.11)。この場合、redirect は、大文字と小文字を区別するマッチングの場合は「~」記号で始まり、大文字と小文字を区別しないマッチングの場合は「~*」記号で始まる必要があります。正規表現には、名前付きキャプチャと位置指定キャプチャを含めることができ、replacement はそれらを参照できます。

proxy_redirect ~^(http://[^:]+):\d+(/.+)$ $1$2;
proxy_redirect ~*/user/([^/]+)/(.+)$      http://$1.example.com/$2;

同じレベルで複数のproxy_redirectディレクティブを指定できます。

proxy_redirect default;
proxy_redirect http://localhost:8000/  /;
proxy_redirect http://www.example.com/ /;

プロキシされたサーバー応答のヘッダーフィールドに複数のディレクティブを適用できる場合、最初に一致するディレクティブが選択されます。

offパラメータは、前の設定レベルから継承されたproxy_redirectディレクティブの効果をキャンセルします。

このディレクティブを使用すると、プロキシされたサーバーによって発行された相対リダイレクトにホスト名を追加することもできます。

proxy_redirect / /;

proxy_request_buffering on;

クライアントリクエストボディのバッファリングを有効または無効にします。

バッファリングが有効になっている場合、リクエスト全体が、プロキシされたサーバーにリクエストを送信する前に、クライアントから読み取られます。

バッファリングが無効になっている場合、リクエストボディは受信されるとすぐにプロキシされたサーバーに送信されます。この場合、nginxがすでにリクエストボディの送信を開始している場合、リクエストを次のサーバーに渡すことはできません。

元のリクエストボディの送信にHTTP/1.1チャンク転送エンコーディングが使用されている場合、プロキシのためにHTTP/1.1が有効になっていない限り、ディレクティブの値に関係なく、リクエストボディはバッファリングされます。

proxy_send_lowat 0;

このディレクティブがゼロ以外の値に設定されている場合、nginxは、kqueueメソッドのNOTE_LOWATフラグ、またはSO_SNDLOWATソケットオプションを使用して、指定されたsizeで、プロキシされたサーバーへの送信接続の送信操作回数を最小限に抑えようとします。

このディレクティブは、Linux、Solaris、およびWindowsでは無視されます。

proxy_send_timeout 60s;

プロキシされたサーバーへのリクエストの送信タイムアウトを設定します。タイムアウトは、2回の連続した書き込み操作の間でのみ設定され、リクエスト全体の送信時間ではありません。この時間内にプロキシされたサーバーが何も受信しないと、接続は閉じられます。

プロキシされたサーバーに渡されるリクエストボディを再定義できます。valueには、テキスト、変数、およびそれらの組み合わせを含めることができます。

proxy_set_header Host $proxy_host;

proxy_set_header Connection close;

プロキシされたサーバーに渡されるリクエストヘッダーのフィールドを再定義または追加できます。valueには、テキスト、変数、およびそれらの組み合わせを含めることができます。これらのディレクティブは、現在のレベルにproxy_set_headerディレクティブが定義されていない場合にのみ、前の設定レベルから継承されます。デフォルトでは、2つのフィールドのみが再定義されます。

proxy_set_header Host       $proxy_host;
proxy_set_header Connection close;

キャッシングが有効になっている場合、元のリクエストからの「If-Modified-Since」、「If-Unmodified-Since」、「If-None-Match」、「If-Match」、「Range」、「If-Range」ヘッダーフィールドは、プロキシされたサーバーに渡されません。

変更されていない「Host」リクエストヘッダーフィールドは、次のように渡すことができます。

proxy_set_header Host       $http_host;

ただし、このフィールドがクライアントリクエストヘッダーに存在しない場合、何も渡されません。そのような場合、$host変数を使用する方が良いでしょう。その値は、「Host」リクエストヘッダーフィールドのサーバー名、またはこのフィールドが存在しない場合はプライマリサーバー名と等しくなります。

proxy_set_header Host       $host;

さらに、プロキシされたサーバーのポートとともにサーバー名を渡すことができます。

proxy_set_header Host       $host:$proxy_port;

ヘッダーフィールドの値が空文字列の場合、そのフィールドはプロキシされたサーバーに渡されません。

proxy_set_header Accept-Encoding "";

proxy_socket_keepalive off;

プロキシされたサーバーへの送信接続の「TCP keepalive」動作を設定します。デフォルトでは、オペレーティングシステムの設定がソケットに適用されます。ディレクティブが「on」に設定されている場合、ソケットのSO_KEEPALIVEソケットオプションがオンになります。

プロキシされたHTTPSサーバーへの認証に使用されるPEM形式の証明書を含むfileを指定します。

バージョン1.21.0以降、file名に変数を使用できます。

プロキシされたHTTPSサーバーへの認証に使用されるPEM形式の秘密鍵を含むfileを指定します。

fileの代わりに、engine:name:idを指定できます(1.7.9)。これは、OpenSSLエンジンnameから指定されたidを持つ秘密鍵を読み込みます。

バージョン1.21.0以降、file名に変数を使用できます。

proxy_ssl_ciphers DEFAULT;

プロキシされたHTTPSサーバーへのリクエストに対して有効な暗号を指定します。暗号は、OpenSSLライブラリによって理解される形式で指定されます。

完全なリストは、「openssl ciphers」コマンドを使用して表示できます。

プロキシされたHTTPSサーバーとの接続を確立するときに、任意のOpenSSL設定コマンドを設定します。

このディレクティブは、OpenSSL 1.0.2以降を使用する場合にサポートされます。

同じレベルで複数のproxy_ssl_conf_commandディレクティブを指定できます。これらのディレクティブは、現在のレベルにproxy_ssl_conf_commandディレクティブが定義されていない場合にのみ、前の設定レベルから継承されます。

OpenSSLを直接構成すると、予期しない動作が発生する可能性があることに注意してください。

プロキシされたHTTPSサーバーの証明書を検証するために使用されるPEM形式の失効証明書(CRL)を含むfileを指定します。

プロキシされたHTTPSサーバー接続のSSLキーのログを有効にし、キーログファイルへのパスを指定します。キーは、Wiresharkと互換性のあるSSLKEYLOGFILE形式でログに記録されます。

このディレクティブは、当社の商用サブスクリプションの一部として利用できます。

proxy_ssl_name $proxy_host;

プロキシされたHTTPSサーバーの証明書の検証に使用されるサーバー名をオーバーライドし、プロキシされたHTTPSサーバーとの接続を確立するときにSNIを介して渡すことができます。

デフォルトでは、proxy_pass URLのホスト部分が使用されます。

秘密鍵のパスフレーズを含むfileを指定します。各パスフレーズは別々の行に指定されます。キーの読み込み時に、パスフレーズが順番に試行されます。

proxy_ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;

プロキシされたHTTPSサーバーへのリクエストに対して指定されたプロトコルを有効にします。

TLSv1.3パラメータは、1.23.4以降、デフォルトで使用されます。

proxy_ssl_server_name off;

プロキシされたHTTPSサーバーとの接続を確立するときに、TLSサーバー名表示拡張機能(SNI、RFC 6066)を介したサーバー名の渡しの有効化または無効化を行います。

proxy_ssl_session_reuse on;

プロキシされたサーバーとの作業時にSSLセッションを再利用できるかどうかを決定します。ログに「SSL3_GET_FINISHED:digest check failed」というエラーが表示される場合は、セッションの再利用を無効にしてみてください。

プロキシされたHTTPSサーバーの証明書を検証するために使用されるPEM形式の信頼できるCA証明書を含むfileを指定します。

proxy_ssl_verify off;

プロキシされたHTTPSサーバー証明書の検証を有効または無効にします。

proxy_ssl_verify_depth 1;

プロキシされたHTTPSサーバー証明書チェーンの検証深度を設定します。

proxy_store off;

ディスクへのファイルの保存を有効にします。onパラメータは、aliasまたはrootディレクティブに対応するパスを持つファイルを保存します。offパラメータはファイルの保存を無効にします。さらに、変数を使用してstringでファイル名を明示的に設定できます。

proxy_store /data/www$original_uri;

ファイルの変更時刻は、受信した「Last-Modified」応答ヘッダーフィールドに従って設定されます。応答は最初にテンポラリファイルに書き込まれ、その後ファイルの名前が変更されます。バージョン0.8.9以降、テンポラリファイルと永続ストレージを異なるファイルシステムに配置できます。ただし、この場合、安価な名前変更操作ではなく、ファイルが2つのファイルシステム間でコピーされることに注意してください。したがって、特定の場所では、保存されたファイルとproxy_temp_pathディレクティブによって設定されたテンポラリファイルを含むディレクトリの両方を同じファイルシステムに配置することをお勧めします。

このディレクティブを使用して、変更不可能な静的ファイルのローカルコピーを作成できます。例：

location /images/ {
    root               /data/www;
    error_page         404 = /fetch$uri;
}

location /fetch/ {
    internal;

    proxy_pass         http://backend/;
    proxy_store        on;
    proxy_store_access user:rw group:rw all:r;
    proxy_temp_path    /data/temp;

    alias              /data/www/;
}

または、次のようにします。

location /images/ {
    root               /data/www;
    error_page         404 = @fetch;
}

location @fetch {
    internal;

    proxy_pass         http://backend;
    proxy_store        on;
    proxy_store_access user:rw group:rw all:r;
    proxy_temp_path    /data/temp;

    root               /data/www;
}

proxy_store_access user:rw;

新しく作成されたファイルとディレクトリのアクセス許可を設定します。例：

proxy_store_access user:rw group:rw all:r;

groupまたはallのアクセス許可が指定されている場合、userの許可は省略できます。

proxy_store_access group:rw all:r;

proxy_temp_file_write_size 8k|16k;

プロキシされたサーバーからの応答をテンポラリファイルにバッファリングする際に、一度にテンポラリファイルに書き込まれるデータのsizeを制限します。デフォルトでは、sizeはproxy_buffer_sizeおよびproxy_buffersディレクティブによって設定された2つのバッファによって制限されます。テンポラリファイルの最大サイズは、proxy_max_temp_file_sizeディレクティブによって設定されます。

proxy_temp_path proxy_temp;

プロキシされたサーバーから受信したデータを含むテンポラリファイルを保存するためのディレクトリを定義します。指定されたディレクトリの下に、最大3レベルのサブディレクトリ階層を使用できます。たとえば、次の構成では

proxy_temp_path /spool/nginx/proxy_temp 1 2;

テンポラリファイルは次のようになります。

/spool/nginx/proxy_temp/7/45/00000123457

proxy_cache_pathディレクティブのuse_temp_pathパラメータも参照してください。

ngx_http_proxy_moduleモジュールは、proxy_set_headerディレクティブを使用してヘッダーを構成するために使用できる埋め込み変数をサポートしています。

$proxy_host

proxy_passディレクティブで指定されたプロキシサーバーの名称とポート。

$proxy_port

proxy_passディレクティブで指定されたプロキシサーバーのポート、またはプロトコルのデフォルトポート。

$proxy_add_x_forwarded_for

$remote_addr変数をカンマで区切って追加した“X-Forwarded-For”クライアントリクエストヘッダーフィールド。クライアントリクエストヘッダーに“X-Forwarded-For”フィールドが存在しない場合、$proxy_add_x_forwarded_for変数は$remote_addr変数と等しくなります。