ngx_http_proxy_module モジュール

設定例
ディレクティブ
     proxy_bind
     proxy_buffer_size
     proxy_buffering
     proxy_buffers
     proxy_busy_buffers_size
     proxy_cache
     proxy_cache_bypass
     proxy_cache_convert_head
     proxy_cache_key
     proxy_cache_lock
     proxy_cache_lock_age
     proxy_cache_lock_timeout
     proxy_cache_max_range_offset
     proxy_cache_methods
     proxy_cache_min_uses
     proxy_cache_path
     proxy_cache_purge
     proxy_cache_revalidate
     proxy_cache_use_stale
     proxy_cache_valid
     proxy_connect_timeout
     proxy_cookie_domain
     proxy_cookie_path
     proxy_force_ranges
     proxy_headers_hash_bucket_size
     proxy_headers_hash_max_size
     proxy_hide_header
     proxy_http_version
     proxy_ignore_client_abort
     proxy_ignore_headers
     proxy_intercept_errors
     proxy_limit_rate
     proxy_max_temp_file_size
     proxy_method
     proxy_next_upstream
     proxy_next_upstream_timeout
     proxy_next_upstream_tries
     proxy_no_cache
     proxy_pass
     proxy_pass_header
     proxy_pass_request_body
     proxy_pass_request_headers
     proxy_read_timeout
     proxy_redirect
     proxy_request_buffering
     proxy_send_lowat
     proxy_send_timeout
     proxy_set_body
     proxy_set_header
     proxy_ssl_certificate
     proxy_ssl_certificate_key
     proxy_ssl_ciphers
     proxy_ssl_crl
     proxy_ssl_name
     proxy_ssl_password_file
     proxy_ssl_server_name
     proxy_ssl_session_reuse
     proxy_ssl_protocols
     proxy_ssl_trusted_certificate
     proxy_ssl_verify
     proxy_ssl_verify_depth
     proxy_store
     proxy_store_access
     proxy_temp_file_write_size
     proxy_temp_path
Embedded Variables

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

設定例

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

ディレクティブ

構文: proxy_bind address [transparent] | off;
デフォルト: -
コンテキスト: http, server, location

このディレクティブはバージョン0.8.22から導入されました。

プロキシされたサーバへ向かって出て行く接続が、指定したローカルの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のワーカープロセスをsuperuser権限を使って実行する必要があり、プロキシされたサーバからのネットワーク通信を捕らえるようにカーネルルーティングテーブルを構成する必要があります。

構文: proxy_buffer_size size;
デフォルト:
proxy_buffer_size 4k|8k;
コンテキスト: http, server, location

プロキシされたサーバから応答の最初の部分を読み込むために使われるバッファのsizeを設定します。この部分は通常小さな応答ヘッダを含んでいます。デフォルトでは、バッファサイズはメモリページと同じサイズです。これは4Kあるいは8kです。プラットフォームに依存します。しかしながら、もっと小さくすることができます。

構文: proxy_buffering on | off;
デフォルト:
proxy_buffering on;
コンテキスト: http, server, location

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

バッファリングが有効な場合、nginxはプロキシされたサーバからできるだけ早く応答を受け取り、 proxy_buffer_sizeproxy_buffers ディレクティブで設定されるバッファに保存します。全ての応答がメモリに収まらない場合、一部をディスク上のtemporary fileに保存することができます。一時ファイルへの書き込みは、proxy_max_temp_file_sizeproxy_temp_file_write_size ディレクティブを使って制御することができます。

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

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

構文: proxy_buffers number size;
デフォルト:
proxy_buffers 8 4k|8k;
コンテキスト: http, server, location

接続ごとにプロキシされたサーバからの応答を読み込むために使われるバッファのnumbersizeを設定します。デフォルトでは、バッファサイズはメモリページと同じサイズです。これは4Kあるいは8kです。プラットフォームに依存します。

構文: proxy_busy_buffers_size size;
デフォルト:
proxy_busy_buffers_size 8k|16k;
コンテキスト: http, server, location

プロキシされたサーバからの応答の buffering を有効にした場合、応答がまだ全て読み込まれていない間にクライアントに応答を送るのに忙しくなりえるバッファのsize を制限します。一方で、バッファの残りが応答を読み込むために使われることがあります。もし必要であれば応答の一部分が一時ファイルにバッファされます。デフォルトでは、sizeproxy_buffer_sizeproxy_buffers ディレクティブで設定される二つのバッファのサイズによって制限されます。

