Proxy pass что означает

0

The ngx_http_proxy_module module allows passing requests to another server.

Example Configuration

Directives

This directive appeared in version 0.8.22.

Makes outgoing connections to a proxied server originate from the specified local IP address with an optional port (1.11.2). Parameter value can contain variables (1.3.12). The special value off (1.3.12) cancels the effect of the proxy_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address and port.

The transparent parameter (1.11.0) allows outgoing connections to a proxied server originate from a non-local IP address, for example, from a real IP address of a client:

In order for this parameter to work, it is usually necessary to run nginx worker processes with the superuser privileges. On Linux it is not required (1.13.8) as if the transparent parameter is specified, worker processes inherit the CAP_NET_RAW capability from the master process. It is also necessary to configure kernel routing table to intercept network traffic from the proxied server.

Sets the size of the buffer used for reading the first part of the response received from the proxied server. This part usually contains a small response header. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform. It can be made smaller, however.

Enables or disables buffering of responses from the proxied server.

When buffering is enabled, nginx receives a response from the proxied server as soon as possible, saving it into the buffers set by the proxy_buffer_size and proxy_buffers directives. If the whole response does not fit into memory, a part of it can be saved to a temporary file on the disk. Writing to temporary files is controlled by the proxy_max_temp_file_size and proxy_temp_file_write_size directives.

When buffering is disabled, the response is passed to a client synchronously, immediately as it is received. 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 proxy_buffer_size directive.

Buffering can also be enabled or disabled by passing “ yes ” or “ no ” in the “X-Accel-Buffering” response header field. This capability can be disabled using the proxy_ignore_headers directive.

Sets the number and size of the 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.

When buffering of responses from the proxied server is enabled, limits the total size of buffers that can be busy sending a response to the client while the response is not yet fully read. In the meantime, the rest of the buffers can be used for reading the response and, if needed, buffering part of the response to a temporary file. By default, size is limited by the size of two buffers set by the proxy_buffer_size and proxy_buffers directives.

Defines a shared memory zone used for caching. The same zone can be used in several places. Parameter value can contain variables (1.7.9). The off parameter disables caching inherited from the previous configuration level.

This directive appeared in version 1.11.10.

Allows starting a background subrequest to update an expired cache item, while a stale cached response is returned to the client. Note that it is necessary to allow the usage of a stale cached response when it is being updated.

Defines conditions under which the response 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 response will not be taken from the cache:

Can be used along with the proxy_no_cache directive.

This directive appeared in version 1.9.7.

Enables or disables the conversion of the “ HEAD ” method to “ GET ” for caching. When the conversion is disabled, the cache key should be configured to include the $request_method .

Defines a key for caching, for example

By default, the directive’s value is close to the string

This directive appeared in version 1.1.12.

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.

This directive appeared in version 1.7.8.

If the last request passed to the proxied server for populating a new cache element has not completed for the specified time , one more request may be passed to the proxied server.

This directive appeared in version 1.1.12.

Sets a timeout for proxy_cache_lock. When the time expires, the request will be passed to the proxied server, however, the response will not be cached.

This directive appeared in version 1.11.6.

Sets an offset in bytes for byte-range requests. If the range is beyond the offset, the range request will be passed to the proxied server and the response will not be cached.

This directive appeared in version 0.7.59.

If the client request method is listed in this directive then the response will be cached. “ GET ” and “ HEAD ” methods are always added to the list, though it is recommended to specify them explicitly. See also the proxy_no_cache directive.

Sets the number of requests after which the response will be cached.

Sets the path and other parameters of a cache. Cache data are stored in files. The file name in a cache is a result of applying the MD5 function to the cache key. The levels parameter defines hierarchy levels of a cache: from 1 to 3, each level accepts values 1 or 2. For example, in the following configuration

file names in a cache will look like this:

A cached response is first written to a temporary file, and then the file is renamed. Starting from version 0.8.9, temporary files and the cache can be put on different file systems. However, be aware that in this case a file is copied across two file systems instead of the cheap renaming operation. It is thus recommended that for any given location both cache and a directory holding temporary files are put on the same file system. The directory for temporary files is set based on the use_temp_path parameter (1.7.10). If this parameter is omitted or set to the value on , the directory set by the proxy_temp_path directive for the given location will be used. If the value is set to off , temporary files will be put directly in the cache directory.

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. One megabyte zone can store about 8 thousand keys.

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 “cache manager” process monitors the maximum cache size set by the max_size parameter, and the minimum amount of free space set by the min_free (1.19.1) parameter on the file system with cache. When the size is exceeded or there is not enough free space, it removes the least recently used data. The data is removed in iterations configured by manager_files , manager_threshold , and manager_sleep parameters (1.11.5). During one iteration no more than manager_files items are deleted (by default, 100). The duration of one iteration is limited by the manager_threshold parameter (by default, 200 milliseconds). Between iterations, a pause configured by the manager_sleep parameter (by default, 50 milliseconds) is made.

A minute after the start the special “cache loader” process is activated. It loads information about previously cached data stored on file system into a cache zone. The loading is also done in iterations. During one iteration no more than loader_files items are loaded (by default, 100). Besides, the duration of one iteration is limited by the loader_threshold parameter (by default, 200 milliseconds). Between iterations, a pause configured by the loader_sleep parameter (by default, 50 milliseconds) is made.

Additionally, the following parameters are available as part of our commercial subscription:

purger = on | off Instructs whether cache entries that match a wildcard key will be removed from the disk by the cache purger (1.7.12). Setting the parameter to on (default is off ) will activate the “cache purger” process that permanently iterates through all cache entries and deletes the entries that match the wildcard key. purger_files = number Sets the number of items that will be scanned during one iteration (1.7.12). By default, purger_files is set to 10. purger_threshold = number Sets the duration of one iteration (1.7.12). By default, purger_threshold is set to 50 milliseconds. purger_sleep = number Sets a pause between iterations (1.7.12). By default, purger_sleep is set to 50 milliseconds.

This directive appeared in version 1.5.7.

Defines conditions under which the request will be considered a cache purge request. If at least one value of the string parameters is not empty and is not equal to “0” then the cache entry with a corresponding cache key is removed. The result of successful operation is indicated by returning the 204 (No Content) response.

If the cache key of a purge request ends with an asterisk (“ * ”), all cache entries matching the wildcard key will be removed from the cache. 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.

This directive appeared in version 1.5.7.

Enables revalidation of expired cache items using conditional requests with the “If-Modified-Since” and “If-None-Match” header fields.

Determines in which cases a stale cached response can be used during communication with the proxied server. The directive’s parameters match the parameters of the proxy_next_upstream directive.

The error parameter also permits using a stale cached response if a proxied server to process a request cannot be selected.

Additionally, the updating parameter permits using a stale cached response if it is currently being updated. This allows minimizing the number of accesses to proxied servers when updating cached data.

Using a stale cached response can also be enabled directly in the response header for a specified number of seconds after the response became stale (1.11.10). This has lower priority than using the directive parameters.

• The “stale-while-revalidate” extension of the “Cache-Control” header field permits using a stale cached response if it is currently being updated.
• The “stale-if-error” extension of the “Cache-Control” header field permits using a stale cached response in case of an error.

To minimize the number of accesses to proxied servers when populating a new cache element, the proxy_cache_lock directive can be used.

Sets caching time for different response codes. For example, the following directives

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

then only 200, 301, and 302 responses are cached.

In addition, the any parameter can be specified to cache any responses:

Parameters of caching can also be set directly in the response header. This has higher priority than setting of caching time using the directive.

• The “X-Accel-Expires” header field sets caching time of a response in seconds. The zero value disables caching for a response. If the value starts with the @ prefix, it sets an absolute time in seconds since Epoch, up to which the response may be cached.
• If the header does not include the “X-Accel-Expires” field, parameters of caching may be set in the header fields “Expires” or “Cache-Control”.
• If the header includes the “Set-Cookie” field, such a response will not be cached.
• If the header includes the “Vary” field with the special value “ * ”, such a response will not be cached (1.7.7). If the header includes the “Vary” field with another value, such a response will be cached taking into account the corresponding request header fields (1.7.7).

Processing of one or more of these response header fields can be disabled using the proxy_ignore_headers directive.

Defines a timeout for establishing a connection with a proxied server. It should be noted that this timeout cannot usually exceed 75 seconds.

This directive appeared in version 1.1.15.

Sets a text that should be changed in the domain attribute of the “Set-Cookie” header fields of a proxied server response. Suppose a proxied server returned the “Set-Cookie” header field with the attribute “ domain=localhost ”. The directive

will rewrite this attribute to “ domain=example.org ”.

A dot at the beginning of the domain and replacement strings and the domain attribute is ignored. Matching is case-insensitive.

The domain and replacement strings can contain variables:

The directive can also be specified using regular expressions. In this case, domain should start from the “

” symbol. A regular expression can contain named and positional captures, and replacement can reference them:

Several proxy_cookie_domain directives can be specified on the same level:

If several directives can be applied to the cookie, the first matching directive will be chosen.

The off parameter cancels the effect of the proxy_cookie_domain directives inherited from the previous configuration level.

This directive appeared in version 1.19.3.

Sets one or more flags for the cookie. The cookie can contain text, variables, and their combinations. The flag can contain text, variables, and their combinations (1.19.8). The secure , httponly , samesite=strict , samesite=lax , samesite=none parameters add the corresponding flags. The nosecure , nohttponly , nosamesite parameters remove the corresponding flags.

The cookie can also be specified using regular expressions. In this case, cookie should start from the “

Several proxy_cookie_flags directives can be specified on the same configuration level:

If several directives can be applied to the cookie, the first matching directive will be chosen. In the example, the httponly flag is added to the cookie one , for all other cookies the samesite=strict flag is added and the secure flag is deleted.

The off parameter cancels the effect of the proxy_cookie_flags directives inherited from the previous configuration level.

This directive appeared in version 1.1.15.

Sets a text that should be changed in the path attribute of the “Set-Cookie” header fields of a proxied server response. Suppose a proxied server returned the “Set-Cookie” header field with the attribute “ path=/two/some/uri/ ”. The directive

will rewrite this attribute to “ path=/some/uri/ ”.

The path and replacement strings can contain variables:

