ngx_http_proxy_module

This module makes it possible to transfer requests to another server.

It is an HTTP/1.0 proxy without the ability for keep-alive requests yet. (As a result, backend connections are created and destroyed on every request.) Nginx talks HTTP/1.1 to the browser and HTTP/1.0 to the backend server. As such it handles keep-alive to the browser.

Example configurations 

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

Note that when using the HTTP Proxy Module (or even when using FastCGI), the entire client request will be buffered in nginx before being passed on to the backend proxied servers. As a result, upload progress meters will not function correctly if they work by measuring the data received by the backend servers.

Directives

Variables

proxy_buffer_size

syntax: proxy_buffer_size the_size

default: proxy_buffer_size 4k/8k

context: http, server, location

This directive set the buffersize, into which will be read the first part of the response, obtained from the proxied server.

In this part of response the small response-header is located, as a rule.

By default, the buffersize is equal to the size of one buffer in directive proxy_buffers; however, it is possible to set it to less.

proxy_buffering

syntax: proxy_buffering on|off

default: proxy_buffering on

context: http, server, location

This directive activate response buffering of the proxied server.

If buffering is activated, then nginx assumes the answer of the proxied server as fast as possible, preserving it in the buffer, assigned by directive proxy_buffer_size and proxy_buffers.

If the response can not all be placed in memory, then parts of it will be written to disk.

If buffering is switched off, then the response is synchronously transferred to client immediately as it is received.

nginx do not attempt to count entire answer of the proxied server, maximum size of data, which nginx can accept from the server it is assigned by directive proxy_buffer_size.

For Comet aplications based on long-polling it is important to set proxy_buffering to off, otherwise the asynchronous response is buffered and the Comet does not work.

proxy_buffers

syntax: proxy_buffers the_number is_size;

default: proxy_buffers 8 4k/8k;

context: http, server, location

This directive sets the number and the size of buffers, into which will be read the answer, obtained from the proxied server. By default, the size of one buffer is equal to the size of page. Depending on platform this is either 4K or 8K.

proxy_busy_buffers_size

syntax: proxy_busy_buffers_size size;

default: proxy_busy_buffers_size #proxy buffer size * 2;

context: http, server, location, if

TODO: Description.

proxy_connect_timeout

syntax: proxy_connect_timeout timeout_in_seconds

context: http, server, location

This directive assigns a timeout for the connection to the proxyserver. This is not the time until the server returns the pages, this is the proxy_read_timeout statement. If your proxyserver 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. It is necessary to keep in mind that this time out cannot be more than 75 seconds.

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 hashtable.
TODO: Better description

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 hashtable.
TODO: Better description

proxy_hide_header

syntax: proxy_hide_header the_header

context: http, server, location

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: 

# Hide the MS-OfficeWebserver and the AspNet-Version headers
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 filleserver 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_ignore_client_abort

syntax: proxy_ignore_client_abort [ on|off ]

default: proxy_ignore_client_abort off

context: http, server, location

Available since: 0.3.36
Prevents aborting request to proxy in case the client itself aborts the request.

proxy_intercept_errors

syntax: proxy_intercept_errors [ on|off ]

default: proxy_intercept_errors off

context: http, server, location

This directive decides if nginx will intercept responses with HTTP status codes of 400 and higher.

By default all responses will be sent as-is from the proxied server.

If you set this to on then nginx will intercept status codes that are explicitly handled by an error_page directive. Responses with status codes that do not match an error_page directive will be sent as-is from the proxied server.

proxy_max_temp_file_size

syntax: proxy_max_temp_file_size size;

default: proxy_max_temp_file_size 1G;

context: http, server, location, if

Available since: 0.1.8
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.

proxy_method

syntax: proxy_method [method]

default: None

context: http, server, location

Used to allow the proxying of additional HTTP methods.

Note: at this time, Nginx only appears to allow a single instance of this directive and it only accepts a single argument (method) so it's not clear how useful this might be for proxying to things like Subversion.

Example: 

    proxy_method PROPFIND;

proxy_next_upstream

syntax: proxy_next_upstream [error|timeout|invalid_header|http_500|http_503|http_404|off]

default: proxy_next_upstream error timeout

context: http, server, location

Directive determines, in what cases the request will be transmitted 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_pass

syntax: proxy_pass URL

default: no

context: location, if in location

This directive sets the port or socket, on which listens to the proxied server, and the URI, to which will be reflected location.