構文: proxy_cache zone | off;
デフォルト:
proxy_cache off;
コンテキスト: http, server, location

キャッシュに使われる共有メモリ領域を定義します。同じ領域が幾つかの場所で使われるかも知れません。パラメータ値は変数を含むことができます (1.7.9)。off パラメータは、前の設定レベルから継承したキャッシングを無効にします。

構文: proxy_cache_bypass string ...;
デフォルト: -
コンテキスト: http, server, location

応答がキャッシュから取れない時の条件を設定します。stringパラメータのうちの一つでも空では無く"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 | off;
デフォルト:
proxy_cache_convert_head on;
コンテキスト: http, server, location

このディレクティブはバージョン1.9.7から導入されました。

キャッシングのために"HEAD"メソッドを"GET"に置き換えします。置き換えが無効な場合、cache key$request_methodを含むように設定されていなければなりません。

構文: proxy_cache_key string;
デフォルト:
proxy_cache_key $scheme$proxy_host$request_uri;
コンテキスト: http, server, location

キャッシュのためのキーを定義します。例えば

proxy_cache_key "$host$request_uri $cookie_user";

デフォルトでは、ディレクティブの値はその文字列とほとんど同じです。

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

構文: proxy_cache_lock on | off;
デフォルト:
proxy_cache_lock off;
コンテキスト: http, server, location

このディレクティブはバージョン1.1.12から導入されました。

有効にされた場合は、リクエストをプロキシされたサーバに渡すことで一度に一つのリクエストがproxy_cache_keyディレクティブによって識別される新しいキャッシュエレメントを生成するようにできるでしょう。同じキャッシュエレメントの他のリクエストは、proxy_cache_lock_timeoutディレクティブで設定された時間まで、キャッシュの中に現れるまで応答を待つか、このエレメントのキャッシュロックが開放されるのを待つかするでしょう。

構文: proxy_cache_lock_age time;
デフォルト:
proxy_cache_lock_age 5s;
コンテキスト: http, server, location

このディレクティブはバージョン1.7.8から導入されました。

もし指定されたtimeの間、新しいキャッシュ要素を作るためにプロキシされたサーバへ送信された最後のリクエストが完了しない場合は、プロキシされたサーバへもう一つのリクエストが渡されるかも知れません。

構文: proxy_cache_lock_timeout time;
デフォルト:
proxy_cache_lock_timeout 5s;
コンテキスト: http, server, location

このディレクティブはバージョン1.1.12から導入されました。

proxy_cache_lockのタイムアウトを設定します。timeが期限切れになると、リクエストはプロキシされるサーバに渡されるでしょうが、応答はキャシュされないでしょう。

1.7.8以前は応答はキャッシュされました。

構文: proxy_cache_max_range_offset number;
デフォルト: -
コンテキスト: http, server, location

このディレクティブはバージョン 1.11.6 から導入されました。

バイトレンジ リクエストについてバイトでオフセットを設定します。範囲がオフセットを超える場合は、レンジ リクエストはプロキシされたサーバに渡され、応答はキャッシュされないでしょう。

構文: proxy_cache_methods GET | HEAD | POST ...;
デフォルト:
proxy_cache_methods GET HEAD;
コンテキスト: http, server, location

このディレクティブはバージョン0.7.59から導入されました。

クライアントのリクエストメソッドがこのリスディレクティブに列挙されている場合、応答はキャッシュされるでしょう。"GET"と"HEAD"メソッドは明示的に指定するように推奨されていますが、それらは常にリストに追加されます。proxy_no_cacheディレクティブも見てください。

構文: proxy_cache_min_uses number;
デフォルト:
proxy_cache_min_uses 1;
コンテキスト: http, server, location

応答がキャッシュされてからのリクエストのnumber を設定します。

構文: proxy_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time];
デフォルト: -
コンテキスト: http