The directive can also be specified using regular expressions. In this case, path should either start from the “

” symbol for a case-sensitive matching, or from the “

* ” symbols for case-insensitive matching. The regular expression can contain named and positional captures, and replacement can reference them:

Several proxy_cookie_path directives can be specified on the same level:

If several directives can be applied to the cookie, the first matching directive will be chosen.

The off parameter cancels the effect of the proxy_cookie_path directives inherited from the previous configuration level.

This directive appeared in version 1.7.7.

Enables byte-range support for both cached and uncached responses from the proxied server regardless of the “Accept-Ranges” field in these responses.

Sets the bucket size for hash tables used by the proxy_hide_header and proxy_set_header directives. The details of setting up hash tables are provided in a separate document.

Sets the maximum size of hash tables used by the proxy_hide_header and proxy_set_header directives. The details of setting up hash tables are provided in a separate document.

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 permitted, the proxy_pass_header directive can be used.

This directive appeared in version 1.1.4.

Sets the HTTP protocol version for proxying. By default, version 1.0 is used. Version 1.1 is recommended for use with keepalive connections and NTLM authentication.

Determines whether the connection with a proxied server should be closed when a client closes the connection without waiting for a response.

Disables processing of certain 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”, “Set-Cookie” (0.8.44), and “Vary” (1.7.7).

If not disabled, processing of these header fields has the following effect:

• “X-Accel-Expires”, “Expires”, “Cache-Control”, “Set-Cookie”, and “Vary” set the parameters of response caching;
• “X-Accel-Redirect” performs an internal redirect to the specified URI;
• “X-Accel-Limit-Rate” sets the rate limit for transmission of a response to a client;
• “X-Accel-Buffering” enables or disables buffering of a response;
• “X-Accel-Charset” sets the desired charset of a response.

Determines whether proxied responses with codes greater than or equal to 300 should be passed to a client or be intercepted and redirected to nginx for processing with the error_page directive.

This directive appeared in version 1.7.7.

Limits the speed of reading the response from the proxied server. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if nginx simultaneously opens two connections to the proxied server, the overall rate will be twice as much as the specified limit. The limitation works only if buffering of responses from the proxied server is enabled.

When buffering of responses from the proxied server is enabled, and the whole response does not fit into the buffers set by the proxy_buffer_size and proxy_buffers directives, a part of the response can be saved to a temporary file. This directive sets the maximum size of the temporary file. The size of data written to the temporary file at a time is set by the proxy_temp_file_write_size directive.

The zero value disables buffering of responses to temporary files.

Specifies the HTTP method to use in requests forwarded to the proxied server instead of the method from the client request. Parameter value can contain variables (1.11.6).

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 a request to it, or reading the response header; timeout a timeout has occurred while establishing a connection with the server, passing a request to it, or reading the response header; invalid_header a server returned an 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_403 a server returned a response with the code 403; http_404 a server returned a response with the code 404; http_429 a server returned a response with the code 429 (1.11.13); non_idempotent normally, requests with a non-idempotent method ( POST , LOCK , PATCH ) are not passed to the next server if a request has been sent to an upstream server (1.9.13); enabling this option explicitly allows retrying such requests; off disables passing a request to the next server.

One should bear in mind that passing a request to the next server is only possible if nothing has been sent to a client yet. That is, if an error or timeout occurs in the middle of the transferring of a response, fixing this is impossible.

The directive also defines what is considered an unsuccessful attempt of communication with a server. The cases of error , timeout and invalid_header are always considered unsuccessful attempts, even if they are not specified in the directive. The cases of http_500 , http_502 , http_503 , http_504 , and http_429 are considered unsuccessful attempts only if they are specified in the directive. The cases of http_403 and http_404 are never considered unsuccessful attempts.

Passing a request to the next server can be limited by the number of tries and by time.

This directive appeared in version 1.7.5.

Limits the time during which a request can be passed to the next server. The 0 value turns off this limitation.

This directive appeared in version 1.7.5.

Limits the number of possible tries for passing a request to the next server. The 0 value turns off this limitation.

Defines conditions under which the response 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 response will not be saved:

Can be used along with the proxy_cache_bypass directive.

Sets the protocol and address of a proxied server and an optional URI to which a location should be mapped. As a protocol, “ http ” or “ https ” can be specified. The address can be specified as a domain name or IP address, and an optional port:

or as a UNIX-domain socket path specified after the word “ unix ” and enclosed in colons:

If a domain name resolves 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.

Parameter value can contain variables. In this case, if an address is specified as a domain name, the name is searched among the described server groups, and, if not found, is determined using a resolver.

A request URI is passed to the server as follows:

If the proxy_pass directive is specified with a URI, then when a request is passed to the server, the part of a normalized request URI matching the location is replaced by a URI specified in the directive:

In some cases, the part of a request URI to be replaced cannot be determined:

When location is specified using a regular expression, and also inside named locations.

In these cases, proxy_pass should be specified without a URI.

In this case, the URI specified in the directive is ignored and the full changed request URI is passed to the server.

WebSocket proxying requires special configuration and is supported since version 1.3.13.

Permits passing otherwise disabled header fields from a proxied server to a client.

Indicates whether the original request body is passed to the proxied server.

Indicates whether the header fields of the original request are passed to the proxied server.

Defines a timeout for reading a response from the proxied server. The timeout is set only between two successive read operations, not for the transmission of the whole response. If the proxied server does not transmit anything within this time, the connection is closed.

Sets the text that should be changed in the “Location” and “Refresh” header fields of a proxied server response. Suppose a proxied server returned the header field “ Location: http://localhost:8000/two/some/uri/ ”. The directive

will rewrite this string to “ Location: http://frontend/one/some/uri/ ”.

A server name may be omitted in the replacement string:

then the primary server’s name and port, if different from 80, will be inserted.

The default replacement specified by the default parameter uses the parameters of the location and proxy_pass directives. Hence, the two configurations below are equivalent:

The default parameter is not permitted if proxy_pass is specified using variables.

A replacement string can contain variables:

A redirect can also contain (1.1.11) variables:

The directive can be specified (1.1.11) using regular expressions. In this case, redirect should either start with the “

” symbol for a case-sensitive matching, or with the “

* ” symbols for case-insensitive matching. The regular expression can contain named and positional captures, and replacement can reference them:

Several proxy_redirect directives can be specified on the same level:

If several directives can be applied to the header fields of a proxied server response, the first matching directive will be chosen.

The off parameter cancels the effect of the proxy_redirect directives inherited from the previous configuration level.

Using this directive, it is also possible to add host names to relative redirects issued by a proxied server:

This directive appeared in version 1.7.11.

Enables or disables buffering of a client request body.

When buffering is enabled, the entire request body is read from the client before sending the request to a proxied server.

When buffering is disabled, the request body is sent to the proxied server immediately as it is received. In this case, the request cannot be passed to the next server if nginx already started sending the request body.

When HTTP/1.1 chunked transfer encoding is used to send the original request body, the request body will be buffered regardless of the directive value unless HTTP/1.1 is enabled for proxying.

If the directive is set to a non-zero value, nginx will try to minimize the number of send operations on outgoing connections to a proxied server by using either NOTE_LOWAT flag of the kqueue method, or the SO_SNDLOWAT socket option, with the specified size .

This directive is ignored on Linux, Solaris, and Windows.

Sets a timeout for transmitting a request to the proxied server. The timeout is set only between two successive write operations, not for the transmission of the whole request. If the proxied server does not receive anything within this time, the connection is closed.

Allows redefining the request body passed to the proxied server. The value can contain text, variables, and their combination.

Allows redefining or appending fields to the request header passed to the proxied server. The value can contain text, variables, and their combinations. These directives are inherited from the previous configuration level if and only if there are no proxy_set_header directives defined on the current level. By default, only two fields are redefined:

If caching is enabled, the header fields “If-Modified-Since”, “If-Unmodified-Since”, “If-None-Match”, “If-Match”, “Range”, and “If-Range” from the original request are not passed to the proxied server.

An unchanged “Host” request header field can be passed like this:

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:

In addition, the server name can be passed together with the port of the proxied server:

If the value of a header field is an empty string then this field will not be passed to a proxied server:

This directive appeared in version 1.15.6.

Configures the “TCP keepalive” behavior for outgoing connections to a proxied server. By default, the operating system’s settings are in effect for the socket. If the directive is set to the value “ on ”, the SO_KEEPALIVE socket option is turned on for the socket.

This directive appeared in version 1.7.8.

Specifies a file with the certificate in the PEM format used for authentication to a proxied HTTPS server.

Since version 1.21.0, variables can be used in the file name.

This directive appeared in version 1.7.8.

Specifies a file with the secret key in the PEM format used for authentication to a proxied HTTPS server.

The value engine : name : id can be specified instead of the file (1.7.9), which loads a secret key with a specified id from the OpenSSL engine name .

Since version 1.21.0, variables can be used in the file name.

This directive appeared in version 1.5.6.

Specifies the enabled ciphers for requests to a proxied HTTPS server. The ciphers are specified in the format understood by the OpenSSL library.

The full list can be viewed using the “ openssl ciphers ” command.

This directive appeared in version 1.19.4.

Sets arbitrary OpenSSL configuration commands when establishing a connection with the proxied HTTPS server.

Several proxy_ssl_conf_command directives can be specified on the same level. These directives are inherited from the previous configuration level if and only if there are no proxy_ssl_conf_command directives defined on the current level.

This directive appeared in version 1.7.0.

Specifies a file with revoked certificates (CRL) in the PEM format used to verify the certificate of the proxied HTTPS server.

This directive appeared in version 1.7.0.

Allows overriding the server name used to verify the certificate of the proxied HTTPS server and to be passed through SNI when establishing a connection with the proxied HTTPS server.

By default, the host part of the proxy_pass URL is used.

This directive appeared in version 1.7.8.

Specifies a file with passphrases for secret keys where each passphrase is specified on a separate line. Passphrases are tried in turn when loading the key.

This directive appeared in version 1.5.6.

Enables the specified protocols for requests to a proxied HTTPS server.

This directive appeared in version 1.7.0.

Enables or disables passing of the server name through TLS Server Name Indication extension (SNI, RFC 6066) when establishing a connection with the proxied HTTPS server.

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 disabling session reuse.

