FAQ

Page Discussion History

HttpProxyModuleJa

インストール | モジュール | アドオン | 設定 | コミュニティ | その他の情報源

Contents

概要

このモジュールにより、リクエストを別のサーバに転送することが可能となります。

設定例:

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

HTTP Proxy Module (および FastCGI) を用いる場合、クライアントからのリクエスト全体がバックエンドのプロキシ対象のサーバに引き渡される前に、nginx でバッファされます。そのため、バックエンドサーバから受信したデータ量を用いてアップロードの進捗を計測している機構は適切に動作しません。

ディレクティブ

proxy_bind

syntax: proxy_bind address

default: none

context: http, server, location

version: ≥ 0.8.22

example:

proxy_bind  192.168.1.1;

This directive binds each upstream socket to a local address before calling connect(). It may be useful if host has several interfaces/aliases and you want to pass outgoing connections from specific interface/address.

proxy_buffer_size

Syntax: proxy_buffer_size size
Default: 4k|8k
Context: http
server
location
Reference:proxy_buffer_size


このディレクティブはプロキシ対象のサーバから取得したレスポンスの先頭部分を読み込むバッファサイズを設定します。

レスポンスの先頭部分は、通常サイズの小さいレスポンスヘッダが格納されています。

デフォルトで、このバッファサイズは proxy_buffers ディレクティブのバッファ1つ分と同一のサイズですが、これより小さい値に設定することも可能です。

proxy_buffering

Syntax: proxy_buffering on | off
Default: on
Context: http
server
location
Reference:proxy_buffering


このディレクティブは、プロキシ対象のサーバからのレスポンスのバッファリングを有効にします。

バッファリングが有効な場合、nginx はプロキシ対象のサーバからのレスポンスを可能な限り迅速に読み込み、それを proxy_buffer_size および proxy_buffers ディレクティブで設定されたバッファに格納します。レスポンスがメモリ内に格納できない場合、その部分はディスクに書き出されます。

バッファリングが off に設定された場合、レスポンスは受信と同時に直ちにクライアントに転送されます。nginx はプロキシ対象のサーバからのレスポンス全体を読み取ろうとはしません。nginx がプロキシ対象のサーバから受信可能な最大サイズは、proxy_buffer_size ディレクティブで設定されます。

proxy_buffering が off の場合、上位サーバからのレスポンスのキャッシュ機構も機能しません。

長周期のポーリング処理を実施する Comet のアプリケーションでは、proxy_buffering を off にする必要があります。これを行わないと、非同期なレスポンスがバッファリングされてしまうため、 Comet は動作しません。

レスポンス内の X-Accel-Buffering ヘッダを用いることで、バッファリングをリクエスト単位で有効にすることが可能です。

proxy_buffers

Syntax: proxy_buffers number size
Default: 8 4k|8k
Context: http
server
location
Reference:proxy_buffers


このディレクティブは、プロキシ対象のサーバから取得したレスポンスを格納するバッファ数とサイズを指定します。デフォルトで、バッファサイズはページサイズと同一になります。ページサイズはプラットフォームによりますが、4K もしくは 8K です。

proxy_busy_buffers_size

Syntax: proxy_busy_buffers_size size
Default: 8k|16k
Context: http
server
location
Reference:proxy_busy_buffers_size


プロキシ対象のサーバからのレスポンスのバッファリングが有効な場合、レスポンス全体の読み取りが完了しない内に、クライアントに対するレスポンスの送信で占有してよいバッファのサイズを指定します。残りのバッファは継続してレスポンスの読み取りを行うとともに、必要であればレスポンスの一部を一時ファイルに保存します。デフォルトで、size は proxy_buffer_size および proxy_buffers ディレクティブで設定されたバッファサイズの 2 倍になっています。

proxy_cache

Syntax: proxy_cache zone | off
Default: off
Context: http
server
location
Reference:proxy_cache


このディレクティブは、キャッシングに用いるゾーン名を設定します。同一のゾーンを複数個所で用いることが可能です。