Port can be indicated in the form of the name of hostname or address and port, for example, 

proxy_pass http://localhost:8000/uri;

and socket -- in the form of unix of socket: 

proxy_pass unix:/path/to/backend.socket

Path is indicated after the word unix and is concluded between two colons.

With the transfer of request to server part URI, which corresponds to location, is substituted to URI, indicated in directive proxy_pass.

But there are two exceptions to this rule, when it is not possible to determine that replaced location: 

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 demand it would be transferred in the same form, as it sent client, but not v in the processed form.

During the working:

If on server it is necessary to transmit URI in the unprocessed form, then for this in directive proxy_pass it is necessary to indicate URL server without URI: 

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

proxy_pass_header

syntax: proxy_pass_header the_name

context: http, server, location

This directive allows transferring header-lines forbidden for response.

For example: 

location / {
  proxy_pass_header Server;
  proxy_pass_header X-MyHeader;
}

proxy_pass_request_body

syntax: proxy_pass_request_body [ on | off ];

default: proxy_pass_request_body on;

context: http, server, location

Available since: 0.1.29
TODO: Description.

proxy_pass_request_headers

syntax: proxy_pass_request_headers [ on | off ];

default: proxy_pass_request_headers on;

context: http, server, location

Available since: 0.1.29
TODO: Description.

proxy_redirect

syntax: proxy_redirect [ default|off|redirect replacement ]

default: proxy_redirect default

context: http, server, location

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

proxy_read_timeout

syntax: proxy_read_timeout the_time

default: proxy_read_timeout 60

context: http, server, location

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 proxyserver 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.

If the proxied server nothing will communicate after this time, then nginx is shut connection.

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_in_seconds

default: proxy_send_timeout 60

context: http, server, location

This directive assigns timeout with the transfer of request to the proxy server. Time out is established not on entire transfer of request, but only between two operations of record. If after this time the proxy server will not take new data, then nginx is shut the connection

proxy_set_body

syntax: proxy_set_body [ on | off ]

default: proxy_set_body off;

context: http, server, location, if

Available since: 0.3.10
TODO: Description.

proxy_set_header

syntax: proxy_set_header header value

default: Host and Connection

context: http, server, location

This directive allows to redefine and to add some request header lines which will be transferred to the proxied server.

As the value it is possible to use a text, variables and their combination.

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

By default only two lines will be redefined: 

proxy_set_header Host $proxy_host;
proxy_set_header Connection Close;

The unchanged request-header "Host" can be transmitted like this: 

proxy_set_header Host $http_host;

However, if this line is absent from the client request, then nothing will be transferred.

In this case it is better to use variable $host, it's value is equal to the name of server in the request-header "Host" or to the basic name of server, if there is no line: 

proxy_set_header Host $host;

Furthermore, it is possible to transmit the name of server together with the port of the proxied server: 

proxy_set_header Host $host:$proxy_port;

proxy_store

syntax: proxy_store [on | off | path]

default: proxy_store off

context: http, server, location

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

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

proxy_store_access

syntax: proxy_store_access users:permissions [users:permission ...]

default: proxy_store_access user:rw

context: http, server, location

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: proxy_temp_file_write_size #proxy buffer size * 2;

context: http, server, location, if

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 dir-path [ level1 [ level2 [ level3 ] ] ];

default: $NGX_PREFIX/proxy_temp controlled by --http-proxy-temp-path at ./configure stage

context: http, server, location

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

proxy_upstream_fail_timeout

Changed in 0.5.0 to deprecated.
Please use the fail_timeout parameter of server Directive from the upstream module.

proxy_upstream_max_fails

Changed in 0.5.0 to deprecated.
Please use the max_fails parameter of server Directive from the upstream module.

Variables

In module ngx_http_proxy_module there are some built-in variables, which can be used for the creation of headers with the help of the proxy_set_header directive:

$proxy_host:: the name of proxied host and port;

$proxy_port:: the port of proxied host;

$proxy_add_x_forwarded_for:: equivalent to client request-header "X-Forwarded-For" and to variable added to it through the comma

$remote_addr:: But if there is no line "X-Forwarded-For" in the client request, then variable $proxy_add_x_forwarded_for is equal to variable $remote_addr.

References

Original Documentation

Questions

NginxHttpProxyModule (last edited 2008-10-31 13:08:28 by AndrzejRusin)