This directive appeared in version 1.7.0.

Specifies a file with trusted CA certificates in the PEM format used to verify the certificate of the proxied HTTPS server.

This directive appeared in version 1.7.0.

Enables or disables verification of the proxied HTTPS server certificate.

This directive appeared in version 1.7.0.

Sets the verification depth in the proxied HTTPS server certificates chain.

Enables saving of files to a disk. The on parameter saves files with paths corresponding to the directives alias or root. The off parameter disables saving of files. In addition, the file name can be set explicitly using the string with variables:

The modification time of files is set according to the received “Last-Modified” response header field. The response is first written to a temporary file, and then the file is renamed. Starting from version 0.8.9, temporary files and the persistent store can be put on different file systems. However, be aware that in this case a file is copied across two file systems instead of the cheap renaming operation. It is thus recommended that for any given location both saved files and a directory holding temporary files, set by the proxy_temp_path directive, are put on the same file system.

This directive can be used to create local copies of static unchangeable files, e.g.:

Sets access permissions for newly created files and directories, e.g.:

If any group or all access permissions are specified then user permissions may be omitted:

Limits the size of data written to a temporary file at a time, when buffering of responses from the proxied server to temporary files is enabled. By default, size is limited by two buffers set by the proxy_buffer_size and proxy_buffers directives. The maximum size of a temporary file is set by the proxy_max_temp_file_size directive.

Defines a directory for storing temporary files with data received from proxied servers. Up to three-level subdirectory hierarchy can be used underneath the specified directory. For example, in the following configuration

a temporary file might look like this:

See also the use_temp_path parameter of the proxy_cache_path directive.

Embedded Variables

The ngx_http_proxy_module module supports embedded variables that can be used to compose headers using the proxy_set_header directive:

$proxy_host name and port of a proxied server as specified in the proxy_pass directive; $proxy_port port of a proxied server as specified in the proxy_pass directive, or the protocol’s default port; $proxy_add_x_forwarded_for the “X-Forwarded-For” client request header field with the $remote_addr variable appended to it, separated by a comma. If the “X-Forwarded-For” field is not present in the client request header, the $proxy_add_x_forwarded_for variable is equal to the $remote_addr variable.

Модуль ngx_http_proxy_module позволяет передавать запросы другому серверу.

Пример конфигурации

Директивы

Эта директива появилась в версии 0.8.22.

Задаёт локальный IP-адрес с необязательным портом (1.11.2), который будет использоваться в исходящих соединениях с проксируемым сервером. В значении параметра допустимо использование переменных (1.3.12). Специальное значение off (1.3.12) отменяет действие унаследованной с предыдущего уровня конфигурации директивы proxy_bind , позволяя системе самостоятельно выбирать локальный IP-адрес и порт.

Параметр transparent (1.11.0) позволяет задать нелокальный IP-aдрес, который будет использоваться в исходящих соединениях с проксируемым сервером, например, реальный IP-адрес клиента:

Для работы параметра обычно требуется запустить рабочие процессы nginx с привилегиями суперпользователя. В Linux этого не требуется (1.13.8), так как если указан параметр transparent , то рабочие процессы наследуют capability CAP_NET_RAW из главного процесса. Также необходимо настроить таблицу маршрутизации ядра для перехвата сетевого трафика с проксируемого сервера.

Задаёт размер буфера, в который будет читаться первая часть ответа, получаемого от проксируемого сервера. В этой части ответа находится, как правило, небольшой заголовок ответа. По умолчанию размер одного буфера равен размеру страницы памяти. В зависимости от платформы это или 4K, или 8K, однако его можно сделать меньше.

Разрешает или запрещает использовать буферизацию ответов проксируемого сервера.

Если буферизация включена, то nginx принимает ответ проксируемого сервера как можно быстрее, сохраняя его в буферы, заданные директивами proxy_buffer_size и proxy_buffers. Если ответ не вмещается целиком в память, то его часть может быть записана на диск во временный файл. Запись во временные файлы контролируется директивами proxy_max_temp_file_size и proxy_temp_file_write_size.

Если буферизация выключена, то ответ синхронно передаётся клиенту сразу же по мере его поступления. nginx не пытается считать весь ответ проксируемого сервера. Максимальный размер данных, который nginx может принять от сервера за один раз, задаётся директивой proxy_buffer_size.

Буферизация может быть также включена или выключена путём передачи значения “ yes ” или “ no ” в поле “X-Accel-Buffering” заголовка ответа. Эту возможность можно запретить с помощью директивы proxy_ignore_headers.

Задаёт число и размер буферов для одного соединения, в которые будет читаться ответ, получаемый от проксируемого сервера. По умолчанию размер одного буфера равен размеру страницы. В зависимости от платформы это или 4K, или 8K.

При включённой буферизации ответов проксируемого сервера, ограничивает суммарный размер буферов, которые могут быть заняты для отправки ответа клиенту, пока ответ ещё не прочитан целиком. Оставшиеся буферы тем временем могут использоваться для чтения ответа и, при необходимости, буферизации части ответа во временный файл. По умолчанию размер ограничен величиной двух буферов, заданных директивами proxy_buffer_size и proxy_buffers.

Задаёт зону разделяемой памяти, используемой для кэширования. Одна и та же зона может использоваться в нескольких местах. В значении параметра можно использовать переменные (1.7.9). Параметр off запрещает кэширование, унаследованное с предыдущего уровня конфигурации.

Эта директива появилась в версии 1.11.10.

Позволяет запустить фоновый подзапрос для обновления просроченного элемента кэша, в то время как клиенту возвращается устаревший закэшированный ответ. Использование устаревшего закэшированного ответа в момент его обновления должно быть разрешено.

Задаёт условия, при которых ответ не будет браться из кэша. Если значение хотя бы одного из строковых параметров непустое и не равно “0”, то ответ не берётся из кэша:

Можно использовать совместно с директивой proxy_no_cache.

Эта директива появилась в версии 1.9.7.

Разрешает или запрещает преобразование метода “ HEAD ” в “ GET ” для кэширования. Если преобразование выключено, то необходимо, чтобы ключ кэширования включал в себя $request_method .

Задаёт ключ для кэширования, например,

По умолчанию значение директивы близко к строке

Эта директива появилась в версии 1.1.12.

Если включено, одновременно только одному запросу будет позволено заполнить новый элемент кэша, идентифицируемый согласно директиве proxy_cache_key, передав запрос на проксируемый сервер. Остальные запросы этого же элемента будут либо ожидать появления ответа в кэше, либо освобождения блокировки этого элемента, в течение времени, заданного директивой proxy_cache_lock_timeout.

Эта директива появилась в версии 1.7.8.

Если последний запрос, переданный на проксируемый сервер для заполнения нового элемента кэша, не завершился за указанное время , на проксируемый сервер может быть передан ещё один запрос.

Эта директива появилась в версии 1.1.12.

Задаёт таймаут для proxy_cache_lock. По истечении указанного времени запрос будет передан на проксируемый сервер, однако ответ не будет закэширован.

Эта директива появилась в версии 1.11.6.

Задаёт смещение в байтах для запросов с указанием диапазона запрашиваемых байт (byte-range requests). Если диапазон находится за указанным смещением, range-запрос будет передан на проксируемый сервер и ответ не будет закэширован.

Эта директива появилась в версии 0.7.59.

Если метод запроса клиента указан в этой директиве, то ответ будет закэширован. Методы “ GET ” и “ HEAD ” всегда добавляются в список, но тем не менее рекомендуется перечислять их явно. См. также директиву proxy_no_cache.

Задаёт число запросов, после которого ответ будет закэширован.

Задаёт путь и другие параметры кэша. Данные кэша хранятся в файлах. Именем файла в кэше является результат функции MD5 от ключа кэширования. Параметр levels задаёт уровни иерархии кэша: можно задать от 1 до 3 уровней, на каждом уровне допускаются значения 1 или 2. Например, при использовании

имена файлов в кэше будут такого вида:

Кэшируемый ответ сначала записывается во временный файл, а потом этот файл переименовывается. Начиная с версии 0.8.9 временные файлы и кэш могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешёвой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если кэш будет находиться на той же файловой системе, что и каталог с временными файлами. Какой из каталогов будет использоваться для временных файлов определяется параметром use_temp_path (1.7.10). Если параметр не задан или установлен в значение “ on ”, то будет использоваться каталог, задаваемый директивой proxy_temp_path для данного location. Если параметр установлен в значение “ off ”, то временные файлы будут располагаться непосредственно в каталоге кэша.

Кроме того, все активные ключи и информация о данных хранятся в зоне разделяемой памяти, имя и размер которой задаются параметром keys_zone . Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч ключей.

Если к данным кэша не обращаются в течение времени, заданного параметром inactive , то данные удаляются, независимо от их свежести. По умолчанию inactive равен 10 минутам.

Специальный процесс “cache manager” следит за максимальным размером кэша, заданным параметром max_size , а также за минимальным объёмом свободного места на файловой системе с кэшем, заданным параметром min_free (1.19.1). При превышении максимального размера кэша или недостаточном объёме свободного места процесс удаляет наименее востребованные данные. Удаление данных происходит итерациями, настраиваемыми параметрами (1.11.5) manager_files , manager_threshold и manager_sleep . За одну итерацию загружается не более manager_files элементов (по умолчанию 100). Время работы одной итерации ограничено параметром manager_threshold (по умолчанию 200 миллисекунд). Между итерациями делается пауза на время, заданное параметром manager_sleep (по умолчанию 50 миллисекунд).

Через минуту после старта активируется специальный процесс “cache loader”, который загружает в зону кэша информацию о ранее закэшированных данных, хранящихся на файловой системе. Загрузка также происходит итерациями. За одну итерацию загружается не более loader_files элементов (по умолчанию 100). Кроме того, время работы одной итерации ограничено параметром loader_threshold (по умолчанию 200 миллисекунд). Между итерациями делается пауза на время, заданное параметром loader_sleep (по умолчанию 50 миллисекунд).

Кроме того, следующие параметры доступны как часть коммерческой подписки:

purger = on | off Указывает, будут ли записи в кэше, соответствующие маске, удалены с диска при помощи процесса “cache purger” (1.7.12). Установка параметра в значение on (по умолчанию off ) активирует процесс “cache purger”, который проходит по всем записям в кэше и удаляет записи, соответствующие этой маске. purger_files = число Задаёт число элементов, которые будут сканироваться за одну итерацию (1.7.12). По умолчанию purger_files равен 10. purger_threshold = время Задаёт продолжительность одной итерации (1.7.12). По умолчанию purger_threshold равен 50 миллисекундам. purger_sleep = время Задаёт паузу между итерациями (1.7.12). По умолчанию purger_sleep равен 50 миллисекундам.

Эта директива появилась в версии 1.5.7.

Задаёт условия, при которых запрос будет считаться запросом на очистку кэша. Если значение хотя бы одного из строковых параметров непустое и не равно “0”, то запись в кэше с соответствующим ключом кэширования удаляется. В результате успешной операции возвращается ответ с кодом 204 (No Content).

Если ключ кэширования запроса на очистку заканчивается звёздочкой (“ * ”), то все записи в кэше, соответствующие этой маске, будут удалены из кэша. Тем не менее, эти записи будут оставаться на диске или до момента удаления из-за отсутствия обращения к данным, или до обработки их процессом “cache purger” (1.7.12), или до попытки клиента получить к ним доступ.

Эта директива появилась в версии 1.5.7.

Разрешает ревалидацию просроченных элементов кэша при помощи условных запросов с полями заголовка “If-Modified-Since” и “If-None-Match”.

Определяет, в каких случаях можно использовать устаревший закэшированный ответ. Параметры директивы совпадают с параметрами директивы proxy_next_upstream.

Параметр error также позволяет использовать устаревший закэшированный ответ при невозможности выбора проксированного сервера для обработки запроса.

Кроме того, дополнительный параметр updating разрешает использовать устаревший закэшированный ответ, если на данный момент он уже обновляется. Это позволяет минимизировать число обращений к проксированным серверам при обновлении закэшированных данных.

Использование устаревшего закэшированного ответа может также быть разрешено непосредственно в заголовке ответа на определённое количество секунд после того, как ответ устарел (1.11.10). Такой способ менее приоритетен, чем задание параметров директивы.

• Расширение “stale-while-revalidate” поля заголовка “Cache-Control” разрешает использовать устаревший закэшированный ответ, если на данный момент он уже обновляется.
• Расширение “stale-if-error” поля заголовка “Cache-Control” разрешает использовать устаревший закэшированный ответ в случае ошибки.

Чтобы минимизировать число обращений к проксированным серверам при заполнении нового элемента кэша, можно воспользоваться директивой proxy_cache_lock.

Задаёт время кэширования для разных кодов ответа. Например, директивы

задают время кэширования 10 минут для ответов с кодами 200 и 302 и 1 минуту для ответов с кодом 404.

Если указано только время кэширования,

то кэшируются только ответы 200, 301 и 302.

Кроме того, можно кэшировать любые ответы с помощью параметра any :

Параметры кэширования могут также быть заданы непосредственно в заголовке ответа. Такой способ приоритетнее, чем задание времени кэширования с помощью директивы.

• Поле заголовка “X-Accel-Expires” задаёт время кэширования ответа в секундах. Значение 0 запрещает кэшировать ответ. Если значение начинается с префикса @ , оно задаёт абсолютное время в секундах с начала эпохи, до которого ответ может быть закэширован.
• Если в заголовке нет поля “X-Accel-Expires”, параметры кэширования определяются по полям заголовка “Expires” или “Cache-Control”.
• Ответ, в заголовке которого есть поле “Set-Cookie”, не будет кэшироваться.
• Ответ, в заголовке которого есть поле “Vary” со специальным значением “ * ”, не будет кэшироваться (1.7.7). Ответ, в заголовке которого есть поле “Vary” с другим значением, будет закэширован с учётом соответствующих полей заголовка запроса (1.7.7).

Обработка одного или более из этих полей заголовка может быть отключена при помощи директивы proxy_ignore_headers.

Задаёт таймаут для установления соединения с проксированным сервером. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.

Эта директива появилась в версии 1.1.15.

Задаёт текст, который нужно изменить в атрибуте domain полей “Set-Cookie” заголовка ответа проксируемого сервера. Предположим, проксируемый сервер вернул поле заголовка “Set-Cookie” с атрибутом “ domain=localhost ”. Директива

перепишет данный атрибут в виде “ domain=example.org ”.

Точка в начале строк домен и замена , а равно как и в атрибуте domain игнорируется. Регистр значения не имеет.

В строках домен и замена можно использовать переменные:

Директиву также можно задать при помощи регулярных выражений. При этом домен должен начинаться с символа “

”. Регулярное выражение может содержать именованные и позиционные выделения, а замена ссылаться на них:

На одном уровне может быть указано несколько директив proxy_cookie_domain :

Если к куке могут быть применены несколько директив, будет выбрана первая из них.

Параметр off отменяет действие унаследованных с предыдущего уровня конфигурации директив proxy_cookie_domain .

Эта директива появилась в версии 1.19.3.

Задаёт один или несколько флагов для куки. В качестве куки можно использовать текст, переменные и их комбинации. В качестве флага можно использовать текст, переменные и их комбинации (1.19.8). Параметры secure , httponly , samesite=strict , samesite=lax , samesite=none добавляют соответствующие флаги. Параметры nosecure , nohttponly , nosamesite удаляют соответствующие флаги.

Куки также можно задать при помощи регулярных выражений. При этом кука должна начинаться с символа “

На одном уровне конфигурации может быть указано несколько директив proxy_cookie_flags :

Если к куке могут быть применены несколько директив, будет выбрана первая из них. В данном примере флаг httponly добавляется к куке one , для остальных кук добавляется флаг samesite=strict и удаляется флаг secure .

Параметр off отменяет действие всех директив proxy_cookie_flags на данном уровне.

Эта директива появилась в версии 1.1.15.

Задаёт текст, который нужно изменить в атрибуте path полей “Set-Cookie” заголовка ответа проксируемого сервера. Предположим, проксируемый сервер вернул поле заголовка “Set-Cookie” с атрибутом “ path=/two/some/uri/ ”. Директива

перепишет данный атрибут в виде “ path=/some/uri/ ”.

В строках путь и замена можно использовать переменные:

Директиву также можно задать при помощи регулярных выражений. При этом путь должен начинаться либо с символа “

”, если при сравнении следует учитывать регистр символов, либо с символов “

* ”, если регистр символов учитывать не нужно. Регулярное выражение может содержать именованные и позиционные выделения, а замена ссылаться на них:

На одном уровне может быть указано несколько директив proxy_cookie_path :

Если к куке могут быть применены несколько директив, будет выбрана первая из них.

Параметр off отменяет действие унаследованных с предыдущего уровня конфигурации директив proxy_cookie_path .

Эта директива появилась в версии 1.7.7.

Включает поддержку диапазонов запрашиваемых байт (byte-range) для кэшированных и некэшированных ответов проксируемого сервера вне зависимости от наличия поля “Accept-Ranges” в заголовках этих ответов.

Задаёт размер корзины для хэш-таблиц, используемых директивами proxy_hide_header и proxy_set_header. Подробнее настройка хэш-таблиц обсуждается в отдельном документе.

Задаёт максимальный размер хэш-таблиц, используемых директивами proxy_hide_header и proxy_set_header. Подробнее настройка хэш-таблиц обсуждается в отдельном документе.

По умолчанию nginx не передаёт клиенту поля заголовка “Date”, “Server”, “X-Pad” и “X-Accel-. ” из ответа проксированного сервера. Директива proxy_hide_header задаёт дополнительные поля, которые не будут передаваться. Если же передачу полей нужно разрешить, можно воспользоваться директивой proxy_pass_header.

Эта директива появилась в версии 1.1.4.

Задаёт версию протокола HTTP для проксирования. По умолчанию используется версия 1.0. Для работы постоянных соединений и проверки подлинности NTLM рекомендуется версия 1.1.

Определяет, закрывать ли соединение с проксированным сервером в случае, если клиент закрыл соединение, не дождавшись ответа.

Запрещает обработку некоторых полей заголовка из ответа проксированного сервера. В директиве можно указать поля “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” задаёт желаемую кодировку ответа.

Определяет, передавать ли клиенту проксированные ответы с кодом больше либо равным 300, или же перехватывать их и перенаправлять на обработку nginx’у с помощью директивы error_page.

Эта директива появилась в версии 1.7.7.

Ограничивает скорость чтения ответа от проксируемого сервера. Скорость задаётся в байтах в секунду. Значение 0 отключает ограничение скорости. Ограничение устанавливается на запрос, поэтому, если nginx одновременно откроет два соединения к проксируемому серверу, суммарная скорость будет вдвое выше заданного ограничения. Ограничение работает только в случае, если включена буферизация ответов проксируемого сервера.

Если включена буферизация ответов проксируемого сервера, и ответ не вмещается целиком в буферы, заданные директивами proxy_buffer_size и proxy_buffers, часть ответа может быть записана во временный файл. Эта директива задаёт максимальный размер временного файла. Размер данных, сбрасываемых во временный файл за один раз, задаётся директивой proxy_temp_file_write_size.

Значение 0 отключает возможность буферизации ответов во временные файлы.

Задаёт HTTP- метод , который будет использоваться в передаваемых на проксируемый сервер запросах вместо метода из клиентского запроса. В значении параметра допустимо использование переменных (1.11.6).

Определяет, в каких случаях запрос будет передан следующему серверу:

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 никогда не считаются неудачными попытками.

Передача запроса следующему серверу может быть ограничена по количеству попыток и по времени.

Эта директива появилась в версии 1.7.5.

Ограничивает время, в течение которого возможна передача запроса следующему серверу. Значение 0 отключает это ограничение.

Эта директива появилась в версии 1.7.5.

Ограничивает число допустимых попыток для передачи запроса следующему серверу. Значение 0 отключает это ограничение.

Задаёт условия, при которых ответ не будет сохраняться в кэш. Если значение хотя бы одного из строковых параметров непустое и не равно “0”, то ответ не будет сохранён:

Можно использовать совместно с директивой proxy_cache_bypass.