0.7.48 以降、キャッシュはバックエンドの "Expires", Cache-Control: no-cache", "Cache-Control: max-age=XXX" ヘッダの値を参照します。0.7.66 以降では、"private" と "no-store" も参照されます。 nginx はキャッシングの際に "Vary" ヘッダを参照しません。ユーザのプライベートな情報が、他のユーザに対して意図せずにキャッシュから提供されることを抑止したい場合は、バックエンドで "no-cache" か "max-age=0" を設定するか、 proxy_cache_key に $cookie_xxx といったユーザ固有のデータを含めておきます。 ただし、Cookie の値を proxy_cache_key の一部として用いた場合、共有する情報をキャッシングする利点が損なわれますので、ロケーションごとに、異なる proxy_cache_key を設定することで、プライベートな情報と共有する情報を分離するのがよいでしょう。

キャッシングは proxy_buffers ディレクティブが off に設定されている場合、機能しません。

以下のレスポンスヘッダが含まれていた場合、これらが ignored に設定されていない限り、レスポンスのキャッシングが無効となります。

  • Set-Cookie
  • Cache-Control に "no-cache", "no-store", "private" が含まれているか、 "max-age" が 0 もしくは数値以外である
  • Expires が過去の日付となっている
  • X-Accel-Expires: 0

proxy_cache_bypass

Syntax: proxy_cache_bypass string ...
Default:
Context: http
server
location
Reference:proxy_cache_bypass


このディレクティブは、レスポンスをキャッシュから取得しない条件を指定します。最低 1 つ以上の文字列が空でなく、"0" でもない場合、レスポンスはキャッシュから取得されません。

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

バックエンドからのレスポンスは適宜キャッシュされます。キャッシュ内のアイテムをリフレッシュする方法の一つとして、"My-Secret-Header: 1" といった独自のヘッダを付加したリクエストを送信したうえで、proxy_cache_bypass に次のような設定をしておく方法が挙げられます。

proxy_cache_bypass $http_my_secret_header;

proxy_no_cache ディレクティブと連携することも可能です。

proxy_cache_key

Syntax: proxy_cache_key string
Default: $scheme$proxy_host$request_uri
Context: http
server
location
Reference:proxy_cache_key


The directive specifies what information is included in the key for caching, for example

proxy_cache_key "$host$request_uri$cookie_user";

Note that by default, the hostname of the server is not included in the cache key. If you are using subdomains for different locations on your website, you need to include it, e.g. by changing the cache key to something like

proxy_cache_key "$scheme$host$request_uri";

proxy_cache_lock

Syntax: proxy_cache_lock on | off
Default: off
Context: http
server
location
Appeared in: 1.1.12
Reference:proxy_cache_lock


When enabled, only one request at a time will be allowed to populate a new cache element identified according to the proxy_cache_key directive by passing a request to a proxied server. Other requests of the same cache element will either wait for a response to appear in the cache, or the cache lock for this element to be released, up to the time set by the proxy_cache_lock_timeout directive.

proxy_cache_lock_timeout

Syntax: proxy_cache_lock_timeout time
Default: 5s
Context: http
server
location
Appeared in: 1.1.12
Reference:proxy_cache_lock_timeout


proxy_cache_methods

syntax: proxy_cache_methods [GET HEAD POST];

default: proxy_cache_methods GET HEAD;

context: http, server, location

GET/HEAD is syntax sugar, i.e. you can not disable GET/HEAD even if you set just

proxy_cache_min_uses

Syntax: proxy_cache_min_uses number
Default: 1
Context: http
server
location
Reference:proxy_cache_min_uses


レスポンスのキャッシングに必要な最小クエリ回数。

proxy_cache_path

Syntax: proxy_cache_path path [ levels = levels ] keys_zone = name : size [ inactive = time ] [ max_size = size ] [ loader_files = number ] [ loader_sleep = time ] [ loader_threshold = time ]
Default:
Context: http
Reference:proxy_cache_path


このディレクティブは、キャッシュパスとキャッシュパラメータを設定します。キャッシュされたデータはファイルに格納されます。キャッシュエントリのキーとしては、プロキシ対象の URL の MD5 ハッシュが用いられます。これはキャッシュパス内でレスポンスのコンテンツとメタデータを格納するファイル名としても用いられます。levels パラメータは、キャッシュ内のサブディレクトリの階層の数を指定します。設定例を次に示します。

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