キャッシュのパスとその他のパラメータを設定します。キャッシュデータはファイルに保存されます。キャッシュの中のファイル名は、cache keyに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から、一時ファイルとキャッシュは異なるファイルシステムに置くことができます。しかし、この場合に注意が必要なのは、手軽なリネーム操作の代わりにファイルは二つのファイルシステムを超えてコピーされるということです。従って、どの指定されたlocationの一時ファイルに保持されるキャシュとディレクトリの両方が同じファイルシステムに配置されることが勧められます。一時ファイルのためのディレクトリはuse_temp_path パラメータに基づいて設定されます(1.7.10)。パラメータが省略あるいは値 onに設定されると、proxy_temp_pathディレクティブによって設定されたディレクトリが指定されたlocationに対して使われるでしょう。値が off に設定されると、一時ファイルは直接キャッシュディレクトリに配置されるでしょう。

更に、全てのアクティブなキーとデータに関する情報は共有メモリ領域に保持されます。その名前サイズkeys_zoneパラメータによって設定されます。一メガバイトの領域は約8000のキーを保持することができます。

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

特別な"cache manager"プロセスはmax_sizeパラメータで設定されるキャッシュサイズの最大値を監視します。このサイズを超えると、もっとも使われていないデータから削除されます。データは、manager_files, manager_threshold および manager_sleep パラメータによって設定される繰り返しの中で削除されます (1.11.5)。1つの繰り返しの中では、manager_files 以下の項目が削除されます (デフォルトでは 100)。一回の繰り返しの持続期間は manager_threshold パラメータによって制限されます (デフォルトでは 200ミリ秒)。繰り返しの間は、loader_sleep パラメータ(デフォルトでは50ミリ秒)で設定される小休止が置かれます。

その開始の1分後に、特別な"cache loader" プロセスが起動されます。それはファイルシステムに保持されている以前のキャッシュデータに関するデータをキャッシュ領域にロードします。そのロードも繰り返し行われます。一回の繰り返しではloader_files(デフォルトでは100)以下のアイテムがロードされます。その上、一回の繰り返しの持続期間は loader_thresholdパラメータ(デフォルトでは200ミリ秒)に制限されます。繰り返しの間は、loader_sleep パラメータ(デフォルトでは50ミリ秒)で設定される小休止が置かれます。

更に、次のパラメータが商用許可の一部として利用可能です:

purger=on|off
wildcard keyに一致するキャッシュエントリをキャッシュpurgerでディスクから削除するかどうかを伝えます (1.7.12)。パラメータを on (デフォルトは off)にすると、永続的に全てのキャッシュエントリを数え上げワイルドカードキーに一致するエントリを削除する"cache purger" プロセスを有効にするでしょう。
purger_files=number
繰り返しの間に走査される項目の数を設定します (1.7.12)。デフォルトでは、purger_files は10に設定されます。
purger_threshold=number
1回の繰り返しの持続時間を設定します (1.7.12)。デフォルトでは、purger_threshold は50ミリ秒に設定されます。
purger_sleep=number
繰り返しの間の休止を設定します (1.7.12)。デフォルトでは、purger_sleep は50ミリ秒に設定されます。

構文: proxy_cache_purge string ...;
デフォルト: -
コンテキスト: http, server, location

このディレクティブはバージョン1.5.7から導入されました。

キャッシュの一掃リクエストと見なされるリクエストの条件を定義します。stringパラメータのうちの一つでも空では無く"0"と等しくない場合は、cache keyに対応するキャッシュエントリが削除されます。操作が成功した結果は204(No Content)応答が返されることによって示されます。

一掃リクエストのcache keyが("*")で終わる場合は、ワイルドカードに一致する全てのキャッシュのエントリがキャッシュから削除されます。However, these entries will remain on the disk until they are deleted for either inactivity, or processed by the cache purger (1.7.12), or a client attempts to access them.

設定例

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

map $request_method $purge_method {
    <s0>'purge'</s0>
    default 0;
}

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

この機能は商用許可の一部として利用可能です。

構文: proxy_cache_revalidate on | off;
デフォルト:
proxy_cache_revalidate off;
コンテキスト: http, server, location

このディレクティブはバージョン1.5.7から導入されました。

"If-Modified-Since"と"If-None-Match"ヘッダフィールドを持つ条件付きリクエストを使って、expireしたアイテムの再検証を有効にします。

構文: proxy_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | off ...;
デフォルト:
proxy_cache_use_stale off;
コンテキスト: http, server, location

プロキシされたサーバとの通信でエラーが起きた場合に、新鮮ではない応答が使われるかどうかを決定します。ディレクティブのパラメータはpoxy_next_upstreamディレクティブのパラメータと一致します。