Задаёт протокол и адрес проксируемого сервера, а также необязательный URI, на который должен отображаться location. В качестве протокола можно указать “ http ” или “ https ”. Адрес может быть указан в виде доменного имени или IP-адреса, и необязательного порта:

или в виде пути UNIX-сокета, который указывается после слова “ unix ” и заключается в двоеточия:

Если доменному имени соответствует несколько адресов, то все они будут использоваться по очереди (round-robin). Кроме того, в качестве адреса можно указать группу серверов.

В значении параметра можно использовать переменные. В этом случае, если адрес указан в виде доменного имени, имя ищется среди описанных групп серверов и если не найдено, то определяется с помощью resolver’а.

URI запроса передаётся на сервер так:

Если директива proxy_pass указана с URI, то при передаче запроса серверу часть нормализованного URI запроса, соответствующая location, заменяется на URI, указанный в директиве:

В ряде случаев часть URI запроса, подлежащую замене, выделить невозможно:

Если location задан регулярным выражением, а также в именованных location’ах.

В этих случаях proxy_pass следует указывать без URI.

В этом случае URI, указанный в директиве, игнорируется, и на сервер передаётся изменённый URI запроса целиком.

Проксирование WebSocket требует особой настройки и поддерживается начиная с версии 1.3.13.

Разрешает передавать от проксируемого сервера клиенту запрещённые для передачи поля заголовка.

Позволяет запретить передачу исходного тела запроса на проксируемый сервер.

Позволяет запретить передачу полей заголовка исходного запроса на проксируемый сервер.

Задаёт таймаут при чтении ответа проксированного сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени проксируемый сервер ничего не передаст, соединение закрывается.

Задаёт текст, который нужно изменить в полях заголовка “Location” и “Refresh” в ответе проксируемого сервера. Предположим, проксируемый сервер вернул поле заголовка “ Location: http://localhost:8000/two/some/uri/ ”. Директива

перепишет эту строку в виде “ Location: http://frontend/one/some/uri/ ”.

В заменяемой строке можно не указывать имя сервера:

тогда будут подставлены основное имя сервера и порт, если он отличен от 80.

Стандартная замена, задаваемая параметром default , использует параметры директив location и proxy_pass. Поэтому две нижеприведённые конфигурации одинаковы:

Параметр default недопустим, если в proxy_pass используются переменные.

В строке замена можно использовать переменные:

В строке перенаправление тоже можно использовать (1.1.11) переменные:

Директиву также можно задать (1.1.11) при помощи регулярных выражений. При этом перенаправление должно начинаться либо с символа “

”, если при сравнении следует учитывать регистр символов, либо с символов “

* ”, если регистр символов учитывать не нужно. Регулярное выражение может содержать именованные и позиционные выделения, а замена ссылаться на них:

На одном уровне может быть указано несколько директив proxy_redirect :

Если к полям заголовка в ответе проксируемого сервера могут быть применены несколько директив, будет выбрана первая из них.

Параметр off отменяет действие унаследованных с предыдущего уровня конфигурации директив proxy_redirect .

С помощью этой директивы можно также добавлять имя хоста к относительным перенаправлениям, выдаваемым проксируемым сервером:

Эта директива появилась в версии 1.7.11.

Разрешает или запрещает использовать буферизацию тела запроса клиента.

Если буферизация включена, то тело запроса полностью читается от клиента перед отправкой запроса на проксируемый сервер.

Если буферизация выключена, то тело запроса отправляется на проксируемый сервер сразу же по мере его поступления. В этом случае запрос не может быть передан следующему серверу, если nginx уже начал отправку тела запроса.

Если для отправки тела исходного запроса используется HTTP/1.1 и передача данных частями (chunked transfer encoding), то тело запроса буферизуется независимо от значения директивы, если для проксирования также не включён HTTP/1.1.

При установке директивы в ненулевое значение nginx будет пытаться минимизировать число операций отправки на исходящих соединениях с проксируемым сервером либо при помощи флага NOTE_LOWAT метода kqueue, либо при помощи параметра сокета SO_SNDLOWAT , с указанным размером .

Эта директива игнорируется на Linux, Solaris и Windows.

Задаёт таймаут при передаче запроса проксированному серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени проксируемый сервер не примет новых данных, соединение закрывается.

Позволяет переопределить тело запроса, передаваемое на проксируемый сервер. В качестве значения можно использовать текст, переменные и их комбинации.

Позволяет переопределять или добавлять поля заголовка запроса, передаваемые проксируемому серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы proxy_set_header . По умолчанию переопределяются только два поля:

Если включено кэширование, поля заголовка “If-Modified-Since”, “If-Unmodified-Since”, “If-None-Match”, “If-Match”, “Range” и “If-Range” исходного запроса не передаются на проксируемый сервер.

Неизменённое поле заголовка запроса “Host” можно передать так:

Однако, если это поле отсутствует в заголовке запроса клиента, то ничего передаваться не будет. В этом случае лучше воспользоваться переменной $host — её значение равно имени сервера в поле “Host” заголовка запроса, или же основному имени сервера, если поля нет:

Кроме того, можно передать имя сервера вместе с портом проксируемого сервера:

Если значение поля заголовка — пустая строка, то поле вообще не будет передаваться проксируемому серверу:

Эта директива появилась в версии 1.15.6.

Конфигурирует поведение “TCP keepalive” для исходящих соединений к проксируемому серверу. По умолчанию для сокета действуют настройки операционной системы. Если указано значение “ on ”, то для сокета включается параметр SO_KEEPALIVE .

Эта директива появилась в версии 1.7.8.

Задаёт файл с сертификатом в формате PEM для аутентификации на проксируемом HTTPS-сервере.

Начиная с версии 1.21.0 в имени файла можно использовать переменные.

Эта директива появилась в версии 1.7.8.

Задаёт файл с секретным ключом в формате PEM для аутентификации на проксируемом HTTPS-сервере.

Вместо файла можно указать значение engine : имя : id (1.7.9), которое загружает ключ с указанным id из OpenSSL engine с заданным именем .

Начиная с версии 1.21.0 в имени файла можно использовать переменные.

Эта директива появилась в версии 1.5.6.

Описывает разрешённые шифры для запросов к проксируемому HTTPS-серверу. Шифры задаются в формате, поддерживаемом библиотекой OpenSSL.

Полный список можно посмотреть с помощью команды “ openssl ciphers ”.

Эта директива появилась в версии 1.19.4.

Задаёт произвольные конфигурационные команды OpenSSL при установлении соединения с проксируемым HTTPS-сервером.

На одном уровне может быть указано несколько директив proxy_ssl_conf_command . Директивы наследуются с предыдущего уровня конфигурации при условии, что на данном уровне не описаны свои директивы proxy_ssl_conf_command .

Эта директива появилась в версии 1.7.0.

Указывает файл с отозванными сертификатами (CRL) в формате PEM, используемыми при проверке сертификата проксируемого HTTPS-сервера.

Эта директива появилась в версии 1.7.0.

Позволяет переопределить имя сервера, используемое при проверке сертификата проксируемого HTTPS-сервера, а также для передачи его через SNI при установлении соединения с проксируемым HTTPS-сервером.

По умолчанию используется имя хоста из URL’а, заданного директивой proxy_pass.

Эта директива появилась в версии 1.7.8.

Задаёт файл с паролями от секретных ключей, где каждый пароль указан на отдельной строке. Пароли применяются по очереди в момент загрузки ключа.

Эта директива появилась в версии 1.5.6.

Разрешает указанные протоколы для запросов к проксируемому HTTPS-серверу.

Эта директива появилась в версии 1.7.0.

Разрешает или запрещает передачу имени сервера через расширение Server Name Indication протокола TLS (SNI, RFC 6066) при установлении соединения с проксируемым HTTPS-сервером.

Определяет, использовать ли повторно SSL-сессии при работе с проксированным сервером. Если в логах появляются ошибки “ SSL3_GET_FINISHED:digest check failed ”, то можно попробовать выключить повторное использование сессий.

Эта директива появилась в версии 1.7.0.

Задаёт файл с доверенными сертификатами CA в формате PEM, используемыми при проверке сертификата проксируемого HTTPS-сервера.

Эта директива появилась в версии 1.7.0.

Разрешает или запрещает проверку сертификата проксируемого HTTPS-сервера.

Эта директива появилась в версии 1.7.0.

Устанавливает глубину проверки в цепочке сертификатов проксируемого HTTPS-сервера.

Разрешает сохранение на диск файлов. Параметр on сохраняет файлы в соответствии с путями, указанными в директивах alias или root. Параметр off запрещает сохранение файлов. Кроме того, имя файла можно задать явно с помощью строки с переменными:

Время изменения файлов выставляется согласно полученному полю “Last-Modified” в заголовке ответа. Ответ сначала записывается во временный файл, а потом этот файл переименовывается. Начиная с версии 0.8.9 временный файл и постоянное место хранения ответа могут располагаться на разных файловых системах. Однако нужно учитывать, что в этом случае вместо дешёвой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой proxy_temp_path для данного location.

Директиву можно использовать для создания локальных копий статических неизменяемых файлов, например, так:

Задаёт права доступа для создаваемых файлов и каталогов, например,

Если заданы какие-либо права для group или all , то права для user указывать необязательно:

Ограничивает размер данных, сбрасываемых во временный файл за один раз, при включённой буферизации ответов проксируемого сервера во временные файлы. По умолчанию размер ограничен двумя буферами, заданными директивами proxy_buffer_size и proxy_buffers. Максимальный размер временного файла задаётся директивой proxy_max_temp_file_size.

Задаёт имя каталога для хранения временных файлов с данными, полученными от проксируемых серверов. В каталоге может использоваться иерархия подкаталогов до трёх уровней. Например, при такой конфигурации

временный файл будет следующего вида:

См. также параметр use_temp_path директивы proxy_cache_path.

Встроенные переменные

В модуле ngx_http_proxy_module есть встроенные переменные, которые можно использовать для формирования заголовков с помощью директивы proxy_set_header:

$proxy_host имя и порт проксируемого сервера, как указано в директиве proxy_pass; $proxy_port порт проксируемого сервера, как указано в директиве proxy_pass, или стандартный порт протокола; $proxy_add_x_forwarded_for поле заголовка запроса клиента “X-Forwarded-For” и добавленная к нему через запятую переменная $remote_addr . Если же поля “X-Forwarded-For” в заголовке запроса клиента нет, то переменная $proxy_add_x_forwarded_for равна переменной $remote_addr .