この場合、ファイル名は次のようになります。

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

levels の形式としては、次のようなものを利用できます: X, X:X, X:X:X 。設定例を示します: "2", "2:2", "1:1:2" 最大 3 階層の設定が可能です。

有効なキーとメタデータは共有メモリに格納されます。ゾーン名とゾーンのサイズは、keys_zone パラメータで指定されます。

各ゾーンには固有のパスを指定する必要があります。次に例を示します。

proxy_cache_path  /data/nginx/cache/one    levels=1      keys_zone=one:10m;
proxy_cache_path  /data/nginx/cache/two    levels=2:2    keys_zone=two:100m;
proxy_cache_path  /data/nginx/cache/three  levels=1:1:2  keys_zone=three:1000m;

キャッシュされたデータが inactive パラメータで指定された期間リクエストされなかった場合、そのデータはキャッシュから消去されます。inactive パラメータのデフォルト値は 10 分 (10m) です。

"cache_manager" という特別なプロセスが、ディスク上のキャッシュを制御するために作成されます。これは利用されていないアイテムを削除することで、キャッシュのサイズが max_size パラメータで指定されたサイズに保たれるようにします。キャッシュのサイズが max_size で指定されたサイズを超過する場合、キャッシュ内にある最後に利用されたデータが、新しいキャッシュエントリの場所を確保するために、消去されます (LRU ポリシー)。

Zone size should be set proportional to number of pages to cache. The size of the metadata for one page (file) depends on the OS; currently it is 64 bytes for FreeBSD/i386, and 128 bytes for FreeBSD/amd64.

The directories specified by proxy_cache_path and proxy_temp_path should be located on the same filesystem.

nginx の起動 1 分後に、"cache loader" という特殊なプロセスが起動し、以前ファイルに格納されたキャッシュデータの情報をゾーンにロードします。ロードは何回かに分けて行われ、各ロードの際は、loader_files で指定された数のアイテム (デフォルト 100) が同時にロードされます。なお、1 回のロード処理は、loader_threshold パラメータ (デフォルト 200 ミリ秒) 以内で行われます。ロードは、loader_sleep パラメータ (デフォルト 50 ミリ秒) で指定された間隔で行われます。

proxy_cache_use_stale

Syntax: proxy_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_502 | http_503 | http_504 | http_404 | off ...
Default: off
Context: http
server
location
Reference:proxy_cache_use_stale


このディレクティブは、nginx にエラーが発生している URL のアイテムをキャッシュから取得することを指定します。このディレクティブのパラメータは 'updating' が追加されていること以外 proxy_next_upstream と同様です。

キャッシュ更新の DoS 状態 (複数のスレッドが同時にキャッシュを更新しようとして DoS 状態になること) を防ぐために、'updating' パラメータを指定することができます。これにより、特定のスレッドがキャッシュの更新を行っている間、ほかのスレッドはキャッシュ内にあるバージョンのアイテムを提供するようになります。

proxy_cache_valid

Syntax: proxy_cache_valid [ code ...] time
Default:
Context: http
server
location
Reference:proxy_cache_valid


このディレクティブはレスポンスコードごとのキャッシング期間を設定します。設定例を以下に示します:

これは、レスポンスコード200および302に対しては、キャッシュ期間を 10 分とし、404 については、キャッシュ期間を 1 分とする例です。

次のように時間だけを指定した場合: If only time is specified:

レスポンスコード200、301、302のみがキャッシュされます。

すべてのレスポンスコードをキャッシュしたい場合は "any" パラメータを用いることもできます:

上位サーバからのキャッシュ関連のディレクティブは、proxy_cache_valid の値に優先します。優先されるじゅんは、(Igor によれば) 次の通りです:

  1. X-Accel-Expires
  2. Expires/Cache-Control
  3. proxy_cache_valid

バックエンドが HTTP ヘッダを返却する順番によって、挙動が異なります。 詳細は this post を読んでください。

次の設定を行うことで、ヘッダによる設定を無視できます:

proxy_ignore_headers X-Accel-Expires Expires Cache-Control;

Concerning If-Modified / Last-Modified since behaviour, please remember that by default nginx sends 304 only if L-M == I-M-S. Controlled by directive if_modified_since [off|exact|before]

Note: you must set this option for any persistent caching to occur.

proxy_connect_timeout

Syntax: proxy_connect_timeout time
Default: 60s
Context: http
server
location
Reference:proxy_connect_timeout


This directive assigns a timeout for the connection to the upstream server. It is necessary to keep in mind that this time out cannot be more than 75 seconds.

This is not the time until the server returns the pages, that is the proxy_read_timeout statement. If your upstream server is up, but hanging (e.g. it does not have enough threads to process your request so it puts you in the pool of connections to deal with later), then this statement will not help as the connection to the server has been made.

proxy_cookie_domain

Syntax: proxy_cookie_domain off
proxy_cookie_domain domain replacement
Default: off
Context: http
server
location
Appeared in: 1.1.15
Reference:proxy_cookie_domain


proxy_cookie_path

Syntax: proxy_cookie_path off
proxy_cookie_path path replacement
Default: off
Context: http
server
location
Appeared in: 1.1.15
Reference:proxy_cookie_path


proxy_headers_hash_bucket_size

syntax: proxy_headers_hash_bucket_size size;

default: proxy_headers_hash_bucket_size 64;

context: http, server, location, if

This directive sets the bucket size of the headers hash table.
This determines the limit of the header name. If you use header names longer than 64 characters then increase this.

proxy_headers_hash_max_size

syntax: proxy_headers_hash_max_size size;

default: proxy_headers_hash_max_size 512;

context: http, server, location, if

This directive sets the maximum size of the headers hash table.
Should not be smaller than the amount of headers your back-end is setting.

proxy_hide_header

Syntax: proxy_hide_header field
Default:
Context: http
server
location
Reference:proxy_hide_header


nginx does not transfer the "Date", "Server", "X-Pad" and "X-Accel-..." header lines from the proxied server response. The proxy_hide_header directive allows to hide some additional header lines. But if on the contrary the header lines must be passed, then the proxy_pass_header should be used. For example if you want to hide the MS-OfficeWebserver and the AspNet-Version:

location / {
  proxy_hide_header X-AspNet-Version;
  proxy_hide_header MicrosoftOfficeWebServer;
}

This directive can also be very helpful when using X-Accel-Redirect. For example, you may have one set of backend servers which return the headers for a file download, which includes X-Accel-Redirect to the actual file, as well as the correct Content-Type. However, the Redirect URL points to a files erver which hosts the actual file you wish to serve, and that server sends its own Content-Type header, which might be incorrect, and overrides the header sent by the original backend servers. You can avoid this by adding the proxy_hide_header directive to the fileserver. Example:

location / {
  proxy_pass http://backend_servers;
}
 
location /files/ {
  proxy_pass http://fileserver;
  proxy_hide_header Content-Type;
}

proxy_http_version

Syntax: proxy_http_version 1.0 | 1.1
Default: 1.0
Context: http
server
location
Appeared in: 1.1.4
Reference:proxy_http_version


proxy_ignore_client_abort

Syntax: proxy_ignore_client_abort on | off
Default: off
Context: http
server
location
Reference:proxy_ignore_client_abort


Prevents aborting request to proxy in case the client itself aborts the request.

proxy_ignore_headers

Syntax: proxy_ignore_headers field ...
Default:
Context: http
server
location
Reference:proxy_ignore_headers


Prohibits the processing of the header lines from the proxy server's response.

It can specify the string as "X-Accel-Redirect", "X-Accel-Expires", "Expires", "Cache-Control" or "Set-Cookie". By default, nginx does not caches requests with Set-Cookie.

proxy_intercept_errors

Syntax: proxy_intercept_errors on | off
Default: off
Context: http
server
location
Reference:proxy_intercept_errors


このディレクティブは、nginx が HTTPステータスコード 400 以上となるレスポンスをerror_pageディレクティブの処理対象とすることを指定します。