もしリクエストを処理するためのプロキシされたサーバが選択できない場合は、error パラメータは新鮮ではないキャッシュ応答を使うことも許可します。

更に、updatingパラメータはもしキャッシュが更新されていても新鮮ではないキャッシュ応答を使うことを許可します。これにより、キャッシュされたデータの更新時にプロキシされたサーバへのアクセス数を最小限にすることができます。

新しいキャッシュの要素を作るときに、プロキシされたサーバへのアクセス数を最小限にするには、 proxy_cache_lock ディレクティブが使われるかも知れません。

構文: proxy_cache_valid [code ...] time;
デフォルト: -
コンテキスト: http, server, location

異なる応答コードのためのキャシュ時間を設定します。例えば、次のディレクティブは、

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;

キャッシングのパラメータは、応答ヘッダの中に直接設定するようにもできます。これはディレクティブを使ってキャッシュ時間を設定するよりも優先されます。

これらの一つ以上の応答フィールドの処理を無効にするには、proxy_ignore_headers ディレクティブを使います。

構文: proxy_connect_timeout time;
デフォルト:
proxy_connect_timeout 60s;
コンテキスト: http, server, location

プロキシされたサーバとの接続の確立のタイムアウトを定義します。このタイムアウトは通常75秒以上にならないことに注意が必要です。

構文: proxy_cookie_domain off;
proxy_cookie_domain domain replacement;
デフォルト:
proxy_cookie_domain off;
コンテキスト: http, server, location

このディレクティブはバージョン1.1.15から導入されました。

プロキシされたサーバの応答の"Set-Cookie"ヘッダフィールドのdomainの属性で変更される文字列を設定します。プロキシされたサーバが"Set-Cookie"ヘッダフィールドを"domain=localhost"属性で返すことを仮定します。次のディレクティブ

proxy_cookie_domain localhost example.org;

この属性を"domain=example.org"で書き換えるでしょう。

domainreplacement 文字列とdomain 属性の最初のドットは無視されるでしょう。マッチングは大文字小文字を区別します。

domainreplacement 文字列には変数を含むことができます:

proxy_cookie_domain www.$host $host;

ディレクティブは正規表現を使って指定することもできます。この場合、domainは"~"記号で始まる必要があります。正規表現には、名前付きと場所のキャプチャを含むことができ、replacementはそれらを参照することができます:

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_domain off;
proxy_cookie_domain localhost example.org;
proxy_cookie_domain www.example.org example.org;

構文: proxy_cookie_path off;
proxy_cookie_path path replacement;
デフォルト:
proxy_cookie_path off;
コンテキスト: http, server, location

このディレクティブはバージョン1.1.15から導入されました。

プロキシされたサーバの応答の"Set-Cookie"ヘッダフィールドのpassの属性で変更される文字列を設定します。プロキシされたサーバが"Set-Cookie"ヘッダフィールドを"path=/two/some/uri/"属性で返すことを仮定します。次のディレクティブ

proxy_cookie_path /two/ /;

この属性を"path=/some/uri/"で書き換えるでしょう。

pathreplacement 文字列には変数を含むことができます:

proxy_cookie_path $uri /some$uri;

ディレクティブは正規表現を使って指定することもできます。この場合、path は、大文字小文字を区別しないマッチングには "~"記号から、大文字小文字を区別するには"~*"記号からのどちらかである必要があります。正規表現には、名前付きと場所のキャプチャを含むことができ、replacementはそれらを参照することができます:

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

複数の proxy_cookie_pathディレクティブが有り得ます:

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

offパラメータは現在のレベルの全てのproxy_cookie_pathディレクティブの影響を無効にすることができます。

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

構文: proxy_force_ranges on | off;
デフォルト:
proxy_force_ranges off;
コンテキスト: http, server, location

このディレクティブはバージョン1.7.7から導入されました。

応答の中の"Accept-Ranges"フィールドに応じてプロキシされるサーバからのキャッシュおよびキャッシュされていない応答の両方において、byte-rangeのサポートを有効にします。

構文: proxy_headers_hash_bucket_size size;
デフォルト:
proxy_headers_hash_bucket_size 64;
コンテキスト: http, server, location

proxy_hide_headerproxy_set_headerディレクティブで使われるハッシュテーブルのsizeを設定します。ハッシュテーブルの設定の詳細は別個のドキュメントで提供されています。

構文: proxy_headers_hash_max_size size;
デフォルト:
proxy_headers_hash_max_size 512;
コンテキスト: http, server, location