Основы работы с Nginx: проксирование, балансировка нагрузки, буферизация и кэширование

В этом руководстве мы обсудим возможности HTTP-проксирования веб-сервера Nginx, которые позволяют ему передавать запросы на http-серверы бэкэнда для дальнейшей обработки. Nginx часто настраивается как обратный прокси-сервер, который помогает масштабировать инфраструктуру или передавать запросы другим серверам, которые не предназначены для обработки больших клиентских нагрузок.

Вы научитесь масштабировать свою инфраструктуру, используя встроенные функции балансировки нагрузки Nginx. Также вы узнаете, как с помощью буферизации и кеширования улучшить производительность прокси-операций клиентов.

Основы проксирования

Одной из причин использовать проксирование Nginx является возможность масштабирования инфраструктуры. Nginx умеет одновременно управлять несколькими параллельными соединениями. Это делает его идеальным сервером для контакта с клиентами. Сервер может передавать запросы на любое количество бэкэнд-серверов для обработки основного массива трафика, поступающего в вашу инфраструктуру. Это также обеспечивает гибкость при добавлении или замене бэкэнд-серверов по мере необходимости.

Вторя причина настроить HTTP-проксирование – это наличие в инфраструктуре серверов приложений, которые не могут обрабатывать клиентские запросы напрямую в производственных средах. Многие фреймворки предоставляют встроенные веб-серверы, но большинство из них не столь надежны, как высокопроизводительные серверы, такие как Nginx. Использование обратного прокси Nginx может улучшить пользовательский опыт и повысить безопасность.

Проксирование в Nginx осуществляется путем обработки запроса, направленного на сервер Nginx, и передачи его другим серверам для фактической обработки. Результат запроса передается обратно на Nginx, который затем передает информацию клиенту. Другими серверами в этом случае могут быть удаленные компьютеры, локальные серверы или даже другие виртуальные серверы, определенные в настройке Nginx. Серверы, к которым обращается прокси Nginx, называются upstream серверами.

Nginx может проксировать запросы на серверы, которые обмениваются данными с помощью протоколов http(s), FastCGI, SCGI и uwsgi или memcached через отдельные наборы директив для каждого типа проксирования. В этом мануале мы сосредоточимся на протоколе http. Экземпляр Nginx отвечает за передачу запроса и связь с любым компонентом обмена сообщениями в формате, который может понять upstream сервер.

Директива proxy_pass

Самый простой тип проксирования включает в себя передачу запроса на один сервер, который может связываться с помощью http. Этот тип проксирования известен как proxy pass и обрабатывается одноименной директивой proxy_pass.

Директива proxy_pass в основном встречается в контекстах location. Она также поддерживается блоками if в контексте location и limit_except. Когда запрос совпадает с адресом, указанным в proxy_pass, он пересылается по этому URL-адресу.

Рассмотрим такой пример:

# server context
location /match/here <
proxy_pass http://example.com;
>
. . .

В приведенном выше фрагменте конфигурации в конце блока server в определении proxy_pass не указывается URI. Для определений, соответствующих этому шаблону, запрошенный клиентом URI будет передан на upstream сервер без изменений.

Например, когда этот блок обрабатывает запрос /match/here/please, URI запроса будет отправлен на сервер example.com как http://example.com/match/here/please.

Рассмотрим альтернативный сценарий:

# server context
location /match/here <
proxy_pass http://example.com/new/prefix;
>
. . .

В приведенном выше примере прокси-сервер определяется вместе с сегментом URI в конце (/new/prefix). Когда в определении proxy_pass указывается URI, то часть запроса, которая соответствует определению location, заменяется этим URI.

К примеру, запрос /match/here/please будет передаваться на upstream сервер как http://example.com/new/prefix/please. Префикс /match/here заменяется на /new/prefix. Об этом важно помнить.

Иногда такая замена невозможна. В этих случаях URI в конце определения proxy_pass игнорируется, и на upstream сервер передается исходный URI клиента или URI, измененный другими директивами.

Например, при использованием регулярных выражений Nginx не может определить, какая часть URI соответствует выражению, поэтому он отправляет исходный URI-запрос клиента. Или, например, если директива rewrite используется в одном и том же location, она переписывает URI клиента, но он все же обрабатывается в одном блоке. В этом случае будет передан переписанный URI.

Обработка заголовков в Nginx

Чтобы upstream сервер обработал запрос должным образом, одного URI недостаточно. Запрос, поступающий от имени клиента через Nginx, будет выглядеть иначе, чем запрос, поступающий непосредственно от клиента. Большая часть этого – заголовки, которые согласуются с запросом.

Когда Nginx проксирует запрос, он автоматически вносит некоторые поправки в заголовки, полученные от клиента.

• Nginx избавляется ото всех пустых заголовков. Нет смысла передавать пустые значения другому серверу; это только усложнит передачу запроса.
• Все заголовки, которые содержат символы подчеркивания, Nginx по умолчанию рассматривает как недопустимые. Он удалит их из запроса. Если вы хотите, чтобы Nginx интерпретировал их как валидные, вы можете установить в директиве underscores_in_headers значение on, в противном случае такие заголовки никогда не попадут на бэкэнд-сервер.
• Заголовок Host переписывается значением, определяемым переменной $proxy_host. Это может быть IP-адрес или имя и номер порта upstream сервера, как указано в директиве proxy_pass.
• Заголовок Connection заменяется значением close. Этот заголовок используется для передачи информации о конкретном соединении, установленном между двумя сторонами. В этом случае Nginx устанавливает это значение, чтобы указать upstream серверу, что это соединение будет закрыто после ответа на исходный запрос. Не следует ожидать, что это upstream соединение будет постоянным.

Первый вывод, который можно сделать из вышеизложенной информации: если вы не хотите передавать тот или иной заголовок, нужно задать ему значение пустой строки. Заголовки с такими значениями полностью удаляются из переданного запроса.

Также следует убедиться, что в нестандартных заголовках нет подчеркиваний, что если ваше бэкэнд-приложение будет обрабатывать такие заголовки. Если вам нужны заголовки, в которых используется символ подчеркивания, вы можете установить директиве underscores_in_headers значение on (это валидно либо в контексте http, либо в контексте объявления server по умолчанию для комбинации IP-адреса/порта). Если вы этого не сделаете, Nginx пометит эти заголовки как некорректные и просто сбросит их, прежде чем перейти к upstream серверу.

Заголовок Host имеет особое значение в большинстве прокси-сценариев. Как указано выше, по умолчанию этот заголовок получит значение переменной $proxy_host, которая содержит домен или IP-адрес и порт, взятые непосредственно из определения proxy_pass. Это поведение определяется по умолчанию, так как это единственный адрес, на который точно отвечает upstream сервер Nginx.

Заголовок Host часто имеет такие значения:

• $proxy_host: устанавливает в Host домен или IP-адрес и порт из определения proxy_pass. Это значение по умолчанию надежно с точки зрения Nginx, но оно не всегда подходит для правильной обработки запроса.
• $http_host: устанавливает в Host заголовок Host из клиентского запроса. Заголовки, отправленные клиентом, всегда доступны Nginx в качестве переменных. Переменные начинаются с префикса $http_, после которого устанавливается имя заголовка в нижнем регистре, а все тире заменяются нижним подчеркиванием. Помните, что переменная $http_host не сработает, если в запросе клиента нет валидного заголовка Host.
• $host: эта переменная может принимать в качестве значений имя хоста из запроса, заголовок host из клиентского запроса или имя сервера соответствующего запроса.

В большинстве случаев нужно установить в заголовке Host переменную $host. Это наиболее гибкий вариант, который обычно обеспечивает точное заполнение заголовка.

Настройка или сброс заголовков

Чтобы настроить или установить заголовки для прокси-соединений, можно использовать директиву proxy_set_header. Например, чтобы изменить заголовок Host и добавить дополнительные заголовки, нужно использовать что-то вроде этого:

# server context
location /match/here <
proxy_set_header HOST $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://example.com/new/prefix;
>
. . .

Здесь заголовок Host получит значение переменной $host, в которой должна содержаться информация о запрошенном исходном хосте. Заголовок X-Forwarded-Proto предоставляет прокси-серверу информацию о схеме исходного запроса клиента (будь то http или https-запрос).

X-Real-IP указывает IP-адрес клиента, чтобы прокси-сервер мог правильно принимать решения или вести лог на основе этой информации. Заголовок X-Forwarded-For – это список, содержащий IP-адрес каждого сервера, по которому проходил запрос. В приведенном выше примере устанавливается значение переменной $proxy_add_x_forwarded_for. Эта переменная принимает значение исходного X-Forwarded-Forheader, извлеченного из клиента, и добавляет IP-адрес сервера Nginx в конец.

Конечно, директиву proxy_set_header стоит переместить в контекст server или http, чтоб иметь возможность ссылаться на нее:

# server context
proxy_set_header HOST $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
location /match/here <
proxy_pass http://example.com/new/prefix;
>
location /different/match <
proxy_pass http://example.com;
>

Раздел Upstream для балансировки нагрузки проксируемых соединений

В предыдущих примерах вы увидели, как сделать настроить простое HTTP-прокси соединение на одном сервере. Nginx позволяет легко масштабировать эту конфигурацию, указав целые пулы бэкэнд-серверов, на которые можно передавать запросы.

Это можно сделать с помощью директивы upstream, которая позволяет определить пул серверов. Эта конфигурация предполагает, что любой из перечисленных серверов способен обрабатывать запрос клиента. Это позволяет масштабировать инфраструктуру практически без усилий. Директива upstream должна быть установлена в контексте http конфигурации Nginx.

Рассмотрим простой пример:

# http context
upstream backend_hosts <
server host1.example.com;
server host2.example.com;
server host3.example.com;
>
server <
listen 80;
server_name example.com;
location /proxy-me <
proxy_pass http:// backend_hosts ;
>
>

