+ + +size +4k|8k +http +server +location + + +Sets size of the buffer used for reading the first part +of a response received from the proxied server. +This part usually contains a small response header. +By default, the buffer size is equal to the size of one +buffer set by the directive. +It can be made smaller however. + + + + + + +on | off +on +http +server +location + + +Enables or disables buffering a response from the proxied server. + + + +When buffering is enabled, nginx receives a response from the proxied server +as soon as possible, saving it into buffers set by the + and directives. +If the whole response does not fit into memory, part of it is saved to a disk. + + + +When buffering is disabled, a response is passed to a client synchronously, +immediately upon receipt. +nginx will not try to read the whole response from the proxied server. +The maximum size of the data that nginx can receive from the server +at a time is set by the directive. + + + + + + +number size +8 4k|8k +http +server +location + + +Sets the number and size of +buffers used for reading a response from the proxied server, +for a single connection. +By default, the buffer size is equal to one memory page. +This is either 4K or 8K, depending on a platform. + + + + + + +zone | off +off +http +server +location + + +Defines a zone used for caching. +The same zone can be used in several places. +The off parameter disables caching inherited +from the previous configuration level. + + + + + + +string ... + +http +server +location + + +Defines conditions under which the answer will not be taken from a cache. +If at least one value of the string parameters is not empty and is not +equal to “0” then the answer will not be taken from the cache: + +proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment; +proxy_cache_bypass $http_pragma $http_authorization; + +Can be used along with the directive. + + + + + + +string +$scheme$proxy_host$request_uri +http +server +location + + +Defines a key for caching, for example + +proxy_cache_key "$host$request_uri $cookie_user"; + +By default, the directive’s value is close to the string + +proxy_cache_key $scheme$proxy_host$uri$is_args$args; + + + + + + + +number +1 +http +server +location + + +Sets the number of requests after which the response +will be cached. + + + + + + + + path + [levels=levels] + keys_zone=name:size + [inactive=time] + [max_size=size] + +http + + +Sets path and other parameters of a cache. +Cache data are stored in files. +Both the key and file name in a cache are a result of +applying the MD5 function to the proxied URL. + +The levels parameter defines hierarchy levels of a cache. +For example, in the following configuration + +proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m; + +file names in a cache will look like this: + +/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c + + + + +A cached response is first written to a temporary file, then a file is renamed. +Starting from version 0.8.9 temporary files and the cache can be put on +different file systems but be aware that in this case a file is copied +across two file systems instead of the cheap rename operation. +It is thus recommended that for any given location both cache and a directory +holding temporary files set by the directive +are put on the same file system. + + + +In addition, all active keys and information about data are stored +in a shared memory zone, whose name and size +are configured by the keys_zone parameter. +Cached data that are not accessed during the time specified by the +inactive parameter get removed from the cache +regardless of their freshness. +By default, inactive is set to 10 minutes. + + + +The special process “cache manager” monitors the maximum cache size set +by the max_size parameter; +when this size is exceeded it removes the least recently used data. + + + + + + + + error | + timeout | + invalid_header | + updating | + http_500 | + http_502 | + http_503 | + http_504 | + http_404 | + off + ... +off +http +server +location + + +If an error occurs while working with the proxied server it is possible +to use a stale cached response. +This directives determines in which cases it is permitted. +The directive’s parameters match those of the + directive. +Additionally, the updating parameter permits +to use a stale cached response if it is currently being updated. + + + + + + +[code ...] time + +http +server +location + + +Sets caching time for different response codes. +For example, the following directives + +proxy_cache_valid 200 302 10m; +proxy_cache_valid 404 1m; + +set 10 minutes of caching for responses with codes 200 and 302, +and 1 minute for responses with code 404. + + + +If only caching time is specified + +proxy_cache_valid 5m; + +then only 200, 301, and 302 responses are cached. + + + +In addition, it can be specified to cache any answers using the +any parameter: + +proxy_cache_valid 200 302 10m; +proxy_cache_valid 301 1h; +proxy_cache_valid any 1m; + + + + + + + +time +60s +http +server +location + + +Defines a timeout for establishing a connection with the proxied server. +It should be noted that this timeout cannot usually exceed 75 seconds. + + + + + + +field + +http +server +location + + +By default, +nginx does not pass the header fields

Date

, +

Server

X-Pad

, and +

X-Accel-...