デフォルトでは、すべてのレスポンスがプロキシ対象のサーバからそのまま返却されます。

このディレクティブをon に設定した場合、nginx は error_pageディレクティブで処理対象として明示的に指定されたステータスコードを処理します。error_page ディレクティブで指定されていないステータスコードのレスポンスは、プロキシ対象のサーバからそのまま返却されます。

proxy_max_temp_file_size

Syntax: proxy_max_temp_file_size size
Default: 1024m
Context: http
server
location
Reference:proxy_max_temp_file_size


The maximum size of a temporary file when the content is larger than the proxy buffer. If file is larger than this size, it will be served synchronously from upstream server rather than buffered to disk.

If proxy_max_temp_file_size is equal to zero, temporary files usage will be disabled.

proxy_method

syntax: proxy_method [method];

default: None

context: http, server, location

Allows you to override the HTTP method of the request to be passed to the backend server. If you specify POST for example, all requests forwarded to the backend server will be POST requests.

Example:

proxy_next_upstream

Syntax: proxy_next_upstream error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_404 | off ...
Default: error timeout
Context: http
server
location
Reference:proxy_next_upstream


Directive determines in what cases the request will be transmitted to the next server:

  • error — an error has occurred while connecting to the server, sending a request to it, or reading its response;
  • timeout — occurred timeout during the connection with the server, transfer the request or while reading response from the server;
  • invalid_header — server returned a empty or incorrect answer;
  • http_500 — server returned answer with code 500
  • http_502 — server returned answer with code 502
  • http_503 — server returned answer with code 503
  • http_504 — server returned answer with code 504
  • http_404 — server returned answer with code 404
  • off — it forbids the request transfer to the next server

Transferring the request to the next server is only possible when nothing has been transferred to the client -- that is, if an error or timeout arises in the middle of the transfer of the request, then it is not possible to retry the current request on a different server.

proxy_no_cache

Syntax: proxy_no_cache string ...
Default:
Context: http
server
location
Reference:proxy_no_cache


レスポンスをキャッシュしない条件を指定します。

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

展開した引数のすべてが "0" もしくは空文字列以外にならない限り、レスポンスはキャッシュされません。上記の例では、Cookie で "nocache" がリクエストに設定されていた場合、レスポンスはキャッシュされません。

proxy_pass

Syntax: proxy_pass URL
Default:
Context: location
if in location
limit_except
Reference:proxy_pass


This directive sets the address of the proxied server and the URI to which location will be mapped. Address may be given as hostname or address and port, for example,

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

or as unix socket path:

proxy_pass http://unix:/path/to/backend.socket:/uri/;

path is given after the word unix between two colons.

By default, the Host header from the request is not forwarded, but is set based on the proxy_pass statement. To forward the requested Host header, it is necessary to use:

proxy_set_header Host $host;

While passing request nginx replaces URI part which corresponds to location with one indicated in proxy_pass directive. But there are two exceptions from this rule when it is not possible to determine what to replace:

  • if the location is given by regular expression;
  • if inside proxied location URI is changed by rewrite directive, and this configuration will be used to process request (break):
location  /name/ {
  rewrite      /name/([^/] +)  /users?name=$1  break;
  proxy_pass   http://127.0.0.1;
}

For these cases of URI it is transferred without the mapping.

Furthermore, it is possible to indicate so that URI should be transferred in the same form as sent by client, not in processed form. During processing:

  • two or by more slashes are converted into one slash: "//" -- "/";
  • references to the current directory are removed: "/./" -- "/";
  • references to the previous catalog are removed: "/dir /../" -- "/".

If it is necessary to transmit URI in the unprocessed form then directive proxy_pass should be used without URI part:

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

A special case is using variables in the proxy_pass statement: The requested URL is not used and you are fully responsible to construct the target URL yourself.

This means, the following is not what you want for rewriting into a zope virtual host monster, as it will proxy always to the same URL (within one server specification):

location / {
  proxy_pass   http://127.0.0.1:8080/VirtualHostBase/https/$server_name:443/some/path/VirtualHostRoot;
}

Instead use a combination of rewrite and proxy_pass:

location / {
  rewrite ^(.*)$ /VirtualHostBase/https/$server_name:443/some/path/VirtualHostRoot$1 break;
  proxy_pass   http://127.0.0.1:8080;
}

In this case URL sanitizing is done already as part of the rewriting process, i.e. a trailing slash with the proxy_pass statement has no further effect.

If you need the proxy connection to an upstream server group to use SSL, your proxy_pass rule should use https:// and you will also have to set your SSL port explicitly in the upstream definition. Example:

upstream backend-secure {
  server 10.0.0.20:443;
}
 
server {
  listen 10.0.0.1:443;
  location / {
    proxy_pass https://backend-secure;
  }
}

proxy_pass_header

Syntax: proxy_pass_header field
Default:
Context: http
server
location
Reference:proxy_pass_header


This directive allows transferring header-lines forbidden for response.

For example:

location / {
  proxy_pass_header X-Accel-Redirect;
}


proxy_pass_request_body

syntax: proxy_pass_request_body [ on | off ];

default: proxy_pass_request_body on;

context: http, server, location

version: ≥ 0.1.29

Defines whether or not the request body should be passed to the proxy.
Should usually be left on. If you switch it off, do not forget to add:

proxy_set_header Content-Length 0;

proxy_pass_request_headers

syntax: proxy_pass_request_headers [ on | off ];

default: proxy_pass_request_headers on;

context: http, server, location

version: ≥ 0.1.29

Defines whether or not the request headers should be passed to the proxy.
Should usually be left on.

proxy_redirect

Syntax: proxy_redirect default
proxy_redirect off
proxy_redirect redirect replacement
Default: default
Context: http
server
location
Reference:proxy_redirect


This directive sets the text, which must be changed in response-header "Location" and "Refresh" in the response of the proxied server.

Let us suppose the proxied server returned line Location: http://localhost:8000/two/some/uri/.

The directive

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

will rewrite this line in the form Location: http://frontend/one/some/uri/.

In the replaceable line it is possible not to indicate the name of the server:

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

then the basic name of server and port is set, if it is different from 80.

The change by default, given by the parameter "default", uses the parameters of directives location and proxy_pass.

Therefore two following configurations are equivalent:

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

In the replace line, it is possible to use some variables:

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

This directive repeated some times:

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

The parameter off forbids all proxy_redirect directives at this level:

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

With the help of this directive it is possible to add the name of host for relative redirect, issued by the proxied server:

proxy_read_timeout

Syntax: proxy_read_timeout time
Default: 60s
Context: http
server
location
Reference:proxy_read_timeout


This directive sets the read timeout for the response of the proxied server. It determines how long nginx will wait to get the response to a request. The timeout is established not for entire response, but only between two operations of reading.

In contrast to proxy_connect_timeout, this timeout will catch a server that puts you in it's connection pool but does not respond to you with anything beyond that. Be careful though not to set this too low, as your proxy server might take a longer time to respond to requests on purpose (e.g. when serving you a report page that takes some time to compute). You are able though to have a different setting per location, which enables you to have a higher proxy_read_timeout for the report page's location.

proxy_redirect_errors

Deprecated. Use proxy_intercept_errors.

proxy_send_lowat

syntax: proxy_send_lowat [ on | off ];

default: proxy_send_lowat off;

context: http, server, location, if

This directive set SO_SNDLOWAT.
This directive is only available on FreeBSD

proxy_send_timeout

Syntax: proxy_send_timeout time
Default: 60s
Context: http
server
location
Reference:proxy_send_timeout


This directive assigns timeout with the transfer of request to the upstream server. Timeout is established not on entire transfer of request, but only between two write operations. If after this time the upstream server will not take new data, then nginx is shutdown the connection.

proxy_set_body

syntax: proxy_set_body value;

default: none

context: http, server, location, if

version: >= 0.3.10

Set the body value passed to the backend. This value can contain variables.

proxy_set_header

Syntax: proxy_set_header field value
Default: Host $proxy_host
Connection close
Context: http
server
location
Reference:proxy_set_header


このディレクティブにより、プロキシ対象のサーバから転送されてきたリクエストヘッダの再定義や追加が可能となります。