В приведенном выше примере был создан контекст upstream под названием backend_hosts. После определения это имя будет доступно в proxy pass как обычный домен. Как вы можете видеть, в блоке server все запросы, сделанные в example.com/proxy-me/…, передаются в пул, который вы определили выше. В этом пуле хост выбирается с помощью настраиваемого алгоритма. По умолчанию это простой процесс round-robin (каждый запрос будет поочередно маршрутизироваться на другой хост).

Изменение алгоритма балансировки в контексте upstream

Настроить алгоритм в пуле upstream можно с помощью таких флагов и директив:

• round robin: Алгоритм балансировки нагрузки по умолчанию, который используется, если не указано других директив. Каждый запрос будет последовательно передаваться серверам, определенным в контексте upstream.
• least_conn: Указывает, что новые соединения всегда должны быть привязаны к бэкэнду, который имеет наименьшее количество активных соединений. Это может быть особенно полезно в ситуациях, когда соединения с бэкэндом могут сохраняться в течение некоторого времени.
• ip_hash: Этот алгоритм балансировки распределяет запросы между серверами на основе IP-адреса клиента. Первые три октета используются в качестве ключа, на основе которого выбирается сервер для обработки запроса. В результате клиенты, как правило, обслуживаются одним и тем же сервером при каждом подключении, что обеспечивает согласованность сеансов.
• hash: Этот алгоритм балансировки в основном используется с прокси-сервером memcached. Серверы делятся на группы на основе значения произвольно предоставленного хэш-ключа. Ключ может быть текстом, переменной или разными комбинациями. Это единственный метод балансировки, который требует от пользователя предоставить данные (ключ).

При изменении алгоритма блок может выглядеть так:

# http context
upstream backend_hosts <
least_conn;
server host1.example.com;
server host2.example.com;
server host3.example.com;
>
. . .

В приведенном выше примере сервер будет выбран по наименьшему количеству соединений. Можно также добавить директиву ip_hash, чтобы обеспечить «липкость» сессии.

Что касается метода hash, вы должны указать ключ для хэша. Это может быть что угодно:

# http context
upstream backend_hosts <
hash $remote_addr$remote_port consistent;
server host1.example.com;
server host2.example.com;
server host3.example.com;
>
. . .

В приведенном выше примере запросы будут распределяться на основе значений IP-адреса и порта клиента. Также здесь есть опциональный параметр consistent, который реализует алгоритм хэширования ketama consistent. Это означает, что если upstream серверы изменятся, это будет иметь минимальное воздействие на кэш.

Установка веса сервера для балансировки

В объявлениях бэкэнд-серверов по умолчанию все серверы весят одинаково. Это предполагает, что каждый сервер может и должен обрабатывать одинаковый объем нагрузки (с учетом эффектов алгоритмов балансировки). Тем не менее, вы также можете установить пользовательский вес своих серверов:

# http context
upstream backend_hosts <
server host1.example.com weight=3;
server host2.example.com;
server host3.example.com;
>
. . .

Теперь host1.example.com будет получать в три раза больше трафика, чем другие два сервера. Вес каждого сервера по умолчанию равен 1.

Использование буферов для освобождения бэкэнд-серверов

Один из главных вопросов при проксировании – насколько изменится скорость работы при добавлении сервера. Увеличение или уменьшение количества серверов можно значительно смягчить с помощью системы буферизации и кэширования Nginx.

При проксировании на другой сервер на опыт клиента влияет скорость двух разных подключений:

• Подключения клиента к прокси Nginx.
• И подключения прокси-сервера Nginx к серверу.

Nginx имеет возможность корректировать свое поведение на основе того, какое из этих соединений вы хотите оптимизировать.

Без буферов данные с прокси-сервера сразу же отправляются к клиенту. Если клиентские соединения быстрые, буферизацию можно отключить, чтобы клиент как можно скорее мог получить данные. При использовании буферов прокси-сервер Nginx будет временно хранить ответ бэкэнда, а затем передавать эти данные клиенту. Если клиент работает медленно, это позволит серверу Nginx быстрее закрыть соединение с бэкэндом. Затем он сможет обрабатывать передачу данных клиенту любым возможным способом.

Nginx по умолчанию использует буферизацию, так как скорость соединения, как правило, меняется в зависимости от клиента. Буферизация настраивается с помощью следующих директив. Их можно установить в контексте http, server или location. Важно иметь в виду, что директивы size касаются каждого запроса, поэтому они могут повлиять на производительность серверов при поступлении множества клиентских запросов.

• proxy_buffering: эта директива определяет, включена ли буферизация для этого контекста и его дочерних контекстов. По умолчанию имеет значение on.
• proxy_buffers: Эта директива контролирует количество (первый аргумент) и размер (второй аргумент) буферов. По умолчанию используется 8 буферов, размер которых равен одной странице памяти (либо 4k, либо 8k). Увеличение количества буферов позволяет буферизовать дополнительную информацию.
• proxy_buffer_size: Исходная часть ответа от бэкэнд-сервера, которая содержит заголовки, буферизуется отдельно от остальных данных. Эта директива устанавливает размер буфера для этой части ответа. По умолчанию она будет того же размера, что и proxy_buffers, но поскольку здесь хранятся только заголовки, ее можно уменьшить.
• proxy_busy_buffers_size: Эта директива устанавливает максимальное количество занятых буферов. Хотя клиент может считывать данные только из одного буфера за раз, буферы помещаются в очередь для отправки фрагментов данных клиенту. Эта директива управляет размером буферного пространства, которое может находиться в этом состоянии.
• proxy_max_temp_file_size: Это максимальный размер временного файла каждого запроса на диске. Они создаются, если ответ бэкэнда слишком велик и не помещается в буфер.
• proxy_temp_file_write_size: Это количество данных, которые Nginx будет записывать во временный файл за один раз, если ответ прокси-сервера слишком велик и не помещается в буфер.
• proxy_temp_path: Это путь к области на диске, где Nginx должен хранить временные файлы, когда ответ upstream сервера не помещается в буфер.

Как вы можете видеть, Nginx предоставляет довольно много разных директив для настройки поведения буферизации. В большинстве случаев вам не придется использовать их, но некоторые из этих значений могут пригодиться. Возможно, наиболее полезными являются proxy_buffers и proxy_buffer_size.

В этом примере увеличивается количество доступных буферов для обработки запросов и уменьшается размер буфера для хранения заголовков:

# server context
proxy_buffering on;
proxy_buffer_size 1k;
proxy_buffers 24 4k;
proxy_busy_buffers_size 8k;
proxy_max_temp_file_size 2048m;
proxy_temp_file_write_size 32k;
location / <
proxy_pass http://example.com;
>

Если у вас есть быстрые клиенты, которым нужно быстро отправить данные, можно полностью отключить буферизацию. Nginx будет по-прежнему использовать буферы, если сервер upstream быстрее, чем клиент, но он попытается немедленно передать данные клиенту. Если клиент работает медленно, это может привести к тому, что upstream соединение останется открытым до тех пор, пока клиент не сможет получить данные. Когда буферизация выключена, будет использоваться только буфер, определенный директивой proxy_buffer_size:

# server context
proxy_buffering off;
proxy_buffer_size 4k;
location / <
proxy_pass http://example.com;
>

Высокая доступность (опционально)

Проксирование Nginx можно сделать более надежным, добавив избыточный набор балансировщиков нагрузки, чтобы создать инфраструктуру высокой доступности.

Настройка высокой доступности – это инфраструктура без единой точки отказа, и балансировщики нагрузки являются частью этой конфигурации. Имея несколько балансировщиков нагрузки, вы сможете предотвратить простои, если один из балансировщиков станет недоступен.

Кэширование и снижение времени ответа

Буферизация помогает освободить сервер бэкэнда для обработки большего количества запросов, но Nginx также может кэшировать контент с бэкэнд-серверов, устраняя необходимость подключения к upstream серверу для обработки запросов.

Настойка прокси-кэша

Для настройки кэширования ответов бэкэнд серверов можно использовать директиву proxy_cache_path, которая определяет пространство для хранения кэша. Её следует задавать в контексте http.

В приведенном ниже примере показано, как использовать эту и некоторые другие директивы для настройки системы кэширования.

# http context
proxy_cache_path /var/lib/nginx/cache levels=1:2 keys_zone=backcache:8m max_size=50m;
proxy_cache_key «$scheme$request_method$host$request_uri$is_args$args»;
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;

Директива proxy_cache_path определяет каталог в файловой системе, где нужно хранить кэш. В этом примере это каталог /var/lib/nginx/cache. Если этот каталог не существует, вы можете создать его и определить права доступа к нему:

sudo mkdir -p /var/lib/nginx/cache
sudo chown www-data /var/lib/nginx/cache
sudo chmod 700 /var/lib/nginx/cache

Параметр levels= указывает, как будет организован кэш. Nginx создаст ключ кеша путем хэширования значения ключа (он настраивается ниже). В результате будет создан каталог, имя которого состоит из одного символа (это будет последний символ хешированного значения), и подкаталог с именем из двух символов (следующие два символа в конце хэша). Это помогает Nginx быстро найти соответствующие значения.

Параметр keys_zone= определяет имя зоны кеша (backcache). Здесь также указывается, сколько метаданных можно хранить. В этом случае сервер будет хранить 8 МБ ключей. На 1 мегабайте Nginx может хранить около 8000 записей. Параметр max_size устанавливает максимальный размер кэшированных данных.

Директива proxy_cache_key устанавливает ключ, который будет использоваться для хранения кешированных значений. Этот же ключ используется для проверки того, можно ли запросить данные из кеша. Здесь используется комбинация схемы (http или https), метода HTTP-запроса, а также запрошенного хоста и URI.

Директива proxy_cache_valid может быть указана несколько раз. Она позволяет определить, как долго должны храниться значения в зависимости от кода состояния. В данном примере удачные и переадресованные ответы хранятся в течение 10 минут, а ответы 404 удаляются каждую минуту.

Теперь зона кэширования настроена, но пока что Nginx не знает, когда именно применять кеширование.

Эта информация указывается в контексте location для бекэнд серверов:

# server context
location /proxy-me <
proxy_cache backcache;
proxy_cache_bypass $http_cache_control;
add_header X-Proxy-Cache $upstream_cache_status;
proxy_pass http://backend;
>
. . .