proxy_hide_headerproxy_set_headerディレクティブで使われるハッシュテーブルの最大のsizeを設定します。ハッシュテーブルの設定の詳細は別個のドキュメントで提供されています。

構文: proxy_hide_header field;
デフォルト: -
コンテキスト: http, server, location

デフォルトでは、nginxはプロキシされたサーバからクライアントへの"Date", "Server", "X-Pad"と"X-Accel-..."ヘッダフィールドを通しません。proxy_hide_headerディレクティブは、更に通過されないフィールドを設定します。逆に、フィールドの通過が必要な場合は、proxy_pass_headerディレクティブを使うことができます。

構文: proxy_http_version 1.0 | 1.1;
デフォルト:
proxy_http_version 1.0;
コンテキスト: http, server, location

このディレクティブはバージョン1.1.4から導入されました。

プロキシのためのHTTPプロトコルバージョンを設定します。デフォルトでは、バージョン1.0が使われます。バージョン1.1は keepalive接続とNTLM authenticationを使う事を推奨されます。

構文: proxy_ignore_client_abort on | off;
デフォルト:
proxy_ignore_client_abort off;
コンテキスト: http, server, location

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

構文: proxy_ignore_headers field ...;
デフォルト: -
コンテキスト: http, server, location

プロキシされたサーバからの特定の応答ヘッダフィールドの処理を無効にします。次のフィールドを無視することができます: "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” は応答 cachingのパラメータを設定します;
  • "X-Accel-Redirect" は特定のURIに対してinternal redirect を実行します。
  • "X-Accel-Limit-Rate" はクライアントへの応答の転送について rate limitを設定します;
  • "X-Accel-Buffering" は応答のbufferingを有効または無効にします ;
  • "X-Accel-Charset"は望ましい応答のcharsetを設定します。

構文: proxy_intercept_errors on | off;
デフォルト:
proxy_intercept_errors off;
コンテキスト: http, server, location

プロキシされたサーバの300以上の応答コードが、クライアントへ渡されるべきかまたは遮断されるべきか、そしてerror_page ディレクティブで処理するためにnginxにリダイレクトすべきかを決定します。

構文: proxy_limit_rate rate;
デフォルト:
proxy_limit_rate 0;
コンテキスト: http, server, location

このディレクティブはバージョン1.7.7から導入されました。

プロキシされるサーバから応答を読み込む時のスピードを制限します。rateは秒間あたりのバイトで指定されます。0の値はレートの制限を無効にします。制限はリクエストごとに設定されます。もしnginxがプロキシされるサーバに同時に二つの接続を開いた場合は、全体のレートは指定された制限の二倍になるでしょう。この制限はプロキシされるサーバからの応答のbufferingが有効な場合にのみ動作します。

構文: proxy_max_temp_file_size size;
デフォルト:
proxy_max_temp_file_size 1024m;
コンテキスト: http, server, location

プロキシされたサーバからの応答のbuffering が有効な場合で、応答の全体が proxy_buffer_sizeproxy_buffers ディレティブで設定されるバッファに収まらない場合に、応答の一部を一時ファイルに保存することができます。このディレクティブは一時ファイルのsize最大値を設定します。一時ファイルに一度に書き込まれるデータのサイズは、proxy_temp_file_write_sizeディレクティブで設定されます。

0の値は、一時ファイルの応答のバッファリングを無効にします。

この制限はディスク上に cached あるいは stored される応答については適用されないでしょう。

構文: proxy_method method;
デフォルト: -
コンテキスト: http, server, location

クライアントのリクエストのメソッドの代わりにプロキシされたサーバへ転送する時のリクエストで使われるHTTP methodを指定します。パラメータ値は変数を含むことができます (1.11.6)。

構文: proxy_next_upstream error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | non_idempotent | off ...;
デフォルト:
proxy_next_upstream error timeout;
コンテキスト: http, server, location

どの場合にリクエストが次のサーバに渡されるべきかを指定します:

error
サーバへの接続の確立時、あるいはサーバにリクエストを渡す時、あるいは応答ヘッダーを読み込む時にエラーが起きた場合;
timeout
サーバへの接続の確立時、あるいはサーバにリクエストを渡す時、あるいは応答ヘッダーを読み込む時にタイムアウトが起きた場合;
invalid_header
サーバが空あるいは無効な応答を返した場合;
http_500
サーバがコード500の応答を返した場合;
http_502
サーバがコード502の応答を返した場合;
http_503
サーバがコード503を返した場合;
http_504
サーバがコード504の応答を返した場合;
http_403
サーバがコード403を返した場合;
http_404
サーバがコード404の応答を返した場合;
non_idempotent
もしリクエストがupstream サーバに送信された場合は、通常 non-idempotent メソッド (POST, LOCK, PATCH) のリクエストは次のサーバに渡されません(1.9.13); このオプションを有効にすると明示的にそのようなリクエストの再試行を行うことができます。
off
リクエストを次のサーバに渡すのを無効化する。

まだクライアントに何も送っていない時にのみ、リクエストを次のサーバに渡す事ができるということを、心に留めておいてください。応答の転送中にエラーまたはタイムアウトが起きると、この修復は不可能です。

このディレクティブは何をサーバとの通信の失敗と見なすかについても定義します。error, timeoutinvalid_header は、ディレクティブの中で指定されていなくても常に失敗と見なされます。http_500, http_502, http_503http_504 がディレクティブの中で指定されている時のみ、失敗と見なされます。http_403http_404 の場合は、失敗と見なされません。

次のサーバへリクエストを渡すことを 試行回数 および 時間で制限することができます。

構文: proxy_next_upstream_timeout time;
デフォルト:
proxy_next_upstream_timeout 0;
コンテキスト: http, server, location

このディレクティブはバージョン1.7.5から導入されました。

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

構文: proxy_next_upstream_tries number;
デフォルト:
proxy_next_upstream_tries 0;
コンテキスト: http, server, location

このディレクティブはバージョン1.7.5から導入されました。

次のサーバにリクエストが渡すときに、可能な試行回数を制限します。0 の値はこの制限を無効にします。

構文: proxy_no_cache string ...;
デフォルト: -
コンテキスト: http, server, location

応答がキャッシュに保存されない状況を定義します。stringパラメータのうちの一つでも空では無く"0"に等しくない場合は、応答は保存されないでしょう。

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

proxy_cache_bypass ディレクティブと一緒に使うことができます。

構文: proxy_pass URL;
デフォルト: -
コンテキスト: location, if in location, limit_except

プロキシされるサーバのプロトコルとアドレスと、locationがマップされるべき任意のURIを設定します。プロトコルとして"http"または"https"が指定可能です。アドレスはドメイン名またはIPアドレス、オプションとしてポートが指定可能です:

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

あるいは、UNIXドメインソケットパスとして、"unix"の単語の後にコロンで囲んで指定します:

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

ドメイン名が幾つかのアドレスに解決される場合は、ラウンドロビンの形式でそれら全てが使われるでしょう。更に、server groupとしてアドレスを指定することができます。

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

  • proxy_passディレクティブがURIで指定されていれば、リクエストがサーバに渡された時に locationに一致したnormalizedリクエストがディレクティブで指定された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の部分が決定できない場合もあります。

  • 正規表現を使ってlocationが指定される場合。

    この場合、ディレクティブはURI無しで指定されるべきです。

  • rewrite ディレクティブを使ってプロキシされたlocationの中でURIが変更される場合、この設定がリクエストを処理するために使われるでしょう((break):
    location /name/ {
        rewrite    /name/([^/]+) /users?name=$1 break;
        proxy_pass http://127.0.0.1;
    }
    

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

サーバ名、ポートと渡されたURIも変数を使って指定することができます:

proxy_pass http://$host$uri;

or even like this:

proxy_pass $request;

この場合、サーバ名は記述されたserver groupsの中で検索されます。もし見つからない場合は、サーバ名はresolverを使って決定されます。

WebSocket プロキシは、特別な設定を必要とし、バージョン1.3.13からサポートされます。

構文: proxy_pass_header field;
デフォルト: -
コンテキスト: http, server, location

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

構文: proxy_pass_request_body on | off;
デフォルト:
proxy_pass_request_body on;
コンテキスト: http, server, location

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

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

    proxy_pass ...
}

proxy_set_headerproxy_pass_request_headersディレクティブも見てください。

構文: proxy_pass_request_headers on | off;
デフォルト:
proxy_pass_request_headers on;
コンテキスト: http, server, location

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

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

    proxy_pass ...
}

proxy_set_headerproxy_pass_request_bodyディレクティブも見てください。