from the response of a proxied +server to a client. +The proxy_hide_header directive sets additional fields +that will not be passed. +If, on the contrary, the passing of fields needs to be enabled, +the directive can be used. + + + + + + +on | off +off +http +server +location + + +Determines should the connection with a proxied server be +closed if a client closes a connection without waiting +for an answer. + + + + + + +field ... + +http +server +location + + +Disables processing of some response header fields from the proxied server. +The following fields can be ignored:

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

, and

Set-Cookie

(0.8.44). + + + + + + +on | off +off +http +server +location + + +Determines whether proxied responses with codes greater or equal to 400 +should be passed to a client or be redirected to nginx for processing +using the directive. + + + + + + + + error | + timeout | + invalid_header | + http_500 | + http_502 | + http_503 | + http_504 | + http_404 | + off + ... +error timeout +http +server +location + + +Specifies in which cases a request should be passed to the next server: + + +error +an error occurred while establishing a connection with the +server, passing it a request, or reading the response header; + +timeout +a timeout has occurred while establishing a connection with the +server, passing it a request, or reading the response header; + +invalid_header +a server returned empty or invalid response; + +http_500 +a server returned a response with the code 500; + +http_502 +a server returned a response with the code 502; + +http_503 +a server returned a response with the code 503; + +http_504 +a server returned a response with the code 504; + +http_404 +a server returned a response with the code 404; + +off +disables passing a request to the next server. + + + + + +It should be understood that passing a request to the next server is +only possible if a client was not sent anything yet. +That is, if an error or a timeout occurs in the middle of +transferring a response, fixing this is impossible. + + + + + + +string ... + +http +server +location + + +Defines conditions under which the answer will not be saved to a cache. +If at least one value of the string parameters is not empty and is not +equal to “0” then the answer will not be saved: + +proxy_no_cache $cookie_nocache $arg_nocache$arg_comment; +proxy_no_cache $http_pragma $http_authorization; + +Can be used along with the directive. + + + + + + +URL + +location +if in location +limit_except + + +Sets an address of the proxied server and a URI that maps a location. +An address can be specified as a domain name or an address, and a port, +for example, + + proxy_pass http://localhost:8000/uri/; + +or as a UNIX-domain socket path: + + proxy_pass http://unix:/tmp/backend.socket:/uri/; + +here a path is specified after the word “unix” +and enclosed in two colons. + + + +If a domain name maps to several addresses, all of them will be +used in a round-robin fashion. +In addition, an address can be specified as a +server group. + + + +When passing a request to the server, part of a URI matching the location +is replaced by a URI specified in the proxy_pass directive. +This rule has two exceptions where a replacement location cannot be +defined: + + + +when a location is specified using a regular expression; + + + +if a URI is changed using the + directive +inside a proxied location, and this same configuration will be +used to process a request (break): + +location /name/ { + rewrite /name/([^/]+) /users?name=$1 break; + proxy_pass http://127.0.0.1; +} + +In these cases a URI is passed without mapping. + + + + + + +It can also be specified that a request URI should be passed unchanged, +in the same form it was sent by the client, not the processed form. +During a processing + + + +two or more adjacent slashes are replaced by one: “//” — “/”; + + + +links to the current directory get removed: “/./” — “/”; + + + +links to the parent directory get removed: “/dir/../” — “/”. + + + + + + +If a URI should be passed unchanged then the server URL should be specified +without a URI in the proxy_pass directive: + +location /some/path/ { + proxy_pass http://127.0.0.1; +} + + + + +Server name, its port, and passed URI can be specified using variables: + + proxy_pass http://$host$uri; + +or like this: + + proxy_pass $request; + + + + +In this case the server name is searched among the described +server groups, +and if not found is determined using a +. + + + + + + +field + +http +server +location + + +Permits to pass otherwise disabled header +fields from a proxied server to a client. + + + + + + +time +60s +http +server +location + + +Defines a timeout for reading a response from the proxied server. +A timeout is only set between two successive read operations, +not for the transmission of the whole response. +If a proxied server does not transmit anything within this time, +a connection is closed. + + + + + + +default +off +redirect replacement +default +http +server +location + + +Sets a text that should be changed in the header fields +

Location

and

Refresh