Используя директиву proxy_cache, можно указать, что для этого контекста следует использовать зону кэширования backcache. Nginx проверит запись перед тем, как перейти к серверу.

Директива proxy_chache_bypass принимает значение переменной $http_cache_control. Эта переменная сообщает, запросил ли клиент свежий, не кэшированный ответ. При использовании этой директивы Nginx сможет корректно обрабатывать запросы такого типа. Никаких дальнейших настроек не для этого не требуется.

Мы также добавили дополнительный заголовок X-Proxy-Cache. Этот заголовок принимает значение переменной $upstream_cache_status. Это позволяет увидеть, обработан ли запрос из кэша, этих данных не было в кэше или клиент запросил новый ответ. Это особенно полезно для отладки.

Рекомендации по кэшированию результатов

Кеширование увеличивает скорость прокси-сервера. Но не стоит забывать о нескольких нюансах.

Во-первых, любая личная информация пользователей ни в коем случае не должна кэшироваться, чтобы пользователи не получали в ответ данные о других пользователях. Эта проблема не касается статичных сайтов.

Если на сайте есть динамические элементы, им следует уделить внимание. Решение этой проблемы зависит от бекэнд-сервера. Для личных данных используется заголовок Cache-Control со значением no-cache, no-store или private.

• no-cache: ответ не будет отправлен, пока сервер не проверит данные на бекэнд-сервере. Это значение используется с динамическими данными. Хэшированные метаданные заголовка Etag проверяются при каждом запросе. Если бекэнд вернет теже значения, то данные отправляются из кэша клиенту.
• no-store: данные не должны храниться в кэше ни при каких обстоятельствах. Это самый безопасный подход при работе с личными данными.
• private: данные не должны кэшироваться в общем кэше. То есть, к примеру, браузер пользователя может кешировать данные, а прокси-сервер нет.
• public: данные можно кэшировать везде.

Есть связанный с этим поведением заголовок max-age, который определяет срок хранения кэша в секундах.

Его значение зависит от чувствительности данных. При разумном использовании этого заголовка конфиденциальные данные будут в безопасности, а часто изменяемый контент будет своевременно обновляться.

Если вы используете nginx и на бэкэнде, добавьте директиву expires, которая определяет значение max-age заголовка Cache-Control:

location / <
expires 60m;
>
location /check-me <
expires -1;
>

Первый блок поддерживает кэш в течение часа. Второй блок присваивает заголовку Cache-Control значение no-cache. Для внесения других изменений примените директиву add_header:

location /private <
expires -1;
add_header Cache-Control «no-store»;
>

Using NGINX Proxypass to Set Up a Reverse Proxy Server

Get a new level of security for your M365 data with immutable backup copies on any object storage. Try the new Veeam Backup for M365 v7.

Table of Contents

Are you planning to create a web application that is only accessible in a private network? Why not use NGINX ProxyPass (proxy_pass) to set up NGINX as a reverse proxy server?

The proxy_pass directive in the ngx_http_proxy_module of NGINX lets you configure NGINX to expose your web application to the world while keeping privacy control. And in this tutorial, you’ll learn about different configurations to define your application’s privacy and increased performance.

Read on and keep your web application secure with NGINX ProxyPass!

Prerequisites

This tutorial will be a hands-on demonstration. If you’d like to follow along, be sure you have the following:

• A Linux server – This tutorial uses Ubuntu 20.04 LTS.

NGINX and Docker are installed and running on your Linux machine.

• A web application running on 127.0.0.1:8000.

What is an NGINX ProxyPass or Reverse Proxy Server?

Before diving deep into NGINX proxy_pass, take a look at what is a reverse proxy server first. Reverse Proxy servers provide an additional layer of security for web applications.

In addition, reverse proxy servers are used for load-balancing, providing a single face for a server application that spans across different servers.

A reverse proxy server is a kind of server that listens to client requests and forward or relays the requests to the relevant web application. At the same time, it responds to the client with the web application’s response.

Configuring NGINX Server as a Reverse Proxy Server

By default, NGINX works as a static content web server, so you’ll configure NGINX as a reverse proxy server by editing NGINX’s configuration files. Depending on your Linux server’s operating system and its distribution, NGINX’s configuration files can be found at one of the places below:

• /etc/nginx
• /usr/local/nginx/conf
• /usr/local/etc/nginx

But since this tutorial uses Ubuntu, you’ll work on the configuration file located at the /etc/nginx directory:

1. Run the following commands to change your working directory (cd) to the /etc/nginx directory, and list all files and directories (ls) inside the working directory.

Below, you can see the nginx.conf file, which is the base file for NGINX configurations.

Listing files inside the /etc/nginx directory

2. Next, run the below rm command, which doesn’t provide output but deletes the sites-available/default file.

3. Create a new file called sites-available/default file with your preferred text editor.

4. Now, add the configuration below to the sites-available/default file, save the changes and close the editor. The following server block (defined using the server directive) contains the entire configuration for a virtual host.

The directives below control the configuration:

• listen — This directive specifies which port a particular server block should listen to for requests.

• access_log and error_log — These directives specify the path for a server block to write access and error logs.

– This directive specifies the proxied server’s address. The configuration below tells NGINX to pass every request to the proxied application on http://127.0.0.1:8000.

Note that the NGINX server can serve more than one application with server blocks.

5. Run the following command to test (-t) your NGINX configuration.

Testing NGINX configuration

6. Next, run the below systemctl command to restart the NGINX service so that new configurations can take effect.

If there’s an error in the configuration, the NGINX service will not restart. Instead, you’ll see instructions on how to find the logs. On ubuntu, you can see logs running the journalctl -xe command.

7. Finally, navigate to your web server’s domain name or IP address to access the application through NGINX reverse proxy server shown below.

Accessing the web application through NGINX reverse proxy server

Passing Headers to Handle Proxied Requests

Apart from proxy_pass, NGINX offers many other directives to handle requests to your server blocks. One of these directives is proxy_set_header, which lets you pass/rewrite headers to handle proxied requests.

This tutorial can’t cover all headers, but you’ll go through some of the most common headers (Host, X-Forwarded-For, and X-Real-IP).

1. Add the following statement above the proxy_pass in your server block under location to pass the Host header in your sites-available/default file. The Host header is sent by HTTP clients/browsers with the application domain name they are trying to access.

By default, NGINX rewrites the Host header to the proxied server’s address ($host) before passing the Host header to the proxied server. The $host variable is set by NGINX, which holds the value of the original request’s Host header or server block’s server_name value.

When the proxied application receives the request, the Host header is set to http://127.0.0.1:8000. Essentially NGINX sets the Host header to your proxy server’s domain name/IP address. This behavior lets your application know it’s being accessed by a designated address rather than from 127.0.0.1.

2. Next, add the statement below to the sites-available/default file as you did in step one.

Your application uses the X-Forwarded-For header to identify the client’s IP address trying to access the application. This header identifies proxy servers used for the request to reach your application.

Below, the $proxy_add_x_forwarded_for variable holds the value of the request’s X-Forwarded-For header with the client’s IP address.

3. Add the last statement below to your sites-available/default file.

Web applications use the X-Real-IP header set to the $remote_addr variable to hold the IP address of the HTTP client accessing the server.

After applying the common configurations used for a reverse proxy server with the previous steps, you’ll get the complete configuration below.

4. Now, run the systemctl command below, which doesn’t provide output but restarts the NGINX service.

5. Finally, try accessing your web application in your browser with the new configuration. If all goes well, you’ll see the output below.

Verifying the web application is accessible with different configuration

Sending Redirect Response

Imagine your application sends a redirect response using the Location header that looks like this, Location: <http://127.0.0.1/user/edit/3. You can see that the 127.0.0.1 address is not descriptive about what’s being accessed. So can you fix it? Yes!

Add either of the following proxy_redirect directives inside the location block in the sites-available/default file. This directive rewrites the Location or Refresh header sent by the proxied application to the actual URL being used to access your application.

Hiding and Permitting Headers

NGINX, by default, hides some headers sent to the client by proxied applications. But by using the proxy_hide_header directive, you can tell NGINX to hide more headers.

Add the directive below to the location block in the sites-available/default file to automatically hide the headers from the response sent to the HTTP client.

Hiding headers help secure sensitive information of the app and the app headers from being misused by malicious attackers.

Or, perhaps you want some header permitted sent to the client that is otherwise hidden. If so, you can use the proxy_pass_header directive like the one below.

Increasing Performance with NGINX Load Balancing

Load balancing is a powerful configuration in your server. The upstream directive in NGINX helps your application balance its load to increase the application performance. At the same time, the upstream directive makes your application scalable.

To configure your NGINX server for load balancing:

1. Create a new file inside the NGINX configuration folder (/etc/nginx/conf.d/) with your text editor, and name the file as load-balancer.conf.

2. Next, add the configuration below to the load-balancer.conf file, save the changes and close the file.

You can see that the upstream directive defines either a web server cluster for load balancing or an app server cluster for routing/load balancing.

3. Run the below rm command, which doesn’t provide output, but removes the default symbolic link (symlink) from the sites-enabled directory.

4. Lastly, restart the NGINX service so new configurations can take effect.

If you get an error in the configuration, open the load-balancer.conf file and double-check if you wrote the configuration correctly.

Verifying the web application works with load balancing

Conclusion

Throughout this tutorial, you’ve learned why and where reverse proxy servers are used with NGINX ProxyPass. You’ve touched on using a couple of directives and headers to handle requests and controlling your web application’s privacy.

Load balancing and hiding headers help your web application’s performance and security. But wouldn’t it be great to add another layer of security? Why not activate NGINX to redirect HTTP to HTTPS traffic?

Hate ads? Want to support the writer? Get many of our tutorials packaged as an ATA Guidebook.

More from ATA Learning & Partners

Recommended Resources!

Recommended Resources for Training, Information Security, Automation, and more!

Get Paid to Write!

ATA Learning is always seeking instructors of all experience levels. Regardless if you’re a junior admin or system architect, you have something to share. Why not write on a platform with an existing audience and share your knowledge with the world?

ATA Learning Guidebooks

ATA Learning is known for its high-quality written tutorials in the form of blog posts. Support ATA Learning with ATA Guidebook PDF eBooks available offline and with no ads!