構文: proxy_read_timeout time;
デフォルト:
proxy_read_timeout 60s;
コンテキスト: http, server, location

プロキシされたサーバからの応答の読み込みのタイムアウトを定義します:. タイムアウトは二つの連続する読み込み操作の間に設定され、応答全体の転送のためのものではありません。プロキシされたサーバがこの時間内に何も転送しなかった場合、接続は閉じられます。

構文: proxy_redirect default;
proxy_redirect off;
proxy_redirect redirect replacement;
デフォルト:
proxy_redirect default;
コンテキスト: http, server, location

プロキシされたサーバの応答の"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パラメータによって指定されるデフォルトの置き換えには、locationproxy_pass ディレクティブが使われます。下がて、次の二つの設定は同じです:

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 off;
proxy_redirect default;
proxy_redirect http://localhost:8000/  /;
proxy_redirect http://www.example.com/ /;

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

proxy_redirect / /;

構文: proxy_request_buffering on | off;
デフォルト:
proxy_request_buffering on;
コンテキスト: http, server, location

このディレクティブはバージョン1.7.11から導入されました。

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

バッファが有効な場合は、リクエストをプロキシされたサーバに渡す前にリクエストボディの全体が読み込まれます。

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

元のリクエストボディを送信するためにHTTP/1.1 chunked transfer encoding が使用された場合は、プロキシのためにHTTP/1.1が enabled では無い場合は指定された値に関係なくバッファされます。

構文: proxy_send_lowat size;
デフォルト:
proxy_send_lowat 0;
コンテキスト: http, server, location

もしこのディレクティブがゼロ以外の値に設定された場合、kqueueメソッドのNOTE_LOWAT またはSO_SNDLOWATソケットオプションのどちらかを使って、プロキシされるサーバへ向かう送信オペレーションの数を指定されたsizeを使って最小化しようとします。

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

構文: proxy_send_timeout time;
デフォルト:
proxy_send_timeout 60s;
コンテキスト: http, server, location

プロキシされるサーバへのリクエストの転送のタイムアウトを設定します。タイムアウトは二つの連続する書き込み操作の間に設定され、リクエスト全体の転送のためのものではありません。この時間内にプロキシされるサーバが何も受け取らなかった場合、接続が閉じられます。

構文: proxy_set_body value;
デフォルト: -
コンテキスト: http, server, location

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

構文: proxy_set_header field value;
デフォルト:
proxy_set_header Host $proxy_host;
proxy_set_header Connection close;
コンテキスト: http, server, location

プロキシされるサーバへ渡されるリクエストヘッダのフィールドの再定義あるいは追加が可能です。valueにはテキスト、変数、それらの組み合わせを含めることができます。現在のレベルに<c4>proxy_set_param</c4>ディレクティブが無い場合に限り、これらのディレクティブは上のレベルから引き継がれます。デフォルトでは、二つのフィールドだけが再定義されます:

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_ssl_certificate file;
デフォルト: -
コンテキスト: http, server, location

このディレクティブはバージョン1.7.8から導入されました。

プロキシされるHTTPサーバに対して認証に使われるPEM形式の証明書の ファイルを指定します。

構文: proxy_ssl_certificate_key file;
デフォルト: -
コンテキスト: http, server, location

このディレクティブはバージョン1.7.8から導入されました。

プロキシされるHTTPSサーバに対して認証に使われるPEM形式の秘密鍵の ファイルを指定します。

engine:name:id の値は file の代わりに指定することができ(1.7.9)、 特定のOpenSSLのnameの特定の id と一緒に秘密鍵を取り付けます。

構文: proxy_ssl_ciphers ciphers;
デフォルト:
proxy_ssl_ciphers DEFAULT;
コンテキスト: http, server, location

このディレクティブはバージョン1.5.6から導入されました。

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

全てのリストは"openssl ciphers"コマンドを使ってみることができます。

構文: proxy_ssl_crl file;
デフォルト: -
コンテキスト: http, server, location

このディレクティブはバージョン1.7.0から導入されました。

プロキシされたHTTPSサーバの証明書をverifyするために使われるPEM形式の無効な証明書(CRL)のfileを指定します。

構文: proxy_ssl_name name;
デフォルト:
proxy_ssl_name $proxy_host;
コンテキスト: http, server, location

このディレクティブはバージョン1.7.0から導入されました。