値としては、文字列、変数、両方の組み合わせが利用できます。

proxy_set_header directives issued at higher levels are only inherited when no proxy_set_header directives have been issued at a given level.

デフォルトでは、次の 2 行だけが再定義されます:

proxy_set_header Host $proxy_host;
proxy_set_header Connection Close;

変更されないリクエストヘッダである "Host" は、次のようにして転送されます:

proxy_set_header Host $http_host;

ただし、クライアントからのリクエストに上記が存在しない場合は、何も転送されません。

この場合は、$host 変数を用いるのがよいでしょう。この変数の値は、"Host" リクエストヘッダに含まれるサーバ名か、該当のリクエストヘッダが存在しない場合はサーバの基本的な名前になります:

proxy_set_header Host $host;

更に、サーバ名と併せて、プロキシ対象のサーバのポート番号を転送することも可能です:

proxy_set_header Host $host:$proxy_port;

値が空文字列の場合、このヘッダは上位サーバに送信されません。たとえば、次の設定を行うことで、上位サーバに対して gzip 圧縮が行われなくなります:

proxy_set_header  Accept-Encoding  "";

proxy_ssl_session_reuse

Syntax: proxy_ssl_session_reuse on | off
Default: on
Context: http
server
location
Reference:proxy_ssl_session_reuse


Attempt to reuse ssl session when connecting to upstream via https.

proxy_store

Syntax: proxy_store on | off | string
Default: off
Context: http
server
location
Reference:proxy_store


This directive sets the path in which upstream files are stored. The parameter "on" preserves files in accordance with path specified in directives alias or root. The parameter "off" forbids storing. Furthermore, the name of the path can be clearly assigned with the aid of the line with the variables:

proxy_store   /data/www$uri;

The time of modification for the file will be set to the date of "Last-Modified" header in the response. To be able to safe files in this directory it is necessary that the path is under the directory with temporary files, given by directive proxy_temp_path for the data location.

This directive can be used for creating the local copies for dynamic output of the backend which is not very often changed, for example:

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 this way:

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

To be clear proxy_store is not a cache, it's rather mirror on demand.

proxy_store_access

Syntax: proxy_store_access users : permissions ...
Default: user:rw
Context: http
server
location
Reference:proxy_store_access


This directive assigns the permissions for the created files and directories, for example:

proxy_store_access  user:rw  group:rw  all:r;

If any rights for groups or all are assigned, then it is not necessary to assign rights for user:

proxy_store_access  group:rw  all:r;


proxy_temp_file_write_size

Syntax: proxy_temp_file_write_size size
Default: 8k|16k
Context: http
server
location
Reference:proxy_temp_file_write_size


Sets the amount of data that will be flushed to the proxy_temp_path when writing. It may be used to prevent a worker process blocking for too long while spooling data.

proxy_temp_path

Syntax: proxy_temp_path path [ level1 [ level2 [ level3 ]]]
Default: proxy_temp
Context: http
server
location
Reference:proxy_temp_path


This directive works like client_body_temp_path to specify a location to buffer large proxied requests to the filesystem.

proxy_upstream_fail_timeout

deprecated: 0.5.0 -- upstream モジュールの server ディレクティブの fail_timeout パラメータを用いること

proxy_upstream_max_fails

deprecated: 0.5.0 -- Please use the max_fails parameter of server directive from the upstream module.

変数

ngx_http_proxy_module モジュールには、幾つかの変数があります。これらは proxy_set_header ディレクティブを用いてヘッダを生成する際に用いることができます:

$proxy_add_x_forwarded_for

クライアントからの "X-Forwarded-For" リクエストヘッダの内容に、 $remote_addr をコンマで区切って加えたものが含まれます。X-Forwarded-For リクエストヘッダが存在しない場合、$proxy_add_x_forwarded_for は $remote_addr と同じ値になります。

$proxy_host

リクエストを処理する上位サーバ名

$proxy_internal_body_length

proxy_set_body によって設定されたプロキシのリクエストボディ長

$proxy_port

リクエストを処理する上位サーバのポート番号

References

Original Documentation

Using Apache and Nginx together with the Proxy Module