of a response +from the proxied server. +Suppose a proxied server returned the header field +“Location: http://localhost:8000/two/some/uri/”. +The directive + + proxy_redirect http://localhost:8000/two/ http://frontend/one/; + +will rewrite this string to +“Location: http://frontend/one/some/uri/”. + + + +A server name may be omitted from the replacement string: + + proxy_redirect http://localhost:8000/two/ /; + +then the primary server’s name and a port, if different from 80, +will be substituted. + + + +The default replacement specified by the default parameter +uses the parameters of the + and + directives. +Hence, the two configurations below 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/; + +The default parameter is not permitted if + is specified using variables. + + + +A replacement string can contain variables: + + proxy_redirect http://localhost:8000/ http://$host:$server_port/; + + + + +A redirect can also contain (1.1.11) variables: + + proxy_redirect http://$proxy_host:8000/ /; + + + + +A directive can be specified (1.1.11) using regular expressions. +In this case, replacement should either start from +the “~” symbol for a case-sensitive matching, +or from the “~*” symbols for case-insensitive +matching. +A regular expression can contain named and positional captures, +and replacement can reference them: + + proxy_redirect ~^(http://[^:]+):\d+(/.+)$ $1$2; + proxy_redirect ~*/user/([^/]+)/(.+)$ http://$1.example.com/$2; + + + + +There could be several proxy_redirect directives: + + proxy_redirect default; + proxy_redirect http://localhost:8000/ /; + proxy_redirect http://www.example.com/ /; + + + + +The off parameter cancels all +proxy_redirect directives on the current level: + + proxy_redirect off; + proxy_redirect default; + proxy_redirect http://localhost:8000/ /; + proxy_redirect http://www.example.com/ /; + + + + +Using this directive it is also possible to add host names to relative +redirects issued by a proxied server: + + proxy_redirect / /; + + + + + + + +time +60s +http +server +location + + +Sets a timeout for transmitting a request to the proxied server. +A timeout is only set between two successive write operations, +not for the transmission of the whole request. +If a proxied server does not receive anything within this time, +a connection is closed. + + + + + + +field value +Host $proxy_host +Connection close +http +server +location + + +Allows to redefine or append fields to the request header +passed to the proxied server. +A value can contain text, variables, and their combination. +These directives are inherited from the previous level if and +only if there are no +proxy_set_header +directives defined on the current level. +By default, only two fields are redefined: + +proxy_set_header Host $proxy_host; +proxy_set_header Connection close; + + + + +An unchanged

Host

request header field can be passed like this: + +proxy_set_header Host $http_host; + + + + +However, if this field is not present in a client request header then +nothing will be passed. +In such a case it is better to use the $host variable—its +value equals the server name in the

Host

request header +field, or the primary server name if this field is not present: + +proxy_set_header Host $host; + + + + +In addition, a server name can be passed together with a port of the +proxied server: + +proxy_set_header Host $host:$proxy_port; + + + + +If the value of a header field is an empty string then this +field will not be passed to a proxied server: + +proxy_set_header Accept-Encoding ""; + + + + + + + +on | off +on +http +server +location + + +Determines whether SSL sessions can be reused when working with +the proxied server. +If the errors +“SSL3_GET_FINISHED:digest check failed” +appear in the logs, try to disable session reuse. + + + + + + + + on | + off | + string +off +http +server +location + + +Enables saving of files to a disk. +The on parameter saves files with paths +corresponding to the directives + or +. +The off parameter disables saving of files. +In addition, the file name can be set explicitly using the +string with variables: + +proxy_store /data/www$original_uri; + + + + +The modification time of files is set according to the received +

Last-Modified

response header field. +A response is first written to a temporary file, then a file is renamed. +Starting from version 0.8.9 temporary files and the persistent store +can be put on different file systems but be aware that in this case +a file is copied across two file systems instead of the cheap rename operation. +It is thus recommended that for any given location both saved files and a +directory holding temporary files set by the +directive are put on the same file system. + + + +This directive can be used to create local copies of static unchangeable +files, e.g.: + +location /images/ { + root /data/www; + open_file_cache_errors off; + 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; +} + + + + + + + +users:permissions ... +user:rw +http +server +location + + +Sets access permissions for newly created files and directories, e.g.: + +proxy_store_access user:rw group:rw all:r; + + + + +If any group or all access permissions +are specified then user permissions may be omitted: + +proxy_store_access group:rw all:r; + + + + + + + + + path + [level1 + [level2 + [level3]]] +proxy_temp +http +server +location + + +Defines a directory for storing temporary files +received from another server. +Up to three-level subdirectory hierarchy can be used underneath the specified +directory. +For example, in the following configuration + +proxy_temp_path /spool/nginx/proxy_temp 1 2; + +a temporary file might look like this: + +/spool/nginx/proxy_temp/7/45/00000123457 + + + + + +