プロキシされたHTTPSサーバの証明書をverifyするために使われるサーバ名を上書きし、プロキシされたHTTPSサーバと接続を確立する時にpassed through SNIできます。

デフォルトでは、proxy_passURIのホスト部分が使われます。

構文: proxy_ssl_password_file file;
デフォルト: -
コンテキスト: http, server, location

このディレクティブはバージョン1.7.8から導入されました。

secret keysのためのそれぞれのパスフレーズが一行に指定されているfileを指定します。パスフレーズはキーがロードされる時に順番に試されます。

構文: proxy_ssl_server_name on | off;
デフォルト:
proxy_ssl_server_name off;
コンテキスト: http, server, location

このディレクティブはバージョン1.7.0から導入されました。

secured HTTPSサーバと接続を確立する時に、TLS Server Name Indication extension (SNI, RFC 6066) を使ってサーバ名を渡すことを有効または無効にします。

構文: proxy_ssl_session_reuse on | off;
デフォルト:
proxy_ssl_session_reuse on;
コンテキスト: http, server, location

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

構文: proxy_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2];
デフォルト:
proxy_ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
コンテキスト: http, server, location

このディレクティブはバージョン1.5.6から導入されました。

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

構文: proxy_ssl_trusted_certificate file;
デフォルト: -
コンテキスト: http, server, location

このディレクティブはバージョン1.7.0から導入されました。

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

構文: proxy_ssl_verify on | off;
デフォルト:
proxy_ssl_verify off;
コンテキスト: http, server, location

このディレクティブはバージョン1.7.0から導入されました。

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

構文: proxy_ssl_verify_depth number;
デフォルト:
proxy_ssl_verify_depth 1;
コンテキスト: http, server, location

このディレクティブはバージョン1.7.0から導入されました。

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

構文: proxy_store on | off | string;
デフォルト:
proxy_store off;
コンテキスト: http, server, location

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

proxy_store /data/www$original_uri;

ファイルの修正時間は受け取った"Last-Modified"応答ヘッダフィールドに従って設定されます。応答はまず一時ファイルに書き込まれ、それからファイルはリネームされます。バージョン0.8.9から、一時ファイルと恒久的な保存は別のファイルシステムに置くことができます。しかし、この場合に注意が必要なのは、手軽なリネーム操作の代わりにファイルは二つのファイルシステムを超えてコピーされるということです。従って、いずれの指定されたlocationの保存されたファイルと一時ファイルを保持するディレクトリの両方が、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/;
}

or like this:

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 users:permissions ...;
デフォルト:
proxy_store_access user:rw;
コンテキスト: http, server, location

新しく作成されたファイルとディレクトリにアクセスパーミッションを設定します。例えば:

proxy_store_access user:rw group:rw all:r;

何らかのgroup または all アクセスパーミッションが指定された場合には、userパーミッションは省略されるかも知れません:

proxy_store_access group:rw all:r;

構文: proxy_temp_file_write_size size;
デフォルト:
proxy_temp_file_write_size 8k|16k;
コンテキスト: http, server, location

プロキシされたサーバから一時ファイルへの応答のバッファリングが有効にされた場合、一時ファイルに一度に書き込まれるデータのsizeを制限します。 デフォルトでは、sizeproxy_buffer_sizeproxy_buffers ディレクティブで設定される二つのバッファによって制限されます。一時ファイルの最大サイズは proxy_max_temp_file_sizeディレクティブによって設定されます。

構文: proxy_temp_path path [level1 [level2 [level3]]];
デフォルト:
proxy_temp_path proxy_temp;
コンテキスト: http, server, location

プロキシされたサーバから受け取るデータを保持する一時ファイルのディレクトリを定義します。指定されたディレクトリの下に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 ディレクティブの中で指定されたプロキシされる差b-アの名前とポート番号;
$proxy_port
proxy_pass ディレクティブの中で指定されたプロキシされるサーバのポート番号、あるいはプロトコルのデフォルトのポート番号;
$proxy_add_x_forwarded_for
"X-Forwarded-For"クライアントリクエストヘッダフィールドと$remote_addr 変数がカンマで区切られて追加されるでしょう。"X-Forwarded-For"フィールドがクライアントリクエストヘッダに存在しない場合、$proxy_add_x_forwarded_for$remote_addr変数は同じになるでしょう。

TOP
inserted by FC2 system