[ { "table": "
Syntax:accept_mutex on | off;
Default:
accept_mutex off;
Context:events
", "doc": "

If accept_mutex is enabled, worker processes will accept new connections by turn. Otherwise, all worker processes will be notified about new connections, and if volume of new connections is low, some of the worker processes may just waste system resources.

There is no need to enable accept_mutex on systems that support the EPOLLEXCLUSIVE flag (1.11.3) or when using reuseport.
Prior to version 1.11.3, the default value was on.
", "module": "Core functionality", "link": "ngx_core_module.html#accept_mutex", "name": "accept_mutex" }, { "table": "
Syntax:accept_mutex_delay time;
Default:
accept_mutex_delay 500ms;
Context:events
", "doc": "

If accept_mutex is enabled, specifies the maximum time during which a worker process will try to restart accepting new connections if another worker process is currently accepting new connections.

", "module": "Core functionality", "link": "ngx_core_module.html#accept_mutex_delay", "name": "accept_mutex_delay" }, { "table": "
Syntax:daemon on | off;
Default:
daemon on;
Context:main
", "doc": "

Determines whether nginx should become a daemon. Mainly used during development.

", "module": "Core functionality", "link": "ngx_core_module.html#daemon", "name": "daemon" }, { "table": "
Syntax:debug_connection address | CIDR | unix:;
Default:—
Context:events
", "doc": "

Enables debugging log for selected client connections. Other connections will use logging level set by the error_log directive. Debugged connections are specified by IPv4 or IPv6 (1.3.0, 1.2.1) address or network. A connection may also be specified using a hostname. For connections using UNIX-domain sockets (1.3.0, 1.2.1), debugging log is enabled by the “unix:” parameter.

\nevents {\n    debug_connection 127.0.0.1;\n    debug_connection localhost;\n    debug_connection 192.0.2.0/24;\n    debug_connection ::1;\n    debug_connection 2001:0db8::/32;\n    debug_connection unix:;\n    ...\n}\n
For this directive to work, nginx needs to be built with --with-debug, see “A debugging log”.
", "module": "Core functionality", "link": "ngx_core_module.html#debug_connection", "name": "debug_connection" }, { "table": "
Syntax:debug_points abort | stop;
Default:—
Context:main
", "doc": "

This directive is used for debugging.

When internal error is detected, e.g. the leak of sockets on restart of working processes, enabling debug_points leads to a core file creation (abort) or to stopping of a process (stop) for further analysis using a system debugger.

", "module": "Core functionality", "link": "ngx_core_module.html#debug_points", "name": "debug_points" }, { "table": "
Syntax:env variable[=value];
Default:
env TZ;
Context:main
", "doc": "

By default, nginx removes all environment variables inherited from its parent process except the TZ variable. This directive allows preserving some of the inherited variables, changing their values, or creating new environment variables. These variables are then:

", "module": "Core functionality", "link": "ngx_core_module.html#env", "name": "env" }, { "table": "
Syntax:error_log file [level];
Default:
error_log logs/error.log error;
Context:main, http, mail, stream, server, location
", "doc": "

Configures logging. Several logs can be specified on the same level (1.5.2). If on the main configuration level writing a log to a file is not explicitly defined, the default file will be used.

The first parameter defines a file that will store the log. The special value stderr selects the standard error file. Logging to syslog can be configured by specifying the “syslog:” prefix. Logging to a cyclic memory buffer can be configured by specifying the “memory:” prefix and buffer size, and is generally used for debugging (1.7.11).

The second parameter determines the level of logging, and can be one of the following: debug, info, notice, warn, error, crit, alert, or emerg. Log levels above are listed in the order of increasing severity. Setting a certain log level will cause all messages of the specified and more severe log levels to be logged. For example, the default level error will cause error, crit, alert, and emerg messages to be logged. If this parameter is omitted then error is used.

For debug logging to work, nginx needs to be built with --with-debug, see “A debugging log”.
The directive can be specified on the stream level starting from version 1.7.11, and on the mail level starting from version 1.9.0.
", "module": "Core functionality", "link": "ngx_core_module.html#error_log", "name": "error_log" }, { "table": "
Syntax:events { ... }
Default:—
Context:main
", "doc": "

Provides the configuration file context in which the directives that affect connection processing are specified.

", "module": "Core functionality", "link": "ngx_core_module.html#events", "name": "events" }, { "table": "
Syntax:include file | mask;
Default:—
Context:any
", "doc": "

Includes another file, or files matching the specified mask, into configuration. Included files should consist of syntactically correct directives and blocks.

Usage example:

\ninclude mime.types;\ninclude vhosts/*.conf;\n
", "module": "Core functionality", "link": "ngx_core_module.html#include", "name": "include" }, { "table": "
Syntax:load_module file;
Default:—
Context:main

This directive appeared in version 1.9.11.

", "doc": "

Loads a dynamic module.

Example:

\nload_module modules/ngx_mail_module.so;\n
", "module": "Core functionality", "link": "ngx_core_module.html#load_module", "name": "load_module" }, { "table": "
Syntax:lock_file file;
Default:
lock_file logs/nginx.lock;
Context:main
", "doc": "

nginx uses the locking mechanism to implement accept_mutex and serialize access to shared memory. On most systems the locks are implemented using atomic operations, and this directive is ignored. On other systems the “lock file” mechanism is used. This directive specifies a prefix for the names of lock files.

", "module": "Core functionality", "link": "ngx_core_module.html#lock_file", "name": "lock_file" }, { "table": "
Syntax:master_process on | off;
Default:
master_process on;
Context:main
", "doc": "

Determines whether worker processes are started. This directive is intended for nginx developers.

", "module": "Core functionality", "link": "ngx_core_module.html#master_process", "name": "master_process" }, { "table": "
Syntax:multi_accept on | off;
Default:
multi_accept off;
Context:events
", "doc": "

If multi_accept is disabled, a worker process will accept one new connection at a time. Otherwise, a worker process will accept all new connections at a time.

The directive is ignored if kqueue connection processing method is used, because it reports the number of new connections waiting to be accepted.
", "module": "Core functionality", "link": "ngx_core_module.html#multi_accept", "name": "multi_accept" }, { "table": "
Syntax:pcre_jit on | off;
Default:
pcre_jit off;
Context:main

This directive appeared in version 1.1.12.

", "doc": "

Enables or disables the use of “just-in-time compilation” (PCRE JIT) for the regular expressions known by the time of configuration parsing.

PCRE JIT can speed up processing of regular expressions significantly.

The JIT is available in PCRE libraries starting from version 8.20 built with the --enable-jit configuration parameter. When the PCRE library is built with nginx (--with-pcre=), the JIT support is enabled via the --with-pcre-jit configuration parameter.
", "module": "Core functionality", "link": "ngx_core_module.html#pcre_jit", "name": "pcre_jit" }, { "table": "
Syntax:pid file;
Default:
pid logs/nginx.pid;
Context:main
", "doc": "

Defines a file that will store the process ID of the main process.

", "module": "Core functionality", "link": "ngx_core_module.html#pid", "name": "pid" }, { "table": "
Syntax:ssl_engine device;
Default:—
Context:main
", "doc": "

Defines the name of the hardware SSL accelerator.

", "module": "Core functionality", "link": "ngx_core_module.html#ssl_engine", "name": "ssl_engine" }, { "table": "
Syntax:thread_pool name threads=number [max_queue=number];
Default:
thread_pool default threads=32 max_queue=65536;
Context:main

This directive appeared in version 1.7.11.

", "doc": "

Defines named thread pools used for multi-threaded reading and sending of files without blocking worker processes.

The threads parameter defines the number of threads in the pool.

In the event that all threads in the pool are busy, a new task will wait in the queue. The max_queue parameter limits the number of tasks allowed to be waiting in the queue. By default, up to 65536 tasks can wait in the queue. When the queue overflows, the task is completed with an error.

", "module": "Core functionality", "link": "ngx_core_module.html#thread_pool", "name": "thread_pool" }, { "table": "
Syntax:timer_resolution interval;
Default:—
Context:main
", "doc": "

Reduces timer resolution in worker processes, thus reducing the number of gettimeofday() system calls made. By default, gettimeofday() is called each time a kernel event is received. With reduced resolution, gettimeofday() is only called once per specified interval.

Example:

\ntimer_resolution 100ms;\n

Internal implementation of the interval depends on the method used:

", "module": "Core functionality", "link": "ngx_core_module.html#timer_resolution", "name": "timer_resolution" }, { "table": "
Syntax:use method;
Default:—
Context:events
", "doc": "

Specifies the connection processing method to use. There is normally no need to specify it explicitly, because nginx will by default use the most efficient method.

", "module": "Core functionality", "link": "ngx_core_module.html#use", "name": "use" }, { "table": "
Syntax:user user [group];
Default:
user nobody nobody;
Context:main
", "doc": "

Defines user and group credentials used by worker processes. If group is omitted, a group whose name equals that of user is used.

", "module": "Core functionality", "link": "ngx_core_module.html#user", "name": "user" }, { "table": "
Syntax:worker_aio_requests number;
Default:
worker_aio_requests 32;
Context:events

This directive appeared in versions 1.1.4 and 1.0.7.

", "doc": "

When using aio with the epoll connection processing method, sets the maximum number of outstanding asynchronous I/O operations for a single worker process.

", "module": "Core functionality", "link": "ngx_core_module.html#worker_aio_requests", "name": "worker_aio_requests" }, { "table": "
Syntax:worker_connections number;
Default:
worker_connections 512;
Context:events
", "doc": "

Sets the maximum number of simultaneous connections that can be opened by a worker process.

It should be kept in mind that this number includes all connections (e.g. connections with proxied servers, among others), not only connections with clients. Another consideration is that the actual number of simultaneous connections cannot exceed the current limit on the maximum number of open files, which can be changed by worker_rlimit_nofile.

", "module": "Core functionality", "link": "ngx_core_module.html#worker_connections", "name": "worker_connections" }, { "table": "
Syntax:worker_cpu_affinity cpumask ...;
worker_cpu_affinity auto [cpumask];
Default:—
Context:main
", "doc": "

Binds worker processes to the sets of CPUs. Each CPU set is represented by a bitmask of allowed CPUs. There should be a separate set defined for each of the worker processes. By default, worker processes are not bound to any specific CPUs.

For example,

\nworker_processes    4;\nworker_cpu_affinity 0001 0010 0100 1000;\n

binds each worker process to a separate CPU, while

\nworker_processes    2;\nworker_cpu_affinity 0101 1010;\n

binds the first worker process to CPU0/CPU2, and the second worker process to CPU1/CPU3. The second example is suitable for hyper-threading.

The special value auto (1.9.10) allows binding worker processes automatically to available CPUs:

\nworker_processes auto;\nworker_cpu_affinity auto;\n

The optional mask parameter can be used to limit the CPUs available for automatic binding:

\nworker_cpu_affinity auto 01010101;\n
The directive is only available on FreeBSD and Linux.
", "module": "Core functionality", "link": "ngx_core_module.html#worker_cpu_affinity", "name": "worker_cpu_affinity" }, { "table": "
Syntax:worker_priority number;
Default:
worker_priority 0;
Context:main
", "doc": "

Defines the scheduling priority for worker processes like it is done by the nice command: a negative number means higher priority. Allowed range normally varies from -20 to 20.

Example:

\nworker_priority -10;\n
", "module": "Core functionality", "link": "ngx_core_module.html#worker_priority", "name": "worker_priority" }, { "table": "
Syntax:worker_processes number | auto;
Default:
worker_processes 1;
Context:main
", "doc": "

Defines the number of worker processes.

The optimal value depends on many factors including (but not limited to) the number of CPU cores, the number of hard disk drives that store data, and load pattern. When one is in doubt, setting it to the number of available CPU cores would be a good start (the value “auto” will try to autodetect it).

The auto parameter is supported starting from versions 1.3.8 and 1.2.5.
", "module": "Core functionality", "link": "ngx_core_module.html#worker_processes", "name": "worker_processes" }, { "table": "
Syntax:worker_rlimit_core size;
Default:—
Context:main
", "doc": "

Changes the limit on the largest size of a core file (RLIMIT_CORE) for worker processes. Used to increase the limit without restarting the main process.

", "module": "Core functionality", "link": "ngx_core_module.html#worker_rlimit_core", "name": "worker_rlimit_core" }, { "table": "
Syntax:worker_rlimit_nofile number;
Default:—
Context:main
", "doc": "

Changes the limit on the maximum number of open files (RLIMIT_NOFILE) for worker processes. Used to increase the limit without restarting the main process.

", "module": "Core functionality", "link": "ngx_core_module.html#worker_rlimit_nofile", "name": "worker_rlimit_nofile" }, { "table": "
Syntax:worker_shutdown_timeout time;
Default:—
Context:main

This directive appeared in version 1.11.11.

", "doc": "

Configures a timeout for a graceful shutdown of worker processes. When the time expires, nginx will try to close all the connections currently open to facilitate shutdown.

", "module": "Core functionality", "link": "ngx_core_module.html#worker_shutdown_timeout", "name": "worker_shutdown_timeout" }, { "table": "
Syntax:working_directory directory;
Default:—
Context:main
", "doc": "

Defines the current working directory for a worker process. It is primarily used when writing a core-file, in which case a worker process should have write permission for the specified directory.

", "module": "Core functionality", "link": "ngx_core_module.html#working_directory", "name": "working_directory" }, { "table": "
Syntax:absolute_redirect on | off;
Default:
absolute_redirect on;
Context:http, server, location

This directive appeared in version 1.11.8.

", "doc": "

If disabled, redirects issued by nginx will be relative.

See also server_name_in_redirect and port_in_redirect directives.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#absolute_redirect", "name": "absolute_redirect" }, { "table": "
Syntax:aio on | off | threads[=pool];
Default:
aio off;
Context:http, server, location

This directive appeared in version 0.8.11.

", "doc": "

Enables or disables the use of asynchronous file I/O (AIO) on FreeBSD and Linux:

\nlocation /video/ {\n    aio            on;\n    output_buffers 1 64k;\n}\n

On FreeBSD, AIO can be used starting from FreeBSD 4.3. Prior to FreeBSD 11.0, AIO can either be linked statically into a kernel:

\noptions VFS_AIO\n

or loaded dynamically as a kernel loadable module:

\nkldload aio\n

On Linux, AIO can be used starting from kernel version 2.6.22. Also, it is necessary to enable directio, or otherwise reading will be blocking:

\nlocation /video/ {\n    aio            on;\n    directio       512;\n    output_buffers 1 128k;\n}\n

On Linux, directio can only be used for reading blocks that are aligned on 512-byte boundaries (or 4K for XFS). File’s unaligned end is read in blocking mode. The same holds true for byte range requests and for FLV requests not from the beginning of a file: reading of unaligned data at the beginning and end of a file will be blocking.

When both AIO and sendfile are enabled on Linux, AIO is used for files that are larger than or equal to the size specified in the directio directive, while sendfile is used for files of smaller sizes or when directio is disabled.

\nlocation /video/ {\n    sendfile       on;\n    aio            on;\n    directio       8m;\n}\n

Finally, files can be read and sent using multi-threading (1.7.11), without blocking a worker process:

\nlocation /video/ {\n    sendfile       on;\n    aio            threads;\n}\n

Read and send file operations are offloaded to threads of the specified pool. If the pool name is omitted, the pool with the name “default” is used. The pool name can also be set with variables:

\naio threads=pool$disk;\n

By default, multi-threading is disabled, it should be enabled with the --with-threads configuration parameter. Currently, multi-threading is compatible only with the epoll, kqueue, and eventport methods. Multi-threaded sending of files is only supported on Linux.

See also the sendfile directive.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#aio", "name": "aio" }, { "table": "
Syntax:aio_write on | off;
Default:
aio_write off;
Context:http, server, location

This directive appeared in version 1.9.13.

", "doc": "

If aio is enabled, specifies whether it is used for writing files. Currently, this only works when using aio threads and is limited to writing temporary files with data received from proxied servers.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#aio_write", "name": "aio_write" }, { "table": "
Syntax:alias path;
Default:—
Context:location
", "doc": "

Defines a replacement for the specified location. For example, with the following configuration

\nlocation /i/ {\n    alias /data/w3/images/;\n}\n

on request of “/i/top.gif”, the file /data/w3/images/top.gif will be sent.

The path value can contain variables, except $document_root and $realpath_root.

If alias is used inside a location defined with a regular expression then such regular expression should contain captures and alias should refer to these captures (0.7.40), for example:

\nlocation ~ ^/users/(.+\\.(?:gif|jpe?g|png))$ {\n    alias /data/w3/images/$1;\n}\n

When location matches the last part of the directive’s value:

\nlocation /images/ {\n    alias /data/w3/images/;\n}\n

it is better to use the root directive instead:

\nlocation /images/ {\n    root /data/w3;\n}\n
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#alias", "name": "alias" }, { "table": "
Syntax:chunked_transfer_encoding on | off;
Default:
chunked_transfer_encoding on;
Context:http, server, location
", "doc": "

Allows disabling chunked transfer encoding in HTTP/1.1. It may come in handy when using a software failing to support chunked encoding despite the standard’s requirement.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#chunked_transfer_encoding", "name": "chunked_transfer_encoding" }, { "table": "
Syntax:client_body_buffer_size size;
Default:
client_body_buffer_size 8k|16k;
Context:http, server, location
", "doc": "

Sets buffer size for reading client request body. In case the request body is larger than the buffer, the whole body or only its part is written to a temporary file. By default, buffer size is equal to two memory pages. This is 8K on x86, other 32-bit platforms, and x86-64. It is usually 16K on other 64-bit platforms.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#client_body_buffer_size", "name": "client_body_buffer_size" }, { "table": "
Syntax:client_body_in_file_only on | clean | off;
Default:
client_body_in_file_only off;
Context:http, server, location
", "doc": "

Determines whether nginx should save the entire client request body into a file. This directive can be used during debugging, or when using the $request_body_file variable, or the $r->request_body_file method of the module ngx_http_perl_module.

When set to the value on, temporary files are not removed after request processing.

The value clean will cause the temporary files left after request processing to be removed.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#client_body_in_file_only", "name": "client_body_in_file_only" }, { "table": "
Syntax:client_body_in_single_buffer on | off;
Default:
client_body_in_single_buffer off;
Context:http, server, location
", "doc": "

Determines whether nginx should save the entire client request body in a single buffer. The directive is recommended when using the $request_body variable, to save the number of copy operations involved.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#client_body_in_single_buffer", "name": "client_body_in_single_buffer" }, { "table": "
Syntax:client_body_temp_path path [level1 [level2 [level3]]];
Default:
client_body_temp_path client_body_temp;
Context:http, server, location
", "doc": "

Defines a directory for storing temporary files holding client request bodies. Up to three-level subdirectory hierarchy can be used under the specified directory. For example, in the following configuration

\nclient_body_temp_path /spool/nginx/client_temp 1 2;\n

a path to a temporary file might look like this:

\n/spool/nginx/client_temp/7/45/00000123457\n
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#client_body_temp_path", "name": "client_body_temp_path" }, { "table": "
Syntax:client_body_timeout time;
Default:
client_body_timeout 60s;
Context:http, server, location
", "doc": "

Defines a timeout for reading client request body. The timeout is set only for a period between two successive read operations, not for the transmission of the whole request body. If a client does not transmit anything within this time, the 408 (Request Time-out) error is returned to the client.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#client_body_timeout", "name": "client_body_timeout" }, { "table": "
Syntax:client_header_buffer_size size;
Default:
client_header_buffer_size 1k;
Context:http, server
", "doc": "

Sets buffer size for reading client request header. For most requests, a buffer of 1K bytes is enough. However, if a request includes long cookies, or comes from a WAP client, it may not fit into 1K. If a request line or a request header field does not fit into this buffer then larger buffers, configured by the large_client_header_buffers directive, are allocated.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#client_header_buffer_size", "name": "client_header_buffer_size" }, { "table": "
Syntax:client_header_timeout time;
Default:
client_header_timeout 60s;
Context:http, server
", "doc": "

Defines a timeout for reading client request header. If a client does not transmit the entire header within this time, the 408 (Request Time-out) error is returned to the client.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#client_header_timeout", "name": "client_header_timeout" }, { "table": "
Syntax:client_max_body_size size;
Default:
client_max_body_size 1m;
Context:http, server, location
", "doc": "

Sets the maximum allowed size of the client request body, specified in the “Content-Length” request header field. If the size in a request exceeds the configured value, the 413 (Request Entity Too Large) error is returned to the client. Please be aware that browsers cannot correctly display this error. Setting size to 0 disables checking of client request body size.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#client_max_body_size", "name": "client_max_body_size" }, { "table": "
Syntax:connection_pool_size size;
Default:
connection_pool_size 256|512;
Context:http, server
", "doc": "

Allows accurate tuning of per-connection memory allocations. This directive has minimal impact on performance and should not generally be used. By default, the size is equal to 256 bytes on 32-bit platforms and 512 bytes on 64-bit platforms.

Prior to version 1.9.8, the default value was 256 on all platforms.
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#connection_pool_size", "name": "connection_pool_size" }, { "table": "
Syntax:default_type mime-type;
Default:
default_type text/plain;
Context:http, server, location
", "doc": "

Defines the default MIME type of a response. Mapping of file name extensions to MIME types can be set with the types directive.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#default_type", "name": "default_type" }, { "table": "
Syntax:directio size | off;
Default:
directio off;
Context:http, server, location

This directive appeared in version 0.7.7.

", "doc": "

Enables the use of the O_DIRECT flag (FreeBSD, Linux), the F_NOCACHE flag (macOS), or the directio() function (Solaris), when reading files that are larger than or equal to the specified size. The directive automatically disables (0.7.15) the use of sendfile for a given request. It can be useful for serving large files:

\ndirectio 4m;\n

or when using aio on Linux.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#directio", "name": "directio" }, { "table": "
Syntax:directio_alignment size;
Default:
directio_alignment 512;
Context:http, server, location

This directive appeared in version 0.8.11.

", "doc": "

Sets the alignment for directio. In most cases, a 512-byte alignment is enough. However, when using XFS under Linux, it needs to be increased to 4K.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#directio_alignment", "name": "directio_alignment" }, { "table": "
Syntax:disable_symlinks off;
disable_symlinks on | if_not_owner [from=part];
Default:
disable_symlinks off;
Context:http, server, location

This directive appeared in version 1.1.15.

", "doc": "

Determines how symbolic links should be treated when opening files:

off
Symbolic links in the pathname are allowed and not checked. This is the default behavior.
on
If any component of the pathname is a symbolic link, access to a file is denied.
if_not_owner
Access to a file is denied if any component of the pathname is a symbolic link, and the link and object that the link points to have different owners.
from=part
When checking symbolic links (parameters on and if_not_owner), all components of the pathname are normally checked. Checking of symbolic links in the initial part of the pathname may be avoided by specifying additionally the from=part parameter. In this case, symbolic links are checked only from the pathname component that follows the specified initial part. If the value is not an initial part of the pathname checked, the whole pathname is checked as if this parameter was not specified at all. If the value matches the whole file name, symbolic links are not checked. The parameter value can contain variables.

Example:

\ndisable_symlinks on from=$document_root;\n

This directive is only available on systems that have the openat() and fstatat() interfaces. Such systems include modern versions of FreeBSD, Linux, and Solaris.

Parameters on and if_not_owner add a processing overhead.

On systems that do not support opening of directories only for search, to use these parameters it is required that worker processes have read permissions for all directories being checked.
The ngx_http_autoindex_module, ngx_http_random_index_module, and ngx_http_dav_module modules currently ignore this directive.
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#disable_symlinks", "name": "disable_symlinks" }, { "table": "
Syntax:error_page code ... [=[response]] uri;
Default:—
Context:http, server, location, if in location
", "doc": "

Defines the URI that will be shown for the specified errors. A uri value can contain variables.

Example:

\nerror_page 404             /404.html;\nerror_page 500 502 503 504 /50x.html;\n

This causes an internal redirect to the specified uri with the client request method changed to “GET” (for all methods other than “GET” and “HEAD”).

Furthermore, it is possible to change the response code to another using the “=response” syntax, for example:

\nerror_page 404 =200 /empty.gif;\n

If an error response is processed by a proxied server or a FastCGI/uwsgi/SCGI/gRPC server, and the server may return different response codes (e.g., 200, 302, 401 or 404), it is possible to respond with the code it returns:

\nerror_page 404 = /404.php;\n

If there is no need to change URI and method during internal redirection it is possible to pass error processing into a named location:

\nlocation / {\n    error_page 404 = @fallback;\n}\n\nlocation @fallback {\n    proxy_pass http://backend;\n}\n
If uri processing leads to an error, the status code of the last occurred error is returned to the client.

It is also possible to use URL redirects for error processing:

\nerror_page 403      http://example.com/forbidden.html;\nerror_page 404 =301 http://example.com/notfound.html;\n

In this case, by default, the response code 302 is returned to the client. It can only be changed to one of the redirect status codes (301, 302, 303, 307, and 308).

The code 307 was not treated as a redirect until versions 1.1.16 and 1.0.13.
The code 308 was not treated as a redirect until version 1.13.0.

These directives are inherited from the previous level if and only if there are no error_page directives defined on the current level.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#error_page", "name": "error_page" }, { "table": "
Syntax:etag on | off;
Default:
etag on;
Context:http, server, location

This directive appeared in version 1.3.3.

", "doc": "

Enables or disables automatic generation of the “ETag” response header field for static resources.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#etag", "name": "etag" }, { "table": "
Syntax:http { ... }
Default:—
Context:main
", "doc": "

Provides the configuration file context in which the HTTP server directives are specified.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#http", "name": "http" }, { "table": "
Syntax:if_modified_since off | exact | before;
Default:
if_modified_since exact;
Context:http, server, location

This directive appeared in version 0.7.24.

", "doc": "

Specifies how to compare modification time of a response with the time in the “If-Modified-Since” request header field:

off
the “If-Modified-Since” request header field is ignored (0.7.34);
exact
exact match;
before
modification time of a response is less than or equal to the time in the “If-Modified-Since” request header field.
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#if_modified_since", "name": "if_modified_since" }, { "table": "
Syntax:ignore_invalid_headers on | off;
Default:
ignore_invalid_headers on;
Context:http, server
", "doc": "

Controls whether header fields with invalid names should be ignored. Valid names are composed of English letters, digits, hyphens, and possibly underscores (as controlled by the underscores_in_headers directive).

If the directive is specified on the server level, its value is only used if a server is a default one. The value specified also applies to all virtual servers listening on the same address and port.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#ignore_invalid_headers", "name": "ignore_invalid_headers" }, { "table": "
Syntax:internal;
Default:—
Context:location
", "doc": "

Specifies that a given location can only be used for internal requests. For external requests, the client error 404 (Not Found) is returned. Internal requests are the following:

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#internal", "name": "internal" }, { "table": "
Syntax:keepalive_disable none | browser ...;
Default:
keepalive_disable msie6;
Context:http, server, location
", "doc": "

Disables keep-alive connections with misbehaving browsers. The browser parameters specify which browsers will be affected. The value msie6 disables keep-alive connections with old versions of MSIE, once a POST request is received. The value safari disables keep-alive connections with Safari and Safari-like browsers on macOS and macOS-like operating systems. The value none enables keep-alive connections with all browsers.

Prior to version 1.1.18, the value safari matched all Safari and Safari-like browsers on all operating systems, and keep-alive connections with them were disabled by default.
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#keepalive_disable", "name": "keepalive_disable" }, { "table": "
Syntax:keepalive_requests number;
Default:
keepalive_requests 100;
Context:http, server, location

This directive appeared in version 0.8.0.

", "doc": "

Sets the maximum number of requests that can be served through one keep-alive connection. After the maximum number of requests are made, the connection is closed.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#keepalive_requests", "name": "keepalive_requests" }, { "table": "
Syntax:keepalive_timeout timeout [header_timeout];
Default:
keepalive_timeout 75s;
Context:http, server, location
", "doc": "

The first parameter sets a timeout during which a keep-alive client connection will stay open on the server side. The zero value disables keep-alive client connections. The optional second parameter sets a value in the “Keep-Alive: timeout=time” response header field. Two parameters may differ.

The “Keep-Alive: timeout=time” header field is recognized by Mozilla and Konqueror. MSIE closes keep-alive connections by itself in about 60 seconds.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#keepalive_timeout", "name": "keepalive_timeout" }, { "table": "
Syntax:large_client_header_buffers number size;
Default:
large_client_header_buffers 4 8k;
Context:http, server
", "doc": "

Sets the maximum number and size of buffers used for reading large client request header. A request line cannot exceed the size of one buffer, or the 414 (Request-URI Too Large) error is returned to the client. A request header field cannot exceed the size of one buffer as well, or the 400 (Bad Request) error is returned to the client. Buffers are allocated only on demand. By default, the buffer size is equal to 8K bytes. If after the end of request processing a connection is transitioned into the keep-alive state, these buffers are released.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#large_client_header_buffers", "name": "large_client_header_buffers" }, { "table": "
Syntax:limit_except method ... { ... }
Default:—
Context:location
", "doc": "

Limits allowed HTTP methods inside a location. The method parameter can be one of the following: GET, HEAD, POST, PUT, DELETE, MKCOL, COPY, MOVE, OPTIONS, PROPFIND, PROPPATCH, LOCK, UNLOCK, or PATCH. Allowing the GET method makes the HEAD method also allowed. Access to other methods can be limited using the ngx_http_access_module, ngx_http_auth_basic_module, and ngx_http_auth_jwt_module (1.13.10) modules directives:

\nlimit_except GET {\n    allow 192.168.1.0/32;\n    deny  all;\n}\n

Please note that this will limit access to all methods except GET and HEAD.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#limit_except", "name": "limit_except" }, { "table": "
Syntax:limit_rate rate;
Default:
limit_rate 0;
Context:http, server, location, if in location
", "doc": "

Limits the rate of response transmission to a client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit.

Rate limit can also be set in the $limit_rate variable. It may be useful in cases where rate should be limited depending on a certain condition:

\nserver {\n\n    if ($slow) {\n        set $limit_rate 4k;\n    }\n\n    ...\n}\n

Rate limit can also be set in the “X-Accel-Limit-Rate” header field of a proxied server response. This capability can be disabled using the proxy_ignore_headers, fastcgi_ignore_headers, uwsgi_ignore_headers, and scgi_ignore_headers directives.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#limit_rate", "name": "limit_rate" }, { "table": "
Syntax:limit_rate_after size;
Default:
limit_rate_after 0;
Context:http, server, location, if in location

This directive appeared in version 0.8.0.

", "doc": "

Sets the initial amount after which the further transmission of a response to a client will be rate limited.

Example:

\nlocation /flv/ {\n    flv;\n    limit_rate_after 500k;\n    limit_rate       50k;\n}\n
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#limit_rate_after", "name": "limit_rate_after" }, { "table": "
Syntax:lingering_close off | on | always;
Default:
lingering_close on;
Context:http, server, location

This directive appeared in versions 1.1.0 and 1.0.6.

", "doc": "

Controls how nginx closes client connections.

The default value “on” instructs nginx to wait for and process additional data from a client before fully closing a connection, but only if heuristics suggests that a client may be sending more data.

The value “always” will cause nginx to unconditionally wait for and process additional client data.

The value “off” tells nginx to never wait for more data and close the connection immediately. This behavior breaks the protocol and should not be used under normal circumstances.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#lingering_close", "name": "lingering_close" }, { "table": "
Syntax:lingering_time time;
Default:
lingering_time 30s;
Context:http, server, location
", "doc": "

When lingering_close is in effect, this directive specifies the maximum time during which nginx will process (read and ignore) additional data coming from a client. After that, the connection will be closed, even if there will be more data.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#lingering_time", "name": "lingering_time" }, { "table": "
Syntax:lingering_timeout time;
Default:
lingering_timeout 5s;
Context:http, server, location
", "doc": "

When lingering_close is in effect, this directive specifies the maximum waiting time for more client data to arrive. If data are not received during this time, the connection is closed. Otherwise, the data are read and ignored, and nginx starts waiting for more data again. The “wait-read-ignore” cycle is repeated, but no longer than specified by the lingering_time directive.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#lingering_timeout", "name": "lingering_timeout" }, { "table": "
Syntax:listen address[:port] [default_server] [ssl] [http2 | spdy] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
listen port [default_server] [ssl] [http2 | spdy] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
listen unix:path [default_server] [ssl] [http2 | spdy] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
Default:
listen *:80 | *:8000;
Context:server
", "doc": "

Sets the address and port for IP, or the path for a UNIX-domain socket on which the server will accept requests. Both address and port, or only address or only port can be specified. An address may also be a hostname, for example:

\nlisten 127.0.0.1:8000;\nlisten 127.0.0.1;\nlisten 8000;\nlisten *:8000;\nlisten localhost:8000;\n

IPv6 addresses (0.7.36) are specified in square brackets:

\nlisten [::]:8000;\nlisten [::1];\n

UNIX-domain sockets (0.8.21) are specified with the “unix:” prefix:

\nlisten unix:/var/run/nginx.sock;\n

If only address is given, the port 80 is used.

If the directive is not present then either *:80 is used if nginx runs with the superuser privileges, or *:8000 otherwise.

The default_server parameter, if present, will cause the server to become the default server for the specified address:port pair. If none of the directives have the default_server parameter then the first server with the address:port pair will be the default server for this pair.

In versions prior to 0.8.21 this parameter is named simply default.

The ssl parameter (0.7.14) allows specifying that all connections accepted on this port should work in SSL mode. This allows for a more compact configuration for the server that handles both HTTP and HTTPS requests.

The http2 parameter (1.9.5) configures the port to accept HTTP/2 connections. Normally, for this to work the ssl parameter should be specified as well, but nginx can also be configured to accept HTTP/2 connections without SSL.

The spdy parameter (1.3.15-1.9.4) allows accepting SPDY connections on this port. Normally, for this to work the ssl parameter should be specified as well, but nginx can also be configured to accept SPDY connections without SSL.

The proxy_protocol parameter (1.5.12) allows specifying that all connections accepted on this port should use the PROXY protocol.

The PROXY protocol version 2 is supported since version 1.13.11.

The listen directive can have several additional parameters specific to socket-related system calls. These parameters can be specified in any listen directive, but only once for a given address:port pair.

In versions prior to 0.8.21, they could only be specified in the listen directive together with the default parameter.
setfib=number
this parameter (0.8.44) sets the associated routing table, FIB (the SO_SETFIB option) for the listening socket. This currently works only on FreeBSD.
fastopen=number
enables “TCP Fast Open” for the listening socket (1.5.8) and limits the maximum length for the queue of connections that have not yet completed the three-way handshake.
Do not enable this feature unless the server can handle receiving the same SYN packet with data more than once.
backlog=number
sets the backlog parameter in the listen() call that limits the maximum length for the queue of pending connections. By default, backlog is set to -1 on FreeBSD, DragonFly BSD, and macOS, and to 511 on other platforms.
rcvbuf=size
sets the receive buffer size (the SO_RCVBUF option) for the listening socket.
sndbuf=size
sets the send buffer size (the SO_SNDBUF option) for the listening socket.
accept_filter=filter
sets the name of accept filter (the SO_ACCEPTFILTER option) for the listening socket that filters incoming connections before passing them to accept(). This works only on FreeBSD and NetBSD 5.0+. Possible values are dataready and httpready.
deferred
instructs to use a deferred accept() (the TCP_DEFER_ACCEPT socket option) on Linux.
bind
instructs to make a separate bind() call for a given address:port pair. This is useful because if there are several listen directives with the same port but different addresses, and one of the listen directives listens on all addresses for the given port (*:port), nginx will bind() only to *:port. It should be noted that the getsockname() system call will be made in this case to determine the address that accepted the connection. If the setfib, backlog, rcvbuf, sndbuf, accept_filter, deferred, ipv6only, or so_keepalive parameters are used then for a given address:port pair a separate bind() call will always be made.
ipv6only=on|off
this parameter (0.7.42) determines (via the IPV6_V6ONLY socket option) whether an IPv6 socket listening on a wildcard address [::] will accept only IPv6 connections or both IPv6 and IPv4 connections. This parameter is turned on by default. It can only be set once on start.
Prior to version 1.3.4, if this parameter was omitted then the operating system’s settings were in effect for the socket.
reuseport
this parameter (1.9.1) instructs to create an individual listening socket for each worker process (using the SO_REUSEPORT socket option), allowing a kernel to distribute incoming connections between worker processes. This currently works only on Linux 3.9+ and DragonFly BSD.
Inappropriate use of this option may have its security implications.
so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]
this parameter (1.1.11) configures the “TCP keepalive” behavior for the listening socket. If this parameter is omitted then the operating system’s settings will be in effect for the socket. If it is set to the value “on”, the SO_KEEPALIVE option is turned on for the socket. If it is set to the value “off”, the SO_KEEPALIVE option is turned off for the socket. Some operating systems support setting of TCP keepalive parameters on a per-socket basis using the TCP_KEEPIDLE, TCP_KEEPINTVL, and TCP_KEEPCNT socket options. On such systems (currently, Linux 2.4+, NetBSD 5+, and FreeBSD 9.0-STABLE), they can be configured using the keepidle, keepintvl, and keepcnt parameters. One or two parameters may be omitted, in which case the system default setting for the corresponding socket option will be in effect. For example,
so_keepalive=30m::10
will set the idle timeout (TCP_KEEPIDLE) to 30 minutes, leave the probe interval (TCP_KEEPINTVL) at its system default, and set the probes count (TCP_KEEPCNT) to 10 probes.

Example:

\nlisten 127.0.0.1 default_server accept_filter=dataready backlog=1024;\n
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#listen", "name": "listen" }, { "table": "
Syntax:location [ = | ~ | ~* | ^~ ] uri { ... }
location @name { ... }
Default:—
Context:server, location
", "doc": "

Sets configuration depending on a request URI.

The matching is performed against a normalized URI, after decoding the text encoded in the “%XX” form, resolving references to relative path components “.” and “..”, and possible compression of two or more adjacent slashes into a single slash.

A location can either be defined by a prefix string, or by a regular expression. Regular expressions are specified with the preceding “~*” modifier (for case-insensitive matching), or the “~” modifier (for case-sensitive matching). To find location matching a given request, nginx first checks locations defined using the prefix strings (prefix locations). Among them, the location with the longest matching prefix is selected and remembered. Then regular expressions are checked, in the order of their appearance in the configuration file. The search of regular expressions terminates on the first match, and the corresponding configuration is used. If no match with a regular expression is found then the configuration of the prefix location remembered earlier is used.

location blocks can be nested, with some exceptions mentioned below.

For case-insensitive operating systems such as macOS and Cygwin, matching with prefix strings ignores a case (0.7.7). However, comparison is limited to one-byte locales.

Regular expressions can contain captures (0.7.40) that can later be used in other directives.

If the longest matching prefix location has the “^~” modifier then regular expressions are not checked.

Also, using the “=” modifier it is possible to define an exact match of URI and location. If an exact match is found, the search terminates. For example, if a “/” request happens frequently, defining “location = /” will speed up the processing of these requests, as search terminates right after the first comparison. Such a location cannot obviously contain nested locations.

In versions from 0.7.1 to 0.8.41, if a request matched the prefix location without the “=” and “^~” modifiers, the search also terminated and regular expressions were not checked.

Let’s illustrate the above by an example:

\nlocation = / {\n    [ configuration A ]\n}\n\nlocation / {\n    [ configuration B ]\n}\n\nlocation /documents/ {\n    [ configuration C ]\n}\n\nlocation ^~ /images/ {\n    [ configuration D ]\n}\n\nlocation ~* \\.(gif|jpg|jpeg)$ {\n    [ configuration E ]\n}\n

The “/” request will match configuration A, the “/index.html” request will match configuration B, the “/documents/document.html” request will match configuration C, the “/images/1.gif” request will match configuration D, and the “/documents/1.jpg” request will match configuration E.

The “@” prefix defines a named location. Such a location is not used for a regular request processing, but instead used for request redirection. They cannot be nested, and cannot contain nested locations.

If a location is defined by a prefix string that ends with the slash character, and requests are processed by one of proxy_pass, fastcgi_pass, uwsgi_pass, scgi_pass, memcached_pass, or grpc_pass, then the special processing is performed. In response to a request with URI equal to this string, but without the trailing slash, a permanent redirect with the code 301 will be returned to the requested URI with the slash appended. If this is not desired, an exact match of the URI and location could be defined like this:

\nlocation /user/ {\n    proxy_pass http://user.example.com;\n}\n\nlocation = /user {\n    proxy_pass http://login.example.com;\n}\n
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#location", "name": "location" }, { "table": "
Syntax:log_not_found on | off;
Default:
log_not_found on;
Context:http, server, location
", "doc": "

Enables or disables logging of errors about not found files into error_log.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#log_not_found", "name": "log_not_found" }, { "table": "
Syntax:log_subrequest on | off;
Default:
log_subrequest off;
Context:http, server, location
", "doc": "

Enables or disables logging of subrequests into access_log.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#log_subrequest", "name": "log_subrequest" }, { "table": "
Syntax:max_ranges number;
Default:—
Context:http, server, location

This directive appeared in version 1.1.2.

", "doc": "

Limits the maximum allowed number of ranges in byte-range requests. Requests that exceed the limit are processed as if there were no byte ranges specified. By default, the number of ranges is not limited. The zero value disables the byte-range support completely.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#max_ranges", "name": "max_ranges" }, { "table": "
Syntax:merge_slashes on | off;
Default:
merge_slashes on;
Context:http, server
", "doc": "

Enables or disables compression of two or more adjacent slashes in a URI into a single slash.

Note that compression is essential for the correct matching of prefix string and regular expression locations. Without it, the “//scripts/one.php” request would not match

\nlocation /scripts/ {\n    ...\n}\n

and might be processed as a static file. So it gets converted to “/scripts/one.php”.

Turning the compression off can become necessary if a URI contains base64-encoded names, since base64 uses the “/” character internally. However, for security considerations, it is better to avoid turning the compression off.

If the directive is specified on the server level, its value is only used if a server is a default one. The value specified also applies to all virtual servers listening on the same address and port.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#merge_slashes", "name": "merge_slashes" }, { "table": "
Syntax:msie_padding on | off;
Default:
msie_padding on;
Context:http, server, location
", "doc": "

Enables or disables adding comments to responses for MSIE clients with status greater than 400 to increase the response size to 512 bytes.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#msie_padding", "name": "msie_padding" }, { "table": "
Syntax:msie_refresh on | off;
Default:
msie_refresh off;
Context:http, server, location
", "doc": "

Enables or disables issuing refreshes instead of redirects for MSIE clients.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#msie_refresh", "name": "msie_refresh" }, { "table": "
Syntax:open_file_cache off;
open_file_cache max=N [inactive=time];
Default:
open_file_cache off;
Context:http, server, location
", "doc": "

Configures a cache that can store:

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#open_file_cache", "name": "open_file_cache" }, { "table": "
Syntax:open_file_cache_errors on | off;
Default:
open_file_cache_errors off;
Context:http, server, location
", "doc": "

Enables or disables caching of file lookup errors by open_file_cache.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#open_file_cache_errors", "name": "open_file_cache_errors" }, { "table": "
Syntax:open_file_cache_min_uses number;
Default:
open_file_cache_min_uses 1;
Context:http, server, location
", "doc": "

Sets the minimum number of file accesses during the period configured by the inactive parameter of the open_file_cache directive, required for a file descriptor to remain open in the cache.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#open_file_cache_min_uses", "name": "open_file_cache_min_uses" }, { "table": "
Syntax:open_file_cache_valid time;
Default:
open_file_cache_valid 60s;
Context:http, server, location
", "doc": "

Sets a time after which open_file_cache elements should be validated.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#open_file_cache_valid", "name": "open_file_cache_valid" }, { "table": "
Syntax:output_buffers number size;
Default:
output_buffers 2 32k;
Context:http, server, location
", "doc": "

Sets the number and size of the buffers used for reading a response from a disk.

Prior to version 1.9.5, the default value was 1 32k.
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#output_buffers", "name": "output_buffers" }, { "table": "
Syntax:port_in_redirect on | off;
Default:
port_in_redirect on;
Context:http, server, location
", "doc": "

Enables or disables specifying the port in absolute redirects issued by nginx.

The use of the primary server name in redirects is controlled by the server_name_in_redirect directive.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#port_in_redirect", "name": "port_in_redirect" }, { "table": "
Syntax:postpone_output size;
Default:
postpone_output 1460;
Context:http, server, location
", "doc": "

If possible, the transmission of client data will be postponed until nginx has at least size bytes of data to send. The zero value disables postponing data transmission.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#postpone_output", "name": "postpone_output" }, { "table": "
Syntax:read_ahead size;
Default:
read_ahead 0;
Context:http, server, location
", "doc": "

Sets the amount of pre-reading for the kernel when working with file.

On Linux, the posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL) system call is used, and so the size parameter is ignored.

On FreeBSD, the fcntl(O_READAHEAD, size) system call, supported since FreeBSD 9.0-CURRENT, is used. FreeBSD 7 has to be patched.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#read_ahead", "name": "read_ahead" }, { "table": "
Syntax:recursive_error_pages on | off;
Default:
recursive_error_pages off;
Context:http, server, location
", "doc": "

Enables or disables doing several redirects using the error_page directive. The number of such redirects is limited.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#recursive_error_pages", "name": "recursive_error_pages" }, { "table": "
Syntax:request_pool_size size;
Default:
request_pool_size 4k;
Context:http, server
", "doc": "

Allows accurate tuning of per-request memory allocations. This directive has minimal impact on performance and should not generally be used.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#request_pool_size", "name": "request_pool_size" }, { "table": "
Syntax:reset_timedout_connection on | off;
Default:
reset_timedout_connection off;
Context:http, server, location
", "doc": "

Enables or disables resetting timed out connections. The reset is performed as follows. Before closing a socket, the SO_LINGER option is set on it with a timeout value of 0. When the socket is closed, TCP RST is sent to the client, and all memory occupied by this socket is released. This helps avoid keeping an already closed socket with filled buffers in a FIN_WAIT1 state for a long time.

It should be noted that timed out keep-alive connections are closed normally.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#reset_timedout_connection", "name": "reset_timedout_connection" }, { "table": "
Syntax:resolver address ... [valid=time] [ipv6=on|off];
Default:—
Context:http, server, location
", "doc": "

Configures name servers used to resolve names of upstream servers into addresses, for example:

\nresolver 127.0.0.1 [::1]:5353;\n

An address can be specified as a domain name or IP address, and an optional port (1.3.1, 1.2.2). If port is not specified, the port 53 is used. Name servers are queried in a round-robin fashion.

Before version 1.1.7, only a single name server could be configured. Specifying name servers using IPv6 addresses is supported starting from versions 1.3.1 and 1.2.2.

By default, nginx will look up both IPv4 and IPv6 addresses while resolving. If looking up of IPv6 addresses is not desired, the ipv6=off parameter can be specified.

Resolving of names into IPv6 addresses is supported starting from version 1.5.8.

By default, nginx caches answers using the TTL value of a response. An optional valid parameter allows overriding it:

\nresolver 127.0.0.1 [::1]:5353 valid=30s;\n
Before version 1.1.9, tuning of caching time was not possible, and nginx always cached answers for the duration of 5 minutes.
To prevent DNS spoofing, it is recommended configuring DNS servers in a properly secured trusted local network.
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#resolver", "name": "resolver" }, { "table": "
Syntax:resolver_timeout time;
Default:
resolver_timeout 30s;
Context:http, server, location
", "doc": "

Sets a timeout for name resolution, for example:

\nresolver_timeout 5s;\n
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#resolver_timeout", "name": "resolver_timeout" }, { "table": "
Syntax:root path;
Default:
root html;
Context:http, server, location, if in location
", "doc": "

Sets the root directory for requests. For example, with the following configuration

\nlocation /i/ {\n    root /data/w3;\n}\n

The /data/w3/i/top.gif file will be sent in response to the “/i/top.gif” request.

The path value can contain variables, except $document_root and $realpath_root.

A path to the file is constructed by merely adding a URI to the value of the root directive. If a URI has to be modified, the alias directive should be used.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#root", "name": "root" }, { "table": "
Syntax:satisfy all | any;
Default:
satisfy all;
Context:http, server, location
", "doc": "

Allows access if all (all) or at least one (any) of the ngx_http_access_module, ngx_http_auth_basic_module, ngx_http_auth_request_module, or ngx_http_auth_jwt_module modules allow access.

Example:

\nlocation / {\n    satisfy any;\n\n    allow 192.168.1.0/32;\n    deny  all;\n\n    auth_basic           "closed site";\n    auth_basic_user_file conf/htpasswd;\n}\n
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#satisfy", "name": "satisfy" }, { "table": "
Syntax:send_lowat size;
Default:
send_lowat 0;
Context:http, server, location
", "doc": "

If the directive is set to a non-zero value, nginx will try to minimize the number of send operations on client sockets by using either NOTE_LOWAT flag of the kqueue method or the SO_SNDLOWAT socket option. In both cases the specified size is used.

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

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#send_lowat", "name": "send_lowat" }, { "table": "
Syntax:send_timeout time;
Default:
send_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#send_timeout", "name": "send_timeout" }, { "table": "
Syntax:sendfile on | off;
Default:
sendfile off;
Context:http, server, location, if in location
", "doc": "

Enables or disables the use of sendfile().

Starting from nginx 0.8.12 and FreeBSD 5.2.1, aio can be used to pre-load data for sendfile():

\nlocation /video/ {\n    sendfile       on;\n    tcp_nopush     on;\n    aio            on;\n}\n

In this configuration, sendfile() is called with the SF_NODISKIO flag which causes it not to block on disk I/O, but, instead, report back that the data are not in memory. nginx then initiates an asynchronous data load by reading one byte. On the first read, the FreeBSD kernel loads the first 128K bytes of a file into memory, although next reads will only load data in 16K chunks. This can be changed using the read_ahead directive.

Before version 1.7.11, pre-loading could be enabled with aio sendfile;.
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#sendfile", "name": "sendfile" }, { "table": "
Syntax:sendfile_max_chunk size;
Default:
sendfile_max_chunk 0;
Context:http, server, location
", "doc": "

When set to a non-zero value, limits the amount of data that can be transferred in a single sendfile() call. Without the limit, one fast connection may seize the worker process entirely.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#sendfile_max_chunk", "name": "sendfile_max_chunk" }, { "table": "
Syntax:server { ... }
Default:—
Context:http
", "doc": "

Sets configuration for a virtual server. There is no clear separation between IP-based (based on the IP address) and name-based (based on the “Host” request header field) virtual servers. Instead, the listen directives describe all addresses and ports that should accept connections for the server, and the server_name directive lists all server names. Example configurations are provided in the “How nginx processes a request” document.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#server", "name": "server" }, { "table": "
Syntax:server_name name ...;
Default:
server_name "";
Context:server
", "doc": "

Sets names of a virtual server, for example:

\nserver {\n    server_name example.com www.example.com;\n}\n

The first name becomes the primary server name.

Server names can include an asterisk (“*”) replacing the first or last part of a name:

\nserver {\n    server_name example.com *.example.com www.example.*;\n}\n

Such names are called wildcard names.

The first two of the names mentioned above can be combined in one:

\nserver {\n    server_name .example.com;\n}\n

It is also possible to use regular expressions in server names, preceding the name with a tilde (“~”):

\nserver {\n    server_name www.example.com ~^www\\d+\\.example\\.com$;\n}\n

Regular expressions can contain captures (0.7.40) that can later be used in other directives:

\nserver {\n    server_name ~^(www\\.)?(.+)$;\n\n    location / {\n        root /sites/$2;\n    }\n}\n\nserver {\n    server_name _;\n\n    location / {\n        root /sites/default;\n    }\n}\n

Named captures in regular expressions create variables (0.8.25) that can later be used in other directives:

\nserver {\n    server_name ~^(www\\.)?(?<domain>.+)$;\n\n    location / {\n        root /sites/$domain;\n    }\n}\n\nserver {\n    server_name _;\n\n    location / {\n        root /sites/default;\n    }\n}\n

If the directive’s parameter is set to “$hostname” (0.9.4), the machine’s hostname is inserted.

It is also possible to specify an empty server name (0.7.11):

\nserver {\n    server_name www.example.com "";\n}\n

It allows this server to process requests without the “Host” header field — instead of the default server — for the given address:port pair. This is the default setting.

Before 0.8.48, the machine’s hostname was used by default.

During searching for a virtual server by name, if the name matches more than one of the specified variants, (e.g. both a wildcard name and regular expression match), the first matching variant will be chosen, in the following order of priority:

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#server_name", "name": "server_name" }, { "table": "
Syntax:server_name_in_redirect on | off;
Default:
server_name_in_redirect off;
Context:http, server, location
", "doc": "

Enables or disables the use of the primary server name, specified by the server_name directive, in absolute redirects issued by nginx. When the use of the primary server name is disabled, the name from the “Host” request header field is used. If this field is not present, the IP address of the server is used.

The use of a port in redirects is controlled by the port_in_redirect directive.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#server_name_in_redirect", "name": "server_name_in_redirect" }, { "table": "
Syntax:server_names_hash_bucket_size size;
Default:
server_names_hash_bucket_size 32|64|128;
Context:http
", "doc": "

Sets the bucket size for the server names hash tables. The default value depends on the size of the processor’s cache line. The details of setting up hash tables are provided in a separate document.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#server_names_hash_bucket_size", "name": "server_names_hash_bucket_size" }, { "table": "
Syntax:server_names_hash_max_size size;
Default:
server_names_hash_max_size 512;
Context:http
", "doc": "

Sets the maximum size of the server names hash tables. The details of setting up hash tables are provided in a separate document.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#server_names_hash_max_size", "name": "server_names_hash_max_size" }, { "table": "
Syntax:server_tokens on | off | build | string;
Default:
server_tokens on;
Context:http, server, location
", "doc": "

Enables or disables emitting nginx version on error pages and in the “Server” response header field.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#server_tokens", "name": "server_tokens" }, { "table": "
Syntax:subrequest_output_buffer_size size;
Default:
subrequest_output_buffer_size 4k|8k;
Context:http, server, location

This directive appeared in version 1.13.10.

", "doc": "

Sets the size of the buffer used for storing the response body of a subrequest. 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.

The directive is applicable only for subrequests with response bodies saved into memory. For example, such subrequests are created by SSI.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#subrequest_output_buffer_size", "name": "subrequest_output_buffer_size" }, { "table": "
Syntax:tcp_nodelay on | off;
Default:
tcp_nodelay on;
Context:http, server, location
", "doc": "

Enables or disables the use of the TCP_NODELAY option. The option is enabled when a connection is transitioned into the keep-alive state. Additionally, it is enabled on SSL connections, for unbuffered proxying, and for WebSocket proxying.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#tcp_nodelay", "name": "tcp_nodelay" }, { "table": "
Syntax:tcp_nopush on | off;
Default:
tcp_nopush off;
Context:http, server, location
", "doc": "

Enables or disables the use of the TCP_NOPUSH socket option on FreeBSD or the TCP_CORK socket option on Linux. The options are enabled only when sendfile is used. Enabling the option allows

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#tcp_nopush", "name": "tcp_nopush" }, { "table": "
Syntax:try_files file ... uri;
try_files file ... =code;
Default:—
Context:server, location
", "doc": "

Checks the existence of files in the specified order and uses the first found file for request processing; the processing is performed in the current context. The path to a file is constructed from the file parameter according to the root and alias directives. It is possible to check directory’s existence by specifying a slash at the end of a name, e.g. “$uri/”. If none of the files were found, an internal redirect to the uri specified in the last parameter is made. For example:

\nlocation /images/ {\n    try_files $uri /images/default.gif;\n}\n\nlocation = /images/default.gif {\n    expires 30s;\n}\n

The last parameter can also point to a named location, as shown in examples below. Starting from version 0.7.51, the last parameter can also be a code:

\nlocation / {\n    try_files $uri $uri/index.html $uri.html =404;\n}\n

Example in proxying Mongrel:

\nlocation / {\n    try_files /system/maintenance.html\n              $uri $uri/index.html $uri.html\n              @mongrel;\n}\n\nlocation @mongrel {\n    proxy_pass http://mongrel;\n}\n

Example for Drupal/FastCGI:

\nlocation / {\n    try_files $uri $uri/ @drupal;\n}\n\nlocation ~ \\.php$ {\n    try_files $uri @drupal;\n\n    fastcgi_pass ...;\n\n    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;\n    fastcgi_param SCRIPT_NAME     $fastcgi_script_name;\n    fastcgi_param QUERY_STRING    $args;\n\n    ... other fastcgi_param's\n}\n\nlocation @drupal {\n    fastcgi_pass ...;\n\n    fastcgi_param SCRIPT_FILENAME /path/to/index.php;\n    fastcgi_param SCRIPT_NAME     /index.php;\n    fastcgi_param QUERY_STRING    q=$uri&$args;\n\n    ... other fastcgi_param's\n}\n

In the following example,

\nlocation / {\n    try_files $uri $uri/ @drupal;\n}\n

the try_files directive is equivalent to

\nlocation / {\n    error_page 404 = @drupal;\n    log_not_found off;\n}\n

And here,

\nlocation ~ \\.php$ {\n    try_files $uri @drupal;\n\n    fastcgi_pass ...;\n\n    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;\n\n    ...\n}\n

try_files checks the existence of the PHP file before passing the request to the FastCGI server.

Example for Wordpress and Joomla:

\nlocation / {\n    try_files $uri $uri/ @wordpress;\n}\n\nlocation ~ \\.php$ {\n    try_files $uri @wordpress;\n\n    fastcgi_pass ...;\n\n    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;\n    ... other fastcgi_param's\n}\n\nlocation @wordpress {\n    fastcgi_pass ...;\n\n    fastcgi_param SCRIPT_FILENAME /path/to/index.php;\n    ... other fastcgi_param's\n}\n
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#try_files", "name": "try_files" }, { "table": "
Syntax:types { ... }
Default:
types {\n    text/html  html;\n    image/gif  gif;\n    image/jpeg jpg;\n}
Context:http, server, location
", "doc": "

Maps file name extensions to MIME types of responses. Extensions are case-insensitive. Several extensions can be mapped to one type, for example:

\ntypes {\n    application/octet-stream bin exe dll;\n    application/octet-stream deb;\n    application/octet-stream dmg;\n}\n

A sufficiently full mapping table is distributed with nginx in the conf/mime.types file.

To make a particular location emit the “application/octet-stream” MIME type for all requests, the following configuration can be used:

\nlocation /download/ {\n    types        { }\n    default_type application/octet-stream;\n}\n
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#types", "name": "types" }, { "table": "
Syntax:types_hash_bucket_size size;
Default:
types_hash_bucket_size 64;
Context:http, server, location
", "doc": "

Sets the bucket size for the types hash tables. The details of setting up hash tables are provided in a separate document.

Prior to version 1.5.13, the default value depended on the size of the processor’s cache line.
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#types_hash_bucket_size", "name": "types_hash_bucket_size" }, { "table": "
Syntax:types_hash_max_size size;
Default:
types_hash_max_size 1024;
Context:http, server, location
", "doc": "

Sets the maximum size of the types hash tables. The details of setting up hash tables are provided in a separate document.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#types_hash_max_size", "name": "types_hash_max_size" }, { "table": "
Syntax:underscores_in_headers on | off;
Default:
underscores_in_headers off;
Context:http, server
", "doc": "

Enables or disables the use of underscores in client request header fields. When the use of underscores is disabled, request header fields whose names contain underscores are marked as invalid and become subject to the ignore_invalid_headers directive.

If the directive is specified on the server level, its value is only used if a server is a default one. The value specified also applies to all virtual servers listening on the same address and port.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#underscores_in_headers", "name": "underscores_in_headers" }, { "table": "
Syntax:variables_hash_bucket_size size;
Default:
variables_hash_bucket_size 64;
Context:http
", "doc": "

Sets the bucket size for the variables hash table. The details of setting up hash tables are provided in a separate document.

", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#variables_hash_bucket_size", "name": "variables_hash_bucket_size" }, { "table": "
Syntax:variables_hash_max_size size;
Default:
variables_hash_max_size 1024;
Context:http
", "doc": "

Sets the maximum size of the variables hash table. The details of setting up hash tables are provided in a separate document.

Prior to version 1.5.13, the default value was 512.
", "module": "ngx_http_core_module", "link": "http/ngx_http_core_module.html#variables_hash_max_size", "name": "variables_hash_max_size" }, { "table": "
Syntax:allow address | CIDR | unix: | all;
Default:—
Context:http, server, location, limit_except
", "doc": "

Allows access for the specified network or address. If the special value unix: is specified (1.5.1), allows access for all UNIX-domain sockets.

", "module": "ngx_http_access_module", "link": "http/ngx_http_access_module.html#allow", "name": "allow" }, { "table": "
Syntax:deny address | CIDR | unix: | all;
Default:—
Context:http, server, location, limit_except
", "doc": "

Denies access for the specified network or address. If the special value unix: is specified (1.5.1), denies access for all UNIX-domain sockets.

", "module": "ngx_http_access_module", "link": "http/ngx_http_access_module.html#deny", "name": "deny" }, { "table": "
Syntax:add_before_body uri;
Default:—
Context:http, server, location
", "doc": "

Adds the text returned as a result of processing a given subrequest before the response body. An empty string ("") as a parameter cancels addition inherited from the previous configuration level.

", "module": "ngx_http_addition_module", "link": "http/ngx_http_addition_module.html#add_before_body", "name": "add_before_body" }, { "table": "
Syntax:add_after_body uri;
Default:—
Context:http, server, location
", "doc": "

Adds the text returned as a result of processing a given subrequest after the response body. An empty string ("") as a parameter cancels addition inherited from the previous configuration level.

", "module": "ngx_http_addition_module", "link": "http/ngx_http_addition_module.html#add_after_body", "name": "add_after_body" }, { "table": "
Syntax:addition_types mime-type ...;
Default:
addition_types text/html;
Context:http, server, location

This directive appeared in version 0.7.9.

", "doc": "

Allows adding text in responses with the specified MIME types, in addition to “text/html”. The special value “*” matches any MIME type (0.8.29).

", "module": "ngx_http_addition_module", "link": "http/ngx_http_addition_module.html#addition_types", "name": "addition_types" }, { "table": "
Syntax:api [write=on|off];
Default:—
Context:location
", "doc": "

Turns on the REST API interface in the surrounding location. Access to this location should be limited.

The write parameter determines whether the API is read-only or read-write. By default, the API is read-only.

", "module": "ngx_http_api_module", "link": "http/ngx_http_api_module.html#api", "name": "api" }, { "table": "
Syntax:auth_basic string | off;
Default:
auth_basic off;
Context:http, server, location, limit_except
", "doc": "

Enables validation of user name and password using the “HTTP Basic Authentication” protocol. The specified parameter is used as a realm. Parameter value can contain variables (1.3.10, 1.2.7). The special value off allows cancelling the effect of the auth_basic directive inherited from the previous configuration level.

", "module": "ngx_http_auth_basic_module", "link": "http/ngx_http_auth_basic_module.html#auth_basic", "name": "auth_basic" }, { "table": "
Syntax:auth_basic_user_file file;
Default:—
Context:http, server, location, limit_except
", "doc": "

Specifies a file that keeps user names and passwords, in the following format:

\n# comment\nname1:password1\nname2:password2:comment\nname3:password3\n

The file name can contain variables.

The following password types are supported:

", "module": "ngx_http_auth_basic_module", "link": "http/ngx_http_auth_basic_module.html#auth_basic_user_file", "name": "auth_basic_user_file" }, { "table": "
Syntax:auth_jwt string [token=$variable] | off;
Default:
auth_jwt off;
Context:http, server, location, limit_except
", "doc": "

Enables validation of JSON Web Token. The specified string is used as a realm. Parameter value can contain variables.

The optional token parameter specifies a variable that contains JSON Web Token. By default, JWT is passed in the “Authorization” header as a Bearer Token. JWT may be also passed as a cookie or a part of a query string:

\nauth_jwt "closed site" token=$cookie_auth_token;\n

The special value off cancels the effect of the auth_jwt directive inherited from the previous configuration level.

", "module": "ngx_http_auth_jwt_module", "link": "http/ngx_http_auth_jwt_module.html#auth_jwt", "name": "auth_jwt" }, { "table": "
Syntax:auth_jwt_claim_set $variable name ...;
Default:—
Context:http

This directive appeared in version 1.11.10.

", "doc": "

Sets the variable to a JWT claim parameter identified by key names. Name matching starts from the top level of the JSON tree. For arrays, the variable keeps a list of array elements separated by commas.

\nlocation / {\n    auth_jwt           "closed site";\n    auth_jwt_key_file  conf/keys.json;\n    auth_jwt_claim_set $email info e-mail;\n    auth_jwt_claim_set $job info "job title";\n}\n
Prior to version 1.13.7, only one key name could be specified, and the result was undefined for arrays.
", "module": "ngx_http_auth_jwt_module", "link": "http/ngx_http_auth_jwt_module.html#auth_jwt_claim_set", "name": "auth_jwt_claim_set" }, { "table": "
Syntax:auth_jwt_header_set $variable name ...;
Default:—
Context:http

This directive appeared in version 1.11.10.

", "doc": "

Sets the variable to a JOSE header parameter identified by key names. Name matching starts from the top level of the JSON tree. For arrays, the variable keeps a list of array elements separated by commas.

Prior to version 1.13.7, only one key name could be specified, and the result was undefined for arrays.
", "module": "ngx_http_auth_jwt_module", "link": "http/ngx_http_auth_jwt_module.html#auth_jwt_header_set", "name": "auth_jwt_header_set" }, { "table": "
Syntax:auth_jwt_key_file file;
Default:—
Context:http, server, location, limit_except
", "doc": "

Specifies a file in JSON Web Key Set format for validating JWT signature. Parameter value can contain variables.

", "module": "ngx_http_auth_jwt_module", "link": "http/ngx_http_auth_jwt_module.html#auth_jwt_key_file", "name": "auth_jwt_key_file" }, { "table": "
Syntax:auth_jwt_leeway time;
Default:
auth_jwt_leeway 0s;
Context:http, server, location

This directive appeared in version 1.13.10.

", "doc": "

Sets the maximum allowable leeway to compensate clock skew when verifying the exp and nbf JWT claims.

", "module": "ngx_http_auth_jwt_module", "link": "http/ngx_http_auth_jwt_module.html#auth_jwt_leeway", "name": "auth_jwt_leeway" }, { "table": "
Syntax:auth_request uri | off;
Default:
auth_request off;
Context:http, server, location
", "doc": "

Enables authorization based on the result of a subrequest and sets the URI to which the subrequest will be sent.

", "module": "ngx_http_auth_request_module", "link": "http/ngx_http_auth_request_module.html#auth_request", "name": "auth_request" }, { "table": "
Syntax:auth_request_set $variable value;
Default:—
Context:http, server, location
", "doc": "

Sets the request variable to the given value after the authorization request completes. The value may contain variables from the authorization request, such as $upstream_http_*.

", "module": "ngx_http_auth_request_module", "link": "http/ngx_http_auth_request_module.html#auth_request_set", "name": "auth_request_set" }, { "table": "
Syntax:autoindex on | off;
Default:
autoindex off;
Context:http, server, location
", "doc": "

Enables or disables the directory listing output.

", "module": "ngx_http_autoindex_module", "link": "http/ngx_http_autoindex_module.html#autoindex", "name": "autoindex" }, { "table": "
Syntax:autoindex_exact_size on | off;
Default:
autoindex_exact_size on;
Context:http, server, location
", "doc": "

For the HTML format, specifies whether exact file sizes should be output in the directory listing, or rather rounded to kilobytes, megabytes, and gigabytes.

", "module": "ngx_http_autoindex_module", "link": "http/ngx_http_autoindex_module.html#autoindex_exact_size", "name": "autoindex_exact_size" }, { "table": "
Syntax:autoindex_format html | xml | json | jsonp;
Default:
autoindex_format html;
Context:http, server, location

This directive appeared in version 1.7.9.

", "doc": "

Sets the format of a directory listing.

When the JSONP format is used, the name of a callback function is set with the callback request argument. If the argument is missing or has an empty value, then the JSON format is used.

The XML output can be transformed using the ngx_http_xslt_module module.

", "module": "ngx_http_autoindex_module", "link": "http/ngx_http_autoindex_module.html#autoindex_format", "name": "autoindex_format" }, { "table": "
Syntax:autoindex_localtime on | off;
Default:
autoindex_localtime off;
Context:http, server, location
", "doc": "

For the HTML format, specifies whether times in the directory listing should be output in the local time zone or UTC.

", "module": "ngx_http_autoindex_module", "link": "http/ngx_http_autoindex_module.html#autoindex_localtime", "name": "autoindex_localtime" }, { "table": "
Syntax:ancient_browser string ...;
Default:—
Context:http, server, location
", "doc": "

If any of the specified substrings is found in the “User-Agent” request header field, the browser will be considered ancient. The special string “netscape4” corresponds to the regular expression “^Mozilla/[1-4]”.

", "module": "ngx_http_browser_module", "link": "http/ngx_http_browser_module.html#ancient_browser", "name": "ancient_browser" }, { "table": "
Syntax:ancient_browser_value string;
Default:
ancient_browser_value 1;
Context:http, server, location
", "doc": "

Sets a value for the $ancient_browser variables.

", "module": "ngx_http_browser_module", "link": "http/ngx_http_browser_module.html#ancient_browser_value", "name": "ancient_browser_value" }, { "table": "
Syntax:modern_browser browser version;
modern_browser unlisted;
Default:—
Context:http, server, location
", "doc": "

Specifies a version starting from which a browser is considered modern. A browser can be any one of the following: msie, gecko (browsers based on Mozilla), opera, safari, or konqueror.

Versions can be specified in the following formats: X, X.X, X.X.X, or X.X.X.X. The maximum values for each of the format are 4000, 4000.99, 4000.99.99, and 4000.99.99.99, respectively.

The special value unlisted specifies to consider a browser as modern if it was not listed by the modern_browser and ancient_browser directives. Otherwise such a browser is considered ancient. If a request does not provide the “User-Agent” field in the header, the browser is treated as not being listed.

", "module": "ngx_http_browser_module", "link": "http/ngx_http_browser_module.html#modern_browser", "name": "modern_browser" }, { "table": "
Syntax:modern_browser_value string;
Default:
modern_browser_value 1;
Context:http, server, location
", "doc": "

Sets a value for the $modern_browser variables.

", "module": "ngx_http_browser_module", "link": "http/ngx_http_browser_module.html#modern_browser_value", "name": "modern_browser_value" }, { "table": "
Syntax:charset charset | off;
Default:
charset off;
Context:http, server, location, if in location
", "doc": "

Adds the specified charset to the “Content-Type” response header field. If this charset is different from the charset specified in the source_charset directive, a conversion is performed.

The parameter off cancels the addition of charset to the “Content-Type” response header field.

A charset can be defined with a variable:

\ncharset $charset;\n

In such a case, all possible values of a variable need to be present in the configuration at least once in the form of the charset_map, charset, or source_charset directives. For utf-8, windows-1251, and koi8-r charsets, it is sufficient to include the files conf/koi-win, conf/koi-utf, and conf/win-utf into configuration. For other charsets, simply making a fictitious conversion table works, for example:

\ncharset_map iso-8859-5 _ { }\n

In addition, a charset can be set in the “X-Accel-Charset” response header field. This capability can be disabled using the proxy_ignore_headers, fastcgi_ignore_headers, uwsgi_ignore_headers, scgi_ignore_headers, and grpc_ignore_headers directives.

", "module": "ngx_http_charset_module", "link": "http/ngx_http_charset_module.html#charset", "name": "charset" }, { "table": "
Syntax:charset_map charset1 charset2 { ... }
Default:—
Context:http
", "doc": "

Describes the conversion table from one charset to another. A reverse conversion table is built using the same data. Character codes are given in hexadecimal. Missing characters in the range 80-FF are replaced with “?”. When converting from UTF-8, characters missing in a one-byte charset are replaced with “&#XXXX;”.

Example:

\ncharset_map koi8-r windows-1251 {\n    C0 FE ; # small yu\n    C1 E0 ; # small a\n    C2 E1 ; # small b\n    C3 F6 ; # small ts\n    ...\n}\n

When describing a conversion table to UTF-8, codes for the UTF-8 charset should be given in the second column, for example:

\ncharset_map koi8-r utf-8 {\n    C0 D18E ; # small yu\n    C1 D0B0 ; # small a\n    C2 D0B1 ; # small b\n    C3 D186 ; # small ts\n    ...\n}\n

Full conversion tables from koi8-r to windows-1251, and from koi8-r and windows-1251 to utf-8 are provided in the distribution files conf/koi-win, conf/koi-utf, and conf/win-utf.

", "module": "ngx_http_charset_module", "link": "http/ngx_http_charset_module.html#charset_map", "name": "charset_map" }, { "table": "
Syntax:charset_types mime-type ...;
Default:
charset_types text/html text/xml text/plain text/vnd.wap.wml\napplication/javascript application/rss+xml;
Context:http, server, location

This directive appeared in version 0.7.9.

", "doc": "

Enables module processing in responses with the specified MIME types in addition to “text/html”. The special value “*” matches any MIME type (0.8.29).

Until version 1.5.4, “application/x-javascript” was used as the default MIME type instead of “application/javascript”.
", "module": "ngx_http_charset_module", "link": "http/ngx_http_charset_module.html#charset_types", "name": "charset_types" }, { "table": "
Syntax:override_charset on | off;
Default:
override_charset off;
Context:http, server, location, if in location
", "doc": "

Determines whether a conversion should be performed for answers received from a proxied or a FastCGI/uwsgi/SCGI/gRPC server when the answers already carry a charset in the “Content-Type” response header field. If conversion is enabled, a charset specified in the received response is used as a source charset.

It should be noted that if a response is received in a subrequest then the conversion from the response charset to the main request charset is always performed, regardless of the override_charset directive setting.
", "module": "ngx_http_charset_module", "link": "http/ngx_http_charset_module.html#override_charset", "name": "override_charset" }, { "table": "
Syntax:source_charset charset;
Default:—
Context:http, server, location, if in location
", "doc": "

Defines the source charset of a response. If this charset is different from the charset specified in the charset directive, a conversion is performed.

", "module": "ngx_http_charset_module", "link": "http/ngx_http_charset_module.html#source_charset", "name": "source_charset" }, { "table": "
Syntax:create_full_put_path on | off;
Default:
create_full_put_path off;
Context:http, server, location
", "doc": "

The WebDAV specification only allows creating files in already existing directories. This directive allows creating all needed intermediate directories.

", "module": "ngx_http_dav_module", "link": "http/ngx_http_dav_module.html#create_full_put_path", "name": "create_full_put_path" }, { "table": "
Syntax:dav_access users:permissions ...;
Default:
dav_access user:rw;
Context:http, server, location
", "doc": "

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

\ndav_access user:rw group:rw all:r;\n

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

\ndav_access group:rw all:r;\n
", "module": "ngx_http_dav_module", "link": "http/ngx_http_dav_module.html#dav_access", "name": "dav_access" }, { "table": "
Syntax:dav_methods off | method ...;
Default:
dav_methods off;
Context:http, server, location
", "doc": "

Allows the specified HTTP and WebDAV methods. The parameter off denies all methods processed by this module. The following methods are supported: PUT, DELETE, MKCOL, COPY, and MOVE.

A file uploaded with the PUT method 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 client_body_temp_path directive, are put on the same file system.

When creating a file with the PUT method, it is possible to specify the modification date by passing it in the “Date” header field.

", "module": "ngx_http_dav_module", "link": "http/ngx_http_dav_module.html#dav_methods", "name": "dav_methods" }, { "table": "
Syntax:min_delete_depth number;
Default:
min_delete_depth 0;
Context:http, server, location
", "doc": "

Allows the DELETE method to remove files provided that the number of elements in a request path is not less than the specified number. For example, the directive

\nmin_delete_depth 4;\n

allows removing files on requests

\n/users/00/00/name\n/users/00/00/name/pic.jpg\n/users/00/00/page.html\n

and denies the removal of

\n/users/00/00\n
", "module": "ngx_http_dav_module", "link": "http/ngx_http_dav_module.html#min_delete_depth", "name": "min_delete_depth" }, { "table": "
Syntax:empty_gif;
Default:—
Context:location
", "doc": "

Turns on module processing in a surrounding location.

", "module": "ngx_http_empty_gif_module", "link": "http/ngx_http_empty_gif_module.html#empty_gif", "name": "empty_gif" }, { "table": "
Syntax:f4f;
Default:—
Context:location
", "doc": "

Turns on module processing in the surrounding location.

", "module": "ngx_http_f4f_module", "link": "http/ngx_http_f4f_module.html#f4f", "name": "f4f" }, { "table": "
Syntax:f4f_buffer_size size;
Default:
f4f_buffer_size 512k;
Context:http, server, location
", "doc": "

Sets the size of the buffer used for reading the .f4x index file.

", "module": "ngx_http_f4f_module", "link": "http/ngx_http_f4f_module.html#f4f_buffer_size", "name": "f4f_buffer_size" }, { "table": "
Syntax:fastcgi_bind address [transparent] | off;
Default:—
Context:http, server, location

This directive appeared in version 0.8.22.

", "doc": "

Makes outgoing connections to a FastCGI 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 fastcgi_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address and port.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_bind", "name": "fastcgi_bind" }, { "table": "
Syntax:fastcgi_buffer_size size;
Default:
fastcgi_buffer_size 4k|8k;
Context:http, server, location
", "doc": "

Sets the size of the buffer used for reading the first part of the response received from the FastCGI 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.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_buffer_size", "name": "fastcgi_buffer_size" }, { "table": "
Syntax:fastcgi_buffering on | off;
Default:
fastcgi_buffering on;
Context:http, server, location

This directive appeared in version 1.5.6.

", "doc": "

Enables or disables buffering of responses from the FastCGI server.

When buffering is enabled, nginx receives a response from the FastCGI server as soon as possible, saving it into the buffers set by the fastcgi_buffer_size and fastcgi_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 fastcgi_max_temp_file_size and fastcgi_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 FastCGI server. The maximum size of the data that nginx can receive from the server at a time is set by the fastcgi_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 fastcgi_ignore_headers directive.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_buffering", "name": "fastcgi_buffering" }, { "table": "
Syntax:fastcgi_buffers number size;
Default:
fastcgi_buffers 8 4k|8k;
Context:http, server, location
", "doc": "

Sets the number and size of the buffers used for reading a response from the FastCGI 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.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_buffers", "name": "fastcgi_buffers" }, { "table": "
Syntax:fastcgi_busy_buffers_size size;
Default:
fastcgi_busy_buffers_size 8k|16k;
Context:http, server, location
", "doc": "

When buffering of responses from the FastCGI 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 fastcgi_buffer_size and fastcgi_buffers directives.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_busy_buffers_size", "name": "fastcgi_busy_buffers_size" }, { "table": "
Syntax:fastcgi_cache zone | off;
Default:
fastcgi_cache off;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_cache", "name": "fastcgi_cache" }, { "table": "
Syntax:fastcgi_cache_background_update on | off;
Default:
fastcgi_cache_background_update off;
Context:http, server, location

This directive appeared in version 1.11.10.

", "doc": "

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.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_cache_background_update", "name": "fastcgi_cache_background_update" }, { "table": "
Syntax:fastcgi_cache_bypass string ...;
Default:—
Context:http, server, location
", "doc": "

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:

\nfastcgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;\nfastcgi_cache_bypass $http_pragma    $http_authorization;\n

Can be used along with the fastcgi_no_cache directive.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_cache_bypass", "name": "fastcgi_cache_bypass" }, { "table": "
Syntax:fastcgi_cache_key string;
Default:—
Context:http, server, location
", "doc": "

Defines a key for caching, for example

\nfastcgi_cache_key localhost:9000$request_uri;\n
", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_cache_key", "name": "fastcgi_cache_key" }, { "table": "
Syntax:fastcgi_cache_lock on | off;
Default:
fastcgi_cache_lock off;
Context:http, server, location

This directive appeared in version 1.1.12.

", "doc": "

When enabled, only one request at a time will be allowed to populate a new cache element identified according to the fastcgi_cache_key directive by passing a request to a FastCGI 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 fastcgi_cache_lock_timeout directive.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_cache_lock", "name": "fastcgi_cache_lock" }, { "table": "
Syntax:fastcgi_cache_lock_age time;
Default:
fastcgi_cache_lock_age 5s;
Context:http, server, location

This directive appeared in version 1.7.8.

", "doc": "

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

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_cache_lock_age", "name": "fastcgi_cache_lock_age" }, { "table": "
Syntax:fastcgi_cache_lock_timeout time;
Default:
fastcgi_cache_lock_timeout 5s;
Context:http, server, location

This directive appeared in version 1.1.12.

", "doc": "

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

Before 1.7.8, the response could be cached.
", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_cache_lock_timeout", "name": "fastcgi_cache_lock_timeout" }, { "table": "
Syntax:fastcgi_cache_max_range_offset number;
Default:—
Context:http, server, location

This directive appeared in version 1.11.6.

", "doc": "

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

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_cache_max_range_offset", "name": "fastcgi_cache_max_range_offset" }, { "table": "
Syntax:fastcgi_cache_methods GET | HEAD | POST ...;
Default:
fastcgi_cache_methods GET HEAD;
Context:http, server, location

This directive appeared in version 0.7.59.

", "doc": "

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 fastcgi_no_cache directive.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_cache_methods", "name": "fastcgi_cache_methods" }, { "table": "
Syntax:fastcgi_cache_min_uses number;
Default:
fastcgi_cache_min_uses 1;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_cache_min_uses", "name": "fastcgi_cache_min_uses" }, { "table": "
Syntax:fastcgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time];
Default:—
Context:http
", "doc": "

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

\nfastcgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;\n

file names in a cache will look like this:

\n/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c\n

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. A 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 fastcgi_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.

As part of commercial subscription, the shared memory zone also stores extended cache information, thus, it is required to specify a larger zone size for the same number of keys. For example, one megabyte zone can store about 4 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. When this size is exceeded, 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.
In versions 1.7.3, 1.7.7, and 1.11.10 cache header format has been changed. Previously cached responses will be considered invalid after upgrading to a newer nginx version.
", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_cache_path", "name": "fastcgi_cache_path" }, { "table": "
Syntax:fastcgi_cache_purge string ...;
Default:—
Context:http, server, location

This directive appeared in version 1.5.7.

", "doc": "

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.

Example configuration:

\nfastcgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;\n\nmap $request_method $purge_method {\n    PURGE   1;\n    default 0;\n}\n\nserver {\n    ...\n    location / {\n        fastcgi_pass        backend;\n        fastcgi_cache       cache_zone;\n        fastcgi_cache_key   $uri;\n        fastcgi_cache_purge $purge_method;\n    }\n}\n
This functionality is available as part of our commercial subscription.
", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_cache_purge", "name": "fastcgi_cache_purge" }, { "table": "
Syntax:fastcgi_cache_revalidate on | off;
Default:
fastcgi_cache_revalidate off;
Context:http, server, location

This directive appeared in version 1.5.7.

", "doc": "

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

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_cache_revalidate", "name": "fastcgi_cache_revalidate" }, { "table": "
Syntax:fastcgi_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_503 | http_403 | http_404 | http_429 | off ...;
Default:
fastcgi_cache_use_stale off;
Context:http, server, location
", "doc": "

Determines in which cases a stale cached response can be used when an error occurs during communication with the FastCGI server. The directive’s parameters match the parameters of the fastcgi_next_upstream directive.

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

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_cache_use_stale", "name": "fastcgi_cache_use_stale" }, { "table": "
Syntax:fastcgi_cache_valid [code ...] time;
Default:—
Context:http, server, location
", "doc": "

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

\nfastcgi_cache_valid 200 302 10m;\nfastcgi_cache_valid 404      1m;\n

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

\nfastcgi_cache_valid 5m;\n

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

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

\nfastcgi_cache_valid 200 302 10m;\nfastcgi_cache_valid 301      1h;\nfastcgi_cache_valid any      1m;\n

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

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_cache_valid", "name": "fastcgi_cache_valid" }, { "table": "
Syntax:fastcgi_catch_stderr string;
Default:—
Context:http, server, location
", "doc": "

Sets a string to search for in the error stream of a response received from a FastCGI server. If the string is found then it is considered that the FastCGI server has returned an invalid response. This allows handling application errors in nginx, for example:

\nlocation /php {\n    fastcgi_pass backend:9000;\n    ...\n    fastcgi_catch_stderr "PHP Fatal error";\n    fastcgi_next_upstream error timeout invalid_header;\n}\n
", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_catch_stderr", "name": "fastcgi_catch_stderr" }, { "table": "
Syntax:fastcgi_connect_timeout time;
Default:
fastcgi_connect_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_connect_timeout", "name": "fastcgi_connect_timeout" }, { "table": "
Syntax:fastcgi_force_ranges on | off;
Default:
fastcgi_force_ranges off;
Context:http, server, location

This directive appeared in version 1.7.7.

", "doc": "

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

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_force_ranges", "name": "fastcgi_force_ranges" }, { "table": "
Syntax:fastcgi_hide_header field;
Default:—
Context:http, server, location
", "doc": "

By default, nginx does not pass the header fields “Status” and “X-Accel-...” from the response of a FastCGI server to a client. The fastcgi_hide_header directive sets additional fields that will not be passed. If, on the contrary, the passing of fields needs to be permitted, the fastcgi_pass_header directive can be used.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_hide_header", "name": "fastcgi_hide_header" }, { "table": "
Syntax:fastcgi_ignore_client_abort on | off;
Default:
fastcgi_ignore_client_abort off;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_ignore_client_abort", "name": "fastcgi_ignore_client_abort" }, { "table": "
Syntax:fastcgi_ignore_headers field ...;
Default:—
Context:http, server, location
", "doc": "

Disables processing of certain response header fields from the FastCGI 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:

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_ignore_headers", "name": "fastcgi_ignore_headers" }, { "table": "
Syntax:fastcgi_index name;
Default:—
Context:http, server, location
", "doc": "

Sets a file name that will be appended after a URI that ends with a slash, in the value of the $fastcgi_script_name variable. For example, with these settings

\nfastcgi_index index.php;\nfastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;\n

and the “/page.php” request, the SCRIPT_FILENAME parameter will be equal to “/home/www/scripts/php/page.php”, and with the “/” request it will be equal to “/home/www/scripts/php/index.php”.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_index", "name": "fastcgi_index" }, { "table": "
Syntax:fastcgi_intercept_errors on | off;
Default:
fastcgi_intercept_errors off;
Context:http, server, location
", "doc": "

Determines whether FastCGI server 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.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_intercept_errors", "name": "fastcgi_intercept_errors" }, { "table": "
Syntax:fastcgi_keep_conn on | off;
Default:
fastcgi_keep_conn off;
Context:http, server, location

This directive appeared in version 1.1.4.

", "doc": "

By default, a FastCGI server will close a connection right after sending the response. However, when this directive is set to the value on, nginx will instruct a FastCGI server to keep connections open. This is necessary, in particular, for keepalive connections to FastCGI servers to function.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_keep_conn", "name": "fastcgi_keep_conn" }, { "table": "
Syntax:fastcgi_limit_rate rate;
Default:
fastcgi_limit_rate 0;
Context:http, server, location

This directive appeared in version 1.7.7.

", "doc": "

Limits the speed of reading the response from the FastCGI 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 FastCFI server, the overall rate will be twice as much as the specified limit. The limitation works only if buffering of responses from the FastCGI server is enabled.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_limit_rate", "name": "fastcgi_limit_rate" }, { "table": "
Syntax:fastcgi_max_temp_file_size size;
Default:
fastcgi_max_temp_file_size 1024m;
Context:http, server, location
", "doc": "

When buffering of responses from the FastCGI server is enabled, and the whole response does not fit into the buffers set by the fastcgi_buffer_size and fastcgi_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 fastcgi_temp_file_write_size directive.

The zero value disables buffering of responses to temporary files.

This restriction does not apply to responses that will be cached or stored on disk.
", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_max_temp_file_size", "name": "fastcgi_max_temp_file_size" }, { "table": "
Syntax:fastcgi_next_upstream error | timeout | invalid_header | http_500 | http_503 | http_403 | http_404 | http_429 | non_idempotent | off ...;
Default:
fastcgi_next_upstream error timeout;
Context:http, server, location
", "doc": "

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_503
a server returned a response with the code 503;
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_503, 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.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_next_upstream", "name": "fastcgi_next_upstream" }, { "table": "
Syntax:fastcgi_next_upstream_timeout time;
Default:
fastcgi_next_upstream_timeout 0;
Context:http, server, location

This directive appeared in version 1.7.5.

", "doc": "

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

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_next_upstream_timeout", "name": "fastcgi_next_upstream_timeout" }, { "table": "
Syntax:fastcgi_next_upstream_tries number;
Default:
fastcgi_next_upstream_tries 0;
Context:http, server, location

This directive appeared in version 1.7.5.

", "doc": "

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

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_next_upstream_tries", "name": "fastcgi_next_upstream_tries" }, { "table": "
Syntax:fastcgi_no_cache string ...;
Default:—
Context:http, server, location
", "doc": "

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:

\nfastcgi_no_cache $cookie_nocache $arg_nocache$arg_comment;\nfastcgi_no_cache $http_pragma    $http_authorization;\n

Can be used along with the fastcgi_cache_bypass directive.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_no_cache", "name": "fastcgi_no_cache" }, { "table": "
Syntax:fastcgi_param parameter value [if_not_empty];
Default:—
Context:http, server, location
", "doc": "

Sets a parameter that should be passed to the FastCGI server. The value can contain text, variables, and their combination. These directives are inherited from the previous level if and only if there are no fastcgi_param directives defined on the current level.

The following example shows the minimum required settings for PHP:

\nfastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;\nfastcgi_param QUERY_STRING    $query_string;\n

The SCRIPT_FILENAME parameter is used in PHP for determining the script name, and the QUERY_STRING parameter is used to pass request parameters.

For scripts that process POST requests, the following three parameters are also required:

\nfastcgi_param REQUEST_METHOD  $request_method;\nfastcgi_param CONTENT_TYPE    $content_type;\nfastcgi_param CONTENT_LENGTH  $content_length;\n

If PHP was built with the --enable-force-cgi-redirect configuration parameter, the REDIRECT_STATUS parameter should also be passed with the value “200”:

\nfastcgi_param REDIRECT_STATUS 200;\n

If the directive is specified with if_not_empty (1.1.11) then such a parameter will be passed to the server only if its value is not empty:

\nfastcgi_param HTTPS           $https if_not_empty;\n
", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_param", "name": "fastcgi_param" }, { "table": "
Syntax:fastcgi_pass address;
Default:—
Context:location, if in location
", "doc": "

Sets the address of a FastCGI server. The address can be specified as a domain name or IP address, and a port:

\nfastcgi_pass localhost:9000;\n

or as a UNIX-domain socket path:

\nfastcgi_pass unix:/tmp/fastcgi.socket;\n

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.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_pass", "name": "fastcgi_pass" }, { "table": "
Syntax:fastcgi_pass_header field;
Default:—
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_pass_header", "name": "fastcgi_pass_header" }, { "table": "
Syntax:fastcgi_pass_request_body on | off;
Default:
fastcgi_pass_request_body on;
Context:http, server, location
", "doc": "

Indicates whether the original request body is passed to the FastCGI server. See also the fastcgi_pass_request_headers directive.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_pass_request_body", "name": "fastcgi_pass_request_body" }, { "table": "
Syntax:fastcgi_pass_request_headers on | off;
Default:
fastcgi_pass_request_headers on;
Context:http, server, location
", "doc": "

Indicates whether the header fields of the original request are passed to the FastCGI server. See also the fastcgi_pass_request_body directive.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_pass_request_headers", "name": "fastcgi_pass_request_headers" }, { "table": "
Syntax:fastcgi_read_timeout time;
Default:
fastcgi_read_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_read_timeout", "name": "fastcgi_read_timeout" }, { "table": "
Syntax:fastcgi_request_buffering on | off;
Default:
fastcgi_request_buffering on;
Context:http, server, location

This directive appeared in version 1.7.11.

", "doc": "

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 FastCGI server.

When buffering is disabled, the request body is sent to the FastCGI 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.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_request_buffering", "name": "fastcgi_request_buffering" }, { "table": "
Syntax:fastcgi_send_lowat size;
Default:
fastcgi_send_lowat 0;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_send_lowat", "name": "fastcgi_send_lowat" }, { "table": "
Syntax:fastcgi_send_timeout time;
Default:
fastcgi_send_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_send_timeout", "name": "fastcgi_send_timeout" }, { "table": "
Syntax:fastcgi_split_path_info regex;
Default:—
Context:location
", "doc": "

Defines a regular expression that captures a value for the $fastcgi_path_info variable. The regular expression should have two captures: the first becomes a value of the $fastcgi_script_name variable, the second becomes a value of the $fastcgi_path_info variable. For example, with these settings

\nlocation ~ ^(.+\\.php)(.*)$ {\n    fastcgi_split_path_info       ^(.+\\.php)(.*)$;\n    fastcgi_param SCRIPT_FILENAME /path/to/php$fastcgi_script_name;\n    fastcgi_param PATH_INFO       $fastcgi_path_info;\n

and the “/show.php/article/0001” request, the SCRIPT_FILENAME parameter will be equal to “/path/to/php/show.php”, and the PATH_INFO parameter will be equal to “/article/0001”.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_split_path_info", "name": "fastcgi_split_path_info" }, { "table": "
Syntax:fastcgi_store on | off | string;
Default:
fastcgi_store off;
Context:http, server, location
", "doc": "

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:

\nfastcgi_store /data/www$original_uri;\n

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 fastcgi_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.:

\nlocation /images/ {\n    root                 /data/www;\n    error_page           404 = /fetch$uri;\n}\n\nlocation /fetch/ {\n    internal;\n\n    fastcgi_pass         backend:9000;\n    ...\n\n    fastcgi_store        on;\n    fastcgi_store_access user:rw group:rw all:r;\n    fastcgi_temp_path    /data/temp;\n\n    alias                /data/www/;\n}\n
", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_store", "name": "fastcgi_store" }, { "table": "
Syntax:fastcgi_store_access users:permissions ...;
Default:
fastcgi_store_access user:rw;
Context:http, server, location
", "doc": "

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

\nfastcgi_store_access user:rw group:rw all:r;\n

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

\nfastcgi_store_access group:rw all:r;\n
", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_store_access", "name": "fastcgi_store_access" }, { "table": "
Syntax:fastcgi_temp_file_write_size size;
Default:
fastcgi_temp_file_write_size 8k|16k;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_temp_file_write_size", "name": "fastcgi_temp_file_write_size" }, { "table": "
Syntax:fastcgi_temp_path path [level1 [level2 [level3]]];
Default:
fastcgi_temp_path fastcgi_temp;
Context:http, server, location
", "doc": "

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

\nfastcgi_temp_path /spool/nginx/fastcgi_temp 1 2;\n

a temporary file might look like this:

\n/spool/nginx/fastcgi_temp/7/45/00000123457\n

See also the use_temp_path parameter of the fastcgi_cache_path directive.

", "module": "ngx_http_fastcgi_module", "link": "http/ngx_http_fastcgi_module.html#fastcgi_temp_path", "name": "fastcgi_temp_path" }, { "table": "
Syntax:flv;
Default:—
Context:location
", "doc": "

Turns on module processing in a surrounding location.

", "module": "ngx_http_flv_module", "link": "http/ngx_http_flv_module.html#flv", "name": "flv" }, { "table": "
Syntax:geo [$address] $variable { ... }
Default:—
Context:http
", "doc": "

Describes the dependency of values of the specified variable on the client IP address. By default, the address is taken from the $remote_addr variable, but it can also be taken from another variable (0.7.27), for example:

\ngeo $arg_remote_addr $geo {\n    ...;\n}\n
Since variables are evaluated only when used, the mere existence of even a large number of declared “geo” variables does not cause any extra costs for request processing.

If the value of a variable does not represent a valid IP address then the “255.255.255.255” address is used.

Addresses are specified either as prefixes in CIDR notation (including individual addresses) or as ranges (0.7.23).

IPv6 prefixes are supported starting from versions 1.3.10 and 1.2.7.

The following special parameters are also supported:

delete
deletes the specified network (0.7.23).
default
a value set to the variable if the client address does not match any of the specified addresses. When addresses are specified in CIDR notation, “0.0.0.0/0” and “::/0” can be used instead of default. When default is not specified, the default value will be an empty string.
include
includes a file with addresses and values. There can be several inclusions.
proxy
defines trusted addresses (0.8.7, 0.7.63). When a request comes from a trusted address, an address from the “X-Forwarded-For” request header field will be used instead. In contrast to the regular addresses, trusted addresses are checked sequentially.
Trusted IPv6 addresses are supported starting from versions 1.3.0 and 1.2.1.
proxy_recursive
enables recursive address search (1.3.0, 1.2.1). If recursive search is disabled then instead of the original client address that matches one of the trusted addresses, the last address sent in “X-Forwarded-For” will be used. If recursive search is enabled then instead of the original client address that matches one of the trusted addresses, the last non-trusted address sent in “X-Forwarded-For” will be used.
ranges
indicates that addresses are specified as ranges (0.7.23). This parameter should be the first. To speed up loading of a geo base, addresses should be put in ascending order.

Example:

\ngeo $country {\n    default        ZZ;\n    include        conf/geo.conf;\n    delete         127.0.0.0/16;\n    proxy          192.168.100.0/24;\n    proxy          2001:0db8::/32;\n\n    127.0.0.0/24   US;\n    127.0.0.1/32   RU;\n    10.1.0.0/16    RU;\n    192.168.1.0/24 UK;\n}\n

The conf/geo.conf file could contain the following lines:

\n10.2.0.0/16    RU;\n192.168.2.0/24 RU;\n

A value of the most specific match is used. For example, for the 127.0.0.1 address the value “RU” will be chosen, not “US”.

Example with ranges:

\ngeo $country {\n    ranges;\n    default                   ZZ;\n    127.0.0.0-127.0.0.0       US;\n    127.0.0.1-127.0.0.1       RU;\n    127.0.0.1-127.0.0.255     US;\n    10.1.0.0-10.1.255.255     RU;\n    192.168.1.0-192.168.1.255 UK;\n}\n
", "module": "ngx_http_geo_module", "link": "http/ngx_http_geo_module.html#geo", "name": "geo" }, { "table": "
Syntax:geoip_country file;
Default:—
Context:http
", "doc": "

Specifies a database used to determine the country depending on the client IP address. The following variables are available when using this database:

$geoip_country_code
two-letter country code, for example, “RU”, “US”.
$geoip_country_code3
three-letter country code, for example, “RUS”, “USA”.
$geoip_country_name
country name, for example, “Russian Federation”, “United States”.
", "module": "ngx_http_geoip_module", "link": "http/ngx_http_geoip_module.html#geoip_country", "name": "geoip_country" }, { "table": "
Syntax:geoip_city file;
Default:—
Context:http
", "doc": "

Specifies a database used to determine the country, region, and city depending on the client IP address. The following variables are available when using this database:

$geoip_area_code
telephone area code (US only).
This variable may contain outdated information since the corresponding database field is deprecated.
$geoip_city_continent_code
two-letter continent code, for example, “EU”, “NA”.
$geoip_city_country_code
two-letter country code, for example, “RU”, “US”.
$geoip_city_country_code3
three-letter country code, for example, “RUS”, “USA”.
$geoip_city_country_name
country name, for example, “Russian Federation”, “United States”.
$geoip_dma_code
DMA region code in US (also known as “metro code”), according to the geotargeting in Google AdWords API.
$geoip_latitude
latitude.
$geoip_longitude
longitude.
$geoip_region
two-symbol country region code (region, territory, state, province, federal land and the like), for example, “48”, “DC”.
$geoip_region_name
country region name (region, territory, state, province, federal land and the like), for example, “Moscow City”, “District of Columbia”.
$geoip_city
city name, for example, “Moscow”, “Washington”.
$geoip_postal_code
postal code.
", "module": "ngx_http_geoip_module", "link": "http/ngx_http_geoip_module.html#geoip_city", "name": "geoip_city" }, { "table": "
Syntax:geoip_org file;
Default:—
Context:http

This directive appeared in version 1.0.3.

", "doc": "

Specifies a database used to determine the organization depending on the client IP address. The following variable is available when using this database:

$geoip_org
organization name, for example, “The University of Melbourne”.
", "module": "ngx_http_geoip_module", "link": "http/ngx_http_geoip_module.html#geoip_org", "name": "geoip_org" }, { "table": "
Syntax:geoip_proxy address | CIDR;
Default:—
Context:http

This directive appeared in versions 1.3.0 and 1.2.1.

", "doc": "

Defines trusted addresses. When a request comes from a trusted address, an address from the “X-Forwarded-For” request header field will be used instead.

", "module": "ngx_http_geoip_module", "link": "http/ngx_http_geoip_module.html#geoip_proxy", "name": "geoip_proxy" }, { "table": "
Syntax:geoip_proxy_recursive on | off;
Default:
geoip_proxy_recursive off;
Context:http

This directive appeared in versions 1.3.0 and 1.2.1.

", "doc": "

If recursive search is disabled then instead of the original client address that matches one of the trusted addresses, the last address sent in “X-Forwarded-For” will be used. If recursive search is enabled then instead of the original client address that matches one of the trusted addresses, the last non-trusted address sent in “X-Forwarded-For” will be used.

", "module": "ngx_http_geoip_module", "link": "http/ngx_http_geoip_module.html#geoip_proxy_recursive", "name": "geoip_proxy_recursive" }, { "table": "
Syntax:grpc_bind address [transparent] | off;
Default:—
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_bind", "name": "grpc_bind" }, { "table": "
Syntax:grpc_buffer_size size;
Default:
grpc_buffer_size 4k|8k;
Context:http, server, location
", "doc": "

Sets the size of the buffer used for reading the response received from the gRPC server. The response is passed to the client synchronously, as soon as it is received.

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_buffer_size", "name": "grpc_buffer_size" }, { "table": "
Syntax:grpc_connect_timeout time;
Default:
grpc_connect_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_connect_timeout", "name": "grpc_connect_timeout" }, { "table": "
Syntax:grpc_hide_header field;
Default:—
Context:http, server, location
", "doc": "

By default, nginx does not pass the header fields “Date”, “Server”, and “X-Accel-...” from the response of a gRPC server to a client. The grpc_hide_header directive sets additional fields that will not be passed. If, on the contrary, the passing of fields needs to be permitted, the grpc_pass_header directive can be used.

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_hide_header", "name": "grpc_hide_header" }, { "table": "
Syntax:grpc_ignore_headers field ...;
Default:—
Context:http, server, location
", "doc": "

Disables processing of certain response header fields from the gRPC server. The following fields can be ignored: “X-Accel-Redirect” and “X-Accel-Charset”.

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

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_ignore_headers", "name": "grpc_ignore_headers" }, { "table": "
Syntax:grpc_intercept_errors on | off;
Default:
grpc_intercept_errors off;
Context:http, server, location
", "doc": "

Determines whether gRPC server 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.

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_intercept_errors", "name": "grpc_intercept_errors" }, { "table": "
Syntax:grpc_next_upstream error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off ...;
Default:
grpc_next_upstream error timeout;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_next_upstream", "name": "grpc_next_upstream" }, { "table": "
Syntax:grpc_next_upstream_timeout time;
Default:
grpc_next_upstream_timeout 0;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_next_upstream_timeout", "name": "grpc_next_upstream_timeout" }, { "table": "
Syntax:grpc_next_upstream_tries number;
Default:
grpc_next_upstream_tries 0;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_next_upstream_tries", "name": "grpc_next_upstream_tries" }, { "table": "
Syntax:grpc_pass address;
Default:—
Context:location, if in location
", "doc": "

Sets the gRPC server address. The address can be specified as a domain name or IP address, and a port:

\ngrpc_pass localhost:9000;\n

or as a UNIX-domain socket path:

\ngrpc_pass unix:/tmp/grpc.socket;\n

Alternatively, the “grpc://” scheme can be used:

\ngrpc_pass grpc://127.0.0.1:9000;\n

To use gRPC over SSL, the “grpcs://” scheme should be used:

\ngrpc_pass grpcs://127.0.0.1:443;\n

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.

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_pass", "name": "grpc_pass" }, { "table": "
Syntax:grpc_pass_header field;
Default:—
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_pass_header", "name": "grpc_pass_header" }, { "table": "
Syntax:grpc_read_timeout time;
Default:
grpc_read_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_read_timeout", "name": "grpc_read_timeout" }, { "table": "
Syntax:grpc_send_timeout time;
Default:
grpc_send_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_send_timeout", "name": "grpc_send_timeout" }, { "table": "
Syntax:grpc_set_header field value;
Default:
grpc_set_header Content-Length $content_length;
Context:http, server, location
", "doc": "

Allows redefining or appending fields to the request header passed to the gRPC server. The value can contain text, variables, and their combinations. These directives are inherited from the previous level if and only if there are no grpc_set_header directives defined on the current level.

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

\ngrpc_set_header Accept-Encoding "";\n
", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_set_header", "name": "grpc_set_header" }, { "table": "
Syntax:grpc_ssl_certificate file;
Default:—
Context:http, server, location
", "doc": "

Specifies a file with the certificate in the PEM format used for authentication to a gRPC SSL server.

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_ssl_certificate", "name": "grpc_ssl_certificate" }, { "table": "
Syntax:grpc_ssl_certificate_key file;
Default:—
Context:http, server, location
", "doc": "

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

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

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_ssl_certificate_key", "name": "grpc_ssl_certificate_key" }, { "table": "
Syntax:grpc_ssl_ciphers ciphers;
Default:
grpc_ssl_ciphers DEFAULT;
Context:http, server, location
", "doc": "

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

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

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_ssl_ciphers", "name": "grpc_ssl_ciphers" }, { "table": "
Syntax:grpc_ssl_crl file;
Default:—
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_ssl_crl", "name": "grpc_ssl_crl" }, { "table": "
Syntax:grpc_ssl_name name;
Default:
grpc_ssl_name host from grpc_pass;
Context:http, server, location
", "doc": "

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

By default, the host part from grpc_pass is used.

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_ssl_name", "name": "grpc_ssl_name" }, { "table": "
Syntax:grpc_ssl_password_file file;
Default:—
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_ssl_password_file", "name": "grpc_ssl_password_file" }, { "table": "
Syntax:grpc_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default:
grpc_ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
Context:http, server, location
", "doc": "

Enables the specified protocols for requests to a gRPC SSL server.

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_ssl_protocols", "name": "grpc_ssl_protocols" }, { "table": "
Syntax:grpc_ssl_server_name on | off;
Default:
grpc_ssl_server_name off;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_ssl_server_name", "name": "grpc_ssl_server_name" }, { "table": "
Syntax:grpc_ssl_session_reuse on | off;
Default:
grpc_ssl_session_reuse on;
Context:http, server, location
", "doc": "

Determines whether SSL sessions can be reused when working with the gRPC server. If the errors “SSL3_GET_FINISHED:digest check failed” appear in the logs, try disabling session reuse.

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_ssl_session_reuse", "name": "grpc_ssl_session_reuse" }, { "table": "
Syntax:grpc_ssl_trusted_certificate file;
Default:—
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_ssl_trusted_certificate", "name": "grpc_ssl_trusted_certificate" }, { "table": "
Syntax:grpc_ssl_verify on | off;
Default:
grpc_ssl_verify off;
Context:http, server, location
", "doc": "

Enables or disables verification of the gRPC SSL server certificate.

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_ssl_verify", "name": "grpc_ssl_verify" }, { "table": "
Syntax:grpc_ssl_verify_depth number;
Default:
grpc_ssl_verify_depth 1;
Context:http, server, location
", "doc": "

Sets the verification depth in the gRPC SSL server certificates chain.

", "module": "ngx_http_grpc_module", "link": "http/ngx_http_grpc_module.html#grpc_ssl_verify_depth", "name": "grpc_ssl_verify_depth" }, { "table": "
Syntax:gunzip on | off;
Default:
gunzip off;
Context:http, server, location
", "doc": "

Enables or disables decompression of gzipped responses for clients that lack gzip support. If enabled, the following directives are also taken into account when determining if clients support gzip: gzip_http_version, gzip_proxied, and gzip_disable. See also the gzip_vary directive.

", "module": "ngx_http_gunzip_module", "link": "http/ngx_http_gunzip_module.html#gunzip", "name": "gunzip" }, { "table": "
Syntax:gunzip_buffers number size;
Default:
gunzip_buffers 32 4k|16 8k;
Context:http, server, location
", "doc": "

Sets the number and size of buffers used to decompress a response. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.

", "module": "ngx_http_gunzip_module", "link": "http/ngx_http_gunzip_module.html#gunzip_buffers", "name": "gunzip_buffers" }, { "table": "
Syntax:gzip on | off;
Default:
gzip off;
Context:http, server, location, if in location
", "doc": "

Enables or disables gzipping of responses.

", "module": "ngx_http_gzip_module", "link": "http/ngx_http_gzip_module.html#gzip", "name": "gzip" }, { "table": "
Syntax:gzip_buffers number size;
Default:
gzip_buffers 32 4k|16 8k;
Context:http, server, location
", "doc": "

Sets the number and size of buffers used to compress a response. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.

Until version 0.7.28, four 4K or 8K buffers were used by default.
", "module": "ngx_http_gzip_module", "link": "http/ngx_http_gzip_module.html#gzip_buffers", "name": "gzip_buffers" }, { "table": "
Syntax:gzip_comp_level level;
Default:
gzip_comp_level 1;
Context:http, server, location
", "doc": "

Sets a gzip compression level of a response. Acceptable values are in the range from 1 to 9.

", "module": "ngx_http_gzip_module", "link": "http/ngx_http_gzip_module.html#gzip_comp_level", "name": "gzip_comp_level" }, { "table": "
Syntax:gzip_disable regex ...;
Default:—
Context:http, server, location

This directive appeared in version 0.6.23.

", "doc": "

Disables gzipping of responses for requests with “User-Agent” header fields matching any of the specified regular expressions.

The special mask “msie6” (0.7.12) corresponds to the regular expression “MSIE [4-6]\\.”, but works faster. Starting from version 0.8.11, “MSIE 6.0; ... SV1” is excluded from this mask.

", "module": "ngx_http_gzip_module", "link": "http/ngx_http_gzip_module.html#gzip_disable", "name": "gzip_disable" }, { "table": "
Syntax:gzip_http_version 1.0 | 1.1;
Default:
gzip_http_version 1.1;
Context:http, server, location
", "doc": "

Sets the minimum HTTP version of a request required to compress a response.

", "module": "ngx_http_gzip_module", "link": "http/ngx_http_gzip_module.html#gzip_http_version", "name": "gzip_http_version" }, { "table": "
Syntax:gzip_min_length length;
Default:
gzip_min_length 20;
Context:http, server, location
", "doc": "

Sets the minimum length of a response that will be gzipped. The length is determined only from the “Content-Length” response header field.

", "module": "ngx_http_gzip_module", "link": "http/ngx_http_gzip_module.html#gzip_min_length", "name": "gzip_min_length" }, { "table": "
Syntax:gzip_proxied off | expired | no-cache | no-store | private | no_last_modified | no_etag | auth | any ...;
Default:
gzip_proxied off;
Context:http, server, location
", "doc": "

Enables or disables gzipping of responses for proxied requests depending on the request and response. The fact that the request is proxied is determined by the presence of the “Via” request header field. The directive accepts multiple parameters:

off
disables compression for all proxied requests, ignoring other parameters;
expired
enables compression if a response header includes the “Expires” field with a value that disables caching;
no-cache
enables compression if a response header includes the “Cache-Control” field with the “no-cache” parameter;
no-store
enables compression if a response header includes the “Cache-Control” field with the “no-store” parameter;
private
enables compression if a response header includes the “Cache-Control” field with the “private” parameter;
no_last_modified
enables compression if a response header does not include the “Last-Modified” field;
no_etag
enables compression if a response header does not include the “ETag” field;
auth
enables compression if a request header includes the “Authorization” field;
any
enables compression for all proxied requests.
", "module": "ngx_http_gzip_module", "link": "http/ngx_http_gzip_module.html#gzip_proxied", "name": "gzip_proxied" }, { "table": "
Syntax:gzip_types mime-type ...;
Default:
gzip_types text/html;
Context:http, server, location
", "doc": "

Enables gzipping of responses for the specified MIME types in addition to “text/html”. The special value “*” matches any MIME type (0.8.29). Responses with the “text/html” type are always compressed.

", "module": "ngx_http_gzip_module", "link": "http/ngx_http_gzip_module.html#gzip_types", "name": "gzip_types" }, { "table": "
Syntax:gzip_vary on | off;
Default:
gzip_vary off;
Context:http, server, location
", "doc": "

Enables or disables inserting the “Vary: Accept-Encoding” response header field if the directives gzip, gzip_static, or gunzip are active.

", "module": "ngx_http_gzip_module", "link": "http/ngx_http_gzip_module.html#gzip_vary", "name": "gzip_vary" }, { "table": "
Syntax:gzip_static on | off | always;
Default:
gzip_static off;
Context:http, server, location
", "doc": "

Enables (“on”) or disables (“off”) checking the existence of precompressed files. The following directives are also taken into account: gzip_http_version, gzip_proxied, gzip_disable, and gzip_vary.

With the “always” value (1.3.6), gzipped file is used in all cases, without checking if the client supports it. It is useful if there are no uncompressed files on the disk anyway or the ngx_http_gunzip_module is used.

The files can be compressed using the gzip command, or any other compatible one. It is recommended that the modification date and time of original and compressed files be the same.

", "module": "ngx_http_gzip_static_module", "link": "http/ngx_http_gzip_static_module.html#gzip_static", "name": "gzip_static" }, { "table": "
Syntax:add_header name value [always];
Default:—
Context:http, server, location, if in location
", "doc": "

Adds the specified field to a response header provided that the response code equals 200, 201 (1.3.10), 204, 206, 301, 302, 303, 304, 307 (1.1.16, 1.0.13), or 308 (1.13.0). The value can contain variables.

There could be several add_header directives. These directives are inherited from the previous level if and only if there are no add_header directives defined on the current level.

If the always parameter is specified (1.7.5), the header field will be added regardless of the response code.

", "module": "ngx_http_headers_module", "link": "http/ngx_http_headers_module.html#add_header", "name": "add_header" }, { "table": "
Syntax:add_trailer name value [always];
Default:—
Context:http, server, location, if in location

This directive appeared in version 1.13.2.

", "doc": "

Adds the specified field to the end of a response provided that the response code equals 200, 201, 206, 301, 302, 303, 307, or 308. The value can contain variables.

There could be several add_trailer directives. These directives are inherited from the previous level if and only if there are no add_trailer directives defined on the current level.

If the always parameter is specified the specified field will be added regardless of the response code.

", "module": "ngx_http_headers_module", "link": "http/ngx_http_headers_module.html#add_trailer", "name": "add_trailer" }, { "table": "
Syntax:expires [modified] time;
expires epoch | max | off;
Default:
expires off;
Context:http, server, location, if in location
", "doc": "

Enables or disables adding or modifying the “Expires” and “Cache-Control” response header fields provided that the response code equals 200, 201 (1.3.10), 204, 206, 301, 302, 303, 304, 307 (1.1.16, 1.0.13), or 308 (1.13.0). The parameter can be a positive or negative time.

The time in the “Expires” field is computed as a sum of the current time and time specified in the directive. If the modified parameter is used (0.7.0, 0.6.32) then the time is computed as a sum of the file’s modification time and the time specified in the directive.

In addition, it is possible to specify a time of day using the “@” prefix (0.7.9, 0.6.34):

\nexpires @15h30m;\n

The epoch parameter corresponds to the absolute time “Thu, 01 Jan 1970 00:00:01 GMT”. The contents of the “Cache-Control” field depends on the sign of the specified time:

", "module": "ngx_http_headers_module", "link": "http/ngx_http_headers_module.html#expires", "name": "expires" }, { "table": "
Syntax:hls;
Default:—
Context:location
", "doc": "

Turns on HLS streaming in the surrounding location.

", "module": "ngx_http_hls_module", "link": "http/ngx_http_hls_module.html#hls", "name": "hls" }, { "table": "
Syntax:hls_buffers number size;
Default:
hls_buffers 8 2m;
Context:http, server, location
", "doc": "

Sets the maximum number and size of buffers that are used for reading and writing data frames.

", "module": "ngx_http_hls_module", "link": "http/ngx_http_hls_module.html#hls_buffers", "name": "hls_buffers" }, { "table": "
Syntax:hls_forward_args on | off;
Default:
hls_forward_args off;
Context:http, server, location

This directive appeared in version 1.5.12.

", "doc": "

Adds arguments from a playlist request to URIs of fragments. This may be useful for performing client authorization at the moment of requesting a fragment, or when protecting an HLS stream with the ngx_http_secure_link_module module.

For example, if a client requests a playlist http://example.com/hls/test.mp4.m3u8?a=1&b=2, the arguments a=1 and b=2 will be added to URIs of fragments after the arguments start and end:

\n#EXTM3U\n#EXT-X-VERSION:3\n#EXT-X-TARGETDURATION:15\n#EXT-X-PLAYLIST-TYPE:VOD\n\n#EXTINF:9.333,\ntest.mp4.ts?start=0.000&end=9.333&a=1&b=2\n#EXTINF:7.167,\ntest.mp4.ts?start=9.333&end=16.500&a=1&b=2\n#EXTINF:5.416,\ntest.mp4.ts?start=16.500&end=21.916&a=1&b=2\n#EXTINF:5.500,\ntest.mp4.ts?start=21.916&end=27.416&a=1&b=2\n#EXTINF:15.167,\ntest.mp4.ts?start=27.416&end=42.583&a=1&b=2\n#EXTINF:9.626,\ntest.mp4.ts?start=42.583&end=52.209&a=1&b=2\n\n#EXT-X-ENDLIST\n

If an HLS stream is protected with the ngx_http_secure_link_module module, $uri should not be used in the secure_link_md5 expression because this will cause errors when requesting the fragments. Base URI should be used instead of $uri ($hls_uri in the example):

\nhttp {\n    ...\n\n    map $uri $hls_uri {\n        ~^(?<base_uri>.*).m3u8$ $base_uri;\n        ~^(?<base_uri>.*).ts$   $base_uri;\n        default                 $uri;\n    }\n\n    server {\n        ...\n\n        location /hls {\n            hls;\n            hls_forward_args on;\n\n            alias /var/videos;\n\n            secure_link $arg_md5,$arg_expires;\n            secure_link_md5 "$secure_link_expires$hls_uri$remote_addr secret";\n\n            if ($secure_link = "") {\n                return 403;\n            }\n\n            if ($secure_link = "0") {\n                return 410;\n            }\n        }\n    }\n}\n
", "module": "ngx_http_hls_module", "link": "http/ngx_http_hls_module.html#hls_forward_args", "name": "hls_forward_args" }, { "table": "
Syntax:hls_fragment time;
Default:
hls_fragment 5s;
Context:http, server, location
", "doc": "

Defines the default fragment length for playlist URIs requested without the “len” argument.

", "module": "ngx_http_hls_module", "link": "http/ngx_http_hls_module.html#hls_fragment", "name": "hls_fragment" }, { "table": "
Syntax:hls_mp4_buffer_size size;
Default:
hls_mp4_buffer_size 512k;
Context:http, server, location
", "doc": "

Sets the initial size of the buffer used for processing MP4 and MOV files.

", "module": "ngx_http_hls_module", "link": "http/ngx_http_hls_module.html#hls_mp4_buffer_size", "name": "hls_mp4_buffer_size" }, { "table": "
Syntax:hls_mp4_max_buffer_size size;
Default:
hls_mp4_max_buffer_size 10m;
Context:http, server, location
", "doc": "

During metadata processing, a larger buffer may become necessary. Its size cannot exceed the specified size, or else nginx will return the server error 500 (Internal Server Error), and log the following message:

\n"/some/movie/file.mp4" mp4 moov atom is too large:\n12583268, you may want to increase hls_mp4_max_buffer_size\n
", "module": "ngx_http_hls_module", "link": "http/ngx_http_hls_module.html#hls_mp4_max_buffer_size", "name": "hls_mp4_max_buffer_size" }, { "table": "
Syntax:image_filter off;
image_filter test;
image_filter size;
image_filter rotate 90 | 180 | 270;
image_filter resize width height;
image_filter crop width height;
Default:
image_filter off;
Context:location
", "doc": "

Sets the type of transformation to perform on images:

off
turns off module processing in a surrounding location.
test
ensures that responses are images in either JPEG, GIF, PNG, or WebP format. Otherwise, the 415 (Unsupported Media Type) error is returned.
size
outputs information about images in a JSON format, e.g.:
\n{ "img" : { "width": 100, "height": 100, "type": "gif" } }\n
In case of an error, the output is as follows:
\n{}\n
rotate 90|180|270
rotates images counter-clockwise by the specified number of degrees. Parameter value can contain variables. This mode can be used either alone or along with the resize and crop transformations.
resize width height
proportionally reduces an image to the specified sizes. To reduce by only one dimension, another dimension can be specified as “-”. In case of an error, the server will return code 415 (Unsupported Media Type). Parameter values can contain variables. When used along with the rotate parameter, the rotation happens after reduction.
crop width height
proportionally reduces an image to the larger side size and crops extraneous edges by another side. To reduce by only one dimension, another dimension can be specified as “-”. In case of an error, the server will return code 415 (Unsupported Media Type). Parameter values can contain variables. When used along with the rotate parameter, the rotation happens before reduction.
", "module": "ngx_http_image_filter_module", "link": "http/ngx_http_image_filter_module.html#image_filter", "name": "image_filter" }, { "table": "
Syntax:image_filter_buffer size;
Default:
image_filter_buffer 1M;
Context:http, server, location
", "doc": "

Sets the maximum size of the buffer used for reading images. When the size is exceeded the server returns error 415 (Unsupported Media Type).

", "module": "ngx_http_image_filter_module", "link": "http/ngx_http_image_filter_module.html#image_filter_buffer", "name": "image_filter_buffer" }, { "table": "
Syntax:image_filter_interlace on | off;
Default:
image_filter_interlace off;
Context:http, server, location

This directive appeared in version 1.3.15.

", "doc": "

If enabled, final images will be interlaced. For JPEG, final images will be in “progressive JPEG” format.

", "module": "ngx_http_image_filter_module", "link": "http/ngx_http_image_filter_module.html#image_filter_interlace", "name": "image_filter_interlace" }, { "table": "
Syntax:image_filter_jpeg_quality quality;
Default:
image_filter_jpeg_quality 75;
Context:http, server, location
", "doc": "

Sets the desired quality of the transformed JPEG images. Acceptable values are in the range from 1 to 100. Lesser values usually imply both lower image quality and less data to transfer. The maximum recommended value is 95. Parameter value can contain variables.

", "module": "ngx_http_image_filter_module", "link": "http/ngx_http_image_filter_module.html#image_filter_jpeg_quality", "name": "image_filter_jpeg_quality" }, { "table": "
Syntax:image_filter_sharpen percent;
Default:
image_filter_sharpen 0;
Context:http, server, location
", "doc": "

Increases sharpness of the final image. The sharpness percentage can exceed 100. The zero value disables sharpening. Parameter value can contain variables.

", "module": "ngx_http_image_filter_module", "link": "http/ngx_http_image_filter_module.html#image_filter_sharpen", "name": "image_filter_sharpen" }, { "table": "
Syntax:image_filter_transparency on|off;
Default:
image_filter_transparency on;
Context:http, server, location
", "doc": "

Defines whether transparency should be preserved when transforming GIF images or PNG images with colors specified by a palette. The loss of transparency results in images of a better quality. The alpha channel transparency in PNG is always preserved.

", "module": "ngx_http_image_filter_module", "link": "http/ngx_http_image_filter_module.html#image_filter_transparency", "name": "image_filter_transparency" }, { "table": "
Syntax:image_filter_webp_quality quality;
Default:
image_filter_webp_quality 80;
Context:http, server, location

This directive appeared in version 1.11.6.

", "doc": "

Sets the desired quality of the transformed WebP images. Acceptable values are in the range from 1 to 100. Lesser values usually imply both lower image quality and less data to transfer. Parameter value can contain variables.

", "module": "ngx_http_image_filter_module", "link": "http/ngx_http_image_filter_module.html#image_filter_webp_quality", "name": "image_filter_webp_quality" }, { "table": "
Syntax:index file ...;
Default:
index index.html;
Context:http, server, location
", "doc": "

Defines files that will be used as an index. The file name can contain variables. Files are checked in the specified order. The last element of the list can be a file with an absolute path. Example:

\nindex index.$geo.html index.0.html /index.html;\n

It should be noted that using an index file causes an internal redirect, and the request can be processed in a different location. For example, with the following configuration:

\nlocation = / {\n    index index.html;\n}\n\nlocation / {\n    ...\n}\n

a “/” request will actually be processed in the second location as “/index.html”.

", "module": "ngx_http_index_module", "link": "http/ngx_http_index_module.html#index", "name": "index" }, { "table": "
Syntax:js_content function;
Default:—
Context:location, limit_except
", "doc": "

Sets an njs function as a location content handler.

", "module": "ngx_http_js_module", "link": "http/ngx_http_js_module.html#js_content", "name": "js_content" }, { "table": "
Syntax:js_include file;
Default:—
Context:http
", "doc": "

Specifies a file that implements location and variable handlers in njs.

", "module": "ngx_http_js_module", "link": "http/ngx_http_js_module.html#js_include", "name": "js_include" }, { "table": "
Syntax:js_set $variable function;
Default:—
Context:http
", "doc": "

Sets an njs function for the specified variable.

", "module": "ngx_http_js_module", "link": "http/ngx_http_js_module.html#js_set", "name": "js_set" }, { "table": "
Syntax:keyval key $variable zone=name;
Default:—
Context:http
", "doc": "

Creates a new $variable whose value is looked up by the key in the key-value database. Strings are matched ignoring the case. The database is stored in a shared memory zone specified by the zone parameter.

", "module": "ngx_http_keyval_module", "link": "http/ngx_http_keyval_module.html#keyval", "name": "keyval" }, { "table": "
Syntax:keyval_zone zone=name:size [state=file];
Default:—
Context:http
", "doc": "

Sets the name and size of the shared memory zone that keeps the key-value database. Key-value pairs are managed by the API.

The optional state parameter specifies a file that keeps the current state of the key-value database in the JSON format and makes it persistent across nginx restarts.

", "module": "ngx_http_keyval_module", "link": "http/ngx_http_keyval_module.html#keyval_zone", "name": "keyval_zone" }, { "table": "
Syntax:limit_conn zone number;
Default:—
Context:http, server, location
", "doc": "

Sets the shared memory zone and the maximum allowed number of connections for a given key value. When this limit is exceeded, the server will return the error in reply to a request. For example, the directives

\nlimit_conn_zone $binary_remote_addr zone=addr:10m;\n\nserver {\n    location /download/ {\n        limit_conn addr 1;\n    }\n

allow only one connection per an IP address at a time.

In HTTP/2 and SPDY, each concurrent request is considered a separate connection.

There could be several limit_conn directives. For example, the following configuration will limit the number of connections to the server per a client IP and, at the same time, the total number of connections to the virtual server:

\nlimit_conn_zone $binary_remote_addr zone=perip:10m;\nlimit_conn_zone $server_name zone=perserver:10m;\n\nserver {\n    ...\n    limit_conn perip 10;\n    limit_conn perserver 100;\n}\n

These directives are inherited from the previous level if and only if there are no limit_conn directives on the current level.

", "module": "ngx_http_limit_conn_module", "link": "http/ngx_http_limit_conn_module.html#limit_conn", "name": "limit_conn" }, { "table": "
Syntax:limit_conn_log_level info | notice | warn | error;
Default:
limit_conn_log_level error;
Context:http, server, location

This directive appeared in version 0.8.18.

", "doc": "

Sets the desired logging level for cases when the server limits the number of connections.

", "module": "ngx_http_limit_conn_module", "link": "http/ngx_http_limit_conn_module.html#limit_conn_log_level", "name": "limit_conn_log_level" }, { "table": "
Syntax:limit_conn_status code;
Default:
limit_conn_status 503;
Context:http, server, location

This directive appeared in version 1.3.15.

", "doc": "

Sets the status code to return in response to rejected requests.

", "module": "ngx_http_limit_conn_module", "link": "http/ngx_http_limit_conn_module.html#limit_conn_status", "name": "limit_conn_status" }, { "table": "
Syntax:limit_conn_zone key zone=name:size;
Default:—
Context:http
", "doc": "

Sets parameters for a shared memory zone that will keep states for various keys. In particular, the state includes the current number of connections. The key can contain text, variables, and their combination. Requests with an empty key value are not accounted.

Prior to version 1.7.6, a key could contain exactly one variable.

Usage example:

\nlimit_conn_zone $binary_remote_addr zone=addr:10m;\n

Here, a client IP address serves as a key. Note that instead of $remote_addr, the $binary_remote_addr variable is used here. The $remote_addr variable’s size can vary from 7 to 15 bytes. The stored state occupies either 32 or 64 bytes of memory on 32-bit platforms and always 64 bytes on 64-bit platforms. The $binary_remote_addr variable’s size is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses. The stored state always occupies 32 or 64 bytes on 32-bit platforms and 64 bytes on 64-bit platforms. One megabyte zone can keep about 32 thousand 32-byte states or about 16 thousand 64-byte states. If the zone storage is exhausted, the server will return the error to all further requests.

", "module": "ngx_http_limit_conn_module", "link": "http/ngx_http_limit_conn_module.html#limit_conn_zone", "name": "limit_conn_zone" }, { "table": "
Syntax:limit_zone name $variable size;
Default:—
Context:http
", "doc": "

This directive was made obsolete in version 1.1.8 and was removed in version 1.7.6. An equivalent limit_conn_zone directive with a changed syntax should be used instead:

limit_conn_zone $variable zone=name:size;
", "module": "ngx_http_limit_conn_module", "link": "http/ngx_http_limit_conn_module.html#limit_zone", "name": "limit_zone" }, { "table": "
Syntax:limit_req zone=name [burst=number] [nodelay];
Default:—
Context:http, server, location
", "doc": "

Sets the shared memory zone and the maximum burst size of requests. If the requests rate exceeds the rate configured for a zone, their processing is delayed such that requests are processed at a defined rate. Excessive requests are delayed until their number exceeds the maximum burst size in which case the request is terminated with an error. By default, the maximum burst size is equal to zero. For example, the directives

\nlimit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;\n\nserver {\n    location /search/ {\n        limit_req zone=one burst=5;\n    }\n

allow not more than 1 request per second at an average, with bursts not exceeding 5 requests.

If delaying of excessive requests while requests are being limited is not desired, the parameter nodelay should be used:

\nlimit_req zone=one burst=5 nodelay;\n

There could be several limit_req directives. For example, the following configuration will limit the processing rate of requests coming from a single IP address and, at the same time, the request processing rate by the virtual server:

\nlimit_req_zone $binary_remote_addr zone=perip:10m rate=1r/s;\nlimit_req_zone $server_name zone=perserver:10m rate=10r/s;\n\nserver {\n    ...\n    limit_req zone=perip burst=5 nodelay;\n    limit_req zone=perserver burst=10;\n}\n

These directives are inherited from the previous level if and only if there are no limit_req directives on the current level.

", "module": "ngx_http_limit_req_module", "link": "http/ngx_http_limit_req_module.html#limit_req", "name": "limit_req" }, { "table": "
Syntax:limit_req_log_level info | notice | warn | error;
Default:
limit_req_log_level error;
Context:http, server, location

This directive appeared in version 0.8.18.

", "doc": "

Sets the desired logging level for cases when the server refuses to process requests due to rate exceeding, or delays request processing. Logging level for delays is one point less than for refusals; for example, if “limit_req_log_level notice” is specified, delays are logged with the info level.

", "module": "ngx_http_limit_req_module", "link": "http/ngx_http_limit_req_module.html#limit_req_log_level", "name": "limit_req_log_level" }, { "table": "
Syntax:limit_req_status code;
Default:
limit_req_status 503;
Context:http, server, location

This directive appeared in version 1.3.15.

", "doc": "

Sets the status code to return in response to rejected requests.

", "module": "ngx_http_limit_req_module", "link": "http/ngx_http_limit_req_module.html#limit_req_status", "name": "limit_req_status" }, { "table": "
Syntax:limit_req_zone key zone=name:size rate=rate;
Default:—
Context:http
", "doc": "

Sets parameters for a shared memory zone that will keep states for various keys. In particular, the state stores the current number of excessive requests. The key can contain text, variables, and their combination. Requests with an empty key value are not accounted.

Prior to version 1.7.6, a key could contain exactly one variable.

Usage example:

\nlimit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;\n

Here, the states are kept in a 10 megabyte zone “one”, and an average request processing rate for this zone cannot exceed 1 request per second.

A client IP address serves as a key. Note that instead of $remote_addr, the $binary_remote_addr variable is used here. The $binary_remote_addr variable’s size is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses. The stored state always occupies 64 bytes on 32-bit platforms and 128 bytes on 64-bit platforms. One megabyte zone can keep about 16 thousand 64-byte states or about 8 thousand 128-byte states.

If the zone storage is exhausted, the least recently used state is removed. Even if after that a new state cannot be created, the request is terminated with an error.

The rate is specified in requests per second (r/s). If a rate of less than one request per second is desired, it is specified in request per minute (r/m). For example, half-request per second is 30r/m.

", "module": "ngx_http_limit_req_module", "link": "http/ngx_http_limit_req_module.html#limit_req_zone", "name": "limit_req_zone" }, { "table": "
Syntax:access_log path [format [buffer=size] [gzip[=level]] [flush=time] [if=condition]];
access_log off;
Default:
access_log logs/access.log combined;
Context:http, server, location, if in location, limit_except
", "doc": "

Sets the path, format, and configuration for a buffered log write. Several logs can be specified on the same level. Logging to syslog can be configured by specifying the “syslog:” prefix in the first parameter. The special value off cancels all access_log directives on the current level. If the format is not specified then the predefined “combined” format is used.

If either the buffer or gzip (1.3.10, 1.2.7) parameter is used, writes to log will be buffered.

The buffer size must not exceed the size of an atomic write to a disk file. For FreeBSD this size is unlimited.

When buffering is enabled, the data will be written to the file:

", "module": "ngx_http_log_module", "link": "http/ngx_http_log_module.html#access_log", "name": "access_log" }, { "table": "
Syntax:log_format name [escape=default|json|none] string ...;
Default:
log_format combined "...";
Context:http
", "doc": "

Specifies log format.

", "module": "ngx_http_log_module", "link": "http/ngx_http_log_module.html#log_format", "name": "log_format" }, { "table": "
Syntax:open_log_file_cache max=N [inactive=time] [min_uses=N] [valid=time];
open_log_file_cache off;
Default:
open_log_file_cache off;
Context:http, server, location
", "doc": "

Defines a cache that stores the file descriptors of frequently used logs whose names contain variables. The directive has the following parameters:

max
sets the maximum number of descriptors in a cache; if the cache becomes full the least recently used (LRU) descriptors are closed
inactive
sets the time after which the cached descriptor is closed if there were no access during this time; by default, 10 seconds
min_uses
sets the minimum number of file uses during the time defined by the inactive parameter to let the descriptor stay open in a cache; by default, 1
valid
sets the time after which it should be checked that the file still exists with the same name; by default, 60 seconds
off
disables caching

Usage example:

\nopen_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;\n
", "module": "ngx_http_log_module", "link": "http/ngx_http_log_module.html#open_log_file_cache", "name": "open_log_file_cache" }, { "table": "
Syntax:map string $variable { ... }
Default:—
Context:http
", "doc": "

Creates a new variable whose value depends on values of one or more of the source variables specified in the first parameter.

Before version 0.9.0 only a single variable could be specified in the first parameter.
Since variables are evaluated only when they are used, the mere declaration even of a large number of “map” variables does not add any extra costs to request processing.

Parameters inside the map block specify a mapping between source and resulting values.

Source values are specified as strings or regular expressions (0.9.6).

Strings are matched ignoring the case.

A regular expression should either start from the “~” symbol for a case-sensitive matching, or from the “~*” symbols (1.0.4) for case-insensitive matching. A regular expression can contain named and positional captures that can later be used in other directives along with the resulting variable.

If a source value matches one of the names of special parameters described below, it should be prefixed with the “\\” symbol.

The resulting value can contain text, variable (0.9.0), and their combination (1.11.0).

The following special parameters are also supported:

default value
sets the resulting value if the source value matches none of the specified variants. When default is not specified, the default resulting value will be an empty string.
hostnames
indicates that source values can be hostnames with a prefix or suffix mask:
\n*.example.com 1;\nexample.*     1;\n
The following two records
\nexample.com   1;\n*.example.com 1;\n
can be combined:
\n.example.com  1;\n
This parameter should be specified before the list of values.
include file
includes a file with values. There can be several inclusions.
volatile
indicates that the variable is not cacheable (1.11.7).

If the source value matches more than one of the specified variants, e.g. both a mask and a regular expression match, the first matching variant will be chosen, in the following order of priority:

", "module": "ngx_http_map_module", "link": "http/ngx_http_map_module.html#map", "name": "map" }, { "table": "
Syntax:map_hash_bucket_size size;
Default:
map_hash_bucket_size 32|64|128;
Context:http
", "doc": "

Sets the bucket size for the map variables hash tables. Default value depends on the processor’s cache line size. The details of setting up hash tables are provided in a separate document.

", "module": "ngx_http_map_module", "link": "http/ngx_http_map_module.html#map_hash_bucket_size", "name": "map_hash_bucket_size" }, { "table": "
Syntax:map_hash_max_size size;
Default:
map_hash_max_size 2048;
Context:http
", "doc": "

Sets the maximum size of the map variables hash tables. The details of setting up hash tables are provided in a separate document.

", "module": "ngx_http_map_module", "link": "http/ngx_http_map_module.html#map_hash_max_size", "name": "map_hash_max_size" }, { "table": "
Syntax:memcached_bind address [transparent] | off;
Default:—
Context:http, server, location

This directive appeared in version 0.8.22.

", "doc": "

Makes outgoing connections to a memcached 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 memcached_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address and port.

", "module": "ngx_http_memcached_module", "link": "http/ngx_http_memcached_module.html#memcached_bind", "name": "memcached_bind" }, { "table": "
Syntax:memcached_buffer_size size;
Default:
memcached_buffer_size 4k|8k;
Context:http, server, location
", "doc": "

Sets the size of the buffer used for reading the response received from the memcached server. The response is passed to the client synchronously, as soon as it is received.

", "module": "ngx_http_memcached_module", "link": "http/ngx_http_memcached_module.html#memcached_buffer_size", "name": "memcached_buffer_size" }, { "table": "
Syntax:memcached_connect_timeout time;
Default:
memcached_connect_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_memcached_module", "link": "http/ngx_http_memcached_module.html#memcached_connect_timeout", "name": "memcached_connect_timeout" }, { "table": "
Syntax:memcached_force_ranges on | off;
Default:
memcached_force_ranges off;
Context:http, server, location

This directive appeared in version 1.7.7.

", "doc": "

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

", "module": "ngx_http_memcached_module", "link": "http/ngx_http_memcached_module.html#memcached_force_ranges", "name": "memcached_force_ranges" }, { "table": "
Syntax:memcached_gzip_flag flag;
Default:—
Context:http, server, location

This directive appeared in version 1.3.6.

", "doc": "

Enables the test for the flag presence in the memcached server response and sets the “Content-Encoding” response header field to “gzip” if the flag is set.

", "module": "ngx_http_memcached_module", "link": "http/ngx_http_memcached_module.html#memcached_gzip_flag", "name": "memcached_gzip_flag" }, { "table": "
Syntax:memcached_next_upstream error | timeout | invalid_response | not_found | off ...;
Default:
memcached_next_upstream error timeout;
Context:http, server, location
", "doc": "

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_response
a server returned an empty or invalid response;
not_found
a response was not found on the server;
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_response are always considered unsuccessful attempts, even if they are not specified in the directive. The case of not_found is never considered an unsuccessful attempt.

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

", "module": "ngx_http_memcached_module", "link": "http/ngx_http_memcached_module.html#memcached_next_upstream", "name": "memcached_next_upstream" }, { "table": "
Syntax:memcached_next_upstream_timeout time;
Default:
memcached_next_upstream_timeout 0;
Context:http, server, location

This directive appeared in version 1.7.5.

", "doc": "

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

", "module": "ngx_http_memcached_module", "link": "http/ngx_http_memcached_module.html#memcached_next_upstream_timeout", "name": "memcached_next_upstream_timeout" }, { "table": "
Syntax:memcached_next_upstream_tries number;
Default:
memcached_next_upstream_tries 0;
Context:http, server, location

This directive appeared in version 1.7.5.

", "doc": "

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

", "module": "ngx_http_memcached_module", "link": "http/ngx_http_memcached_module.html#memcached_next_upstream_tries", "name": "memcached_next_upstream_tries" }, { "table": "
Syntax:memcached_pass address;
Default:—
Context:location, if in location
", "doc": "

Sets the memcached server address. The address can be specified as a domain name or IP address, and a port:

\nmemcached_pass localhost:11211;\n

or as a UNIX-domain socket path:

\nmemcached_pass unix:/tmp/memcached.socket;\n

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.

", "module": "ngx_http_memcached_module", "link": "http/ngx_http_memcached_module.html#memcached_pass", "name": "memcached_pass" }, { "table": "
Syntax:memcached_read_timeout time;
Default:
memcached_read_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_memcached_module", "link": "http/ngx_http_memcached_module.html#memcached_read_timeout", "name": "memcached_read_timeout" }, { "table": "
Syntax:memcached_send_timeout time;
Default:
memcached_send_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_memcached_module", "link": "http/ngx_http_memcached_module.html#memcached_send_timeout", "name": "memcached_send_timeout" }, { "table": "
Syntax:mirror uri | off;
Default:
mirror off;
Context:http, server, location
", "doc": "

Sets the URI to which an original request will be mirrored. Several mirrors can be specified on the same level.

", "module": "ngx_http_mirror_module", "link": "http/ngx_http_mirror_module.html#mirror", "name": "mirror" }, { "table": "
Syntax:mirror_request_body on | off;
Default:
mirror_request_body on;
Context:http, server, location
", "doc": "

Indicates whether the client request body is mirrored. When enabled, the client request body will be read prior to creating mirror subrequests. In this case, unbuffered client request body proxying set by the proxy_request_buffering, fastcgi_request_buffering, scgi_request_buffering, and uwsgi_request_buffering directives will be disabled.

\nlocation / {\n    mirror /mirror;\n    mirror_request_body off;\n    proxy_pass http://backend;\n}\n\nlocation /mirror {\n    internal;\n    proxy_pass http://log_backend;\n    proxy_pass_request_body off;\n    proxy_set_header Content-Length "";\n    proxy_set_header X-Original-URI $request_uri;\n}\n
", "module": "ngx_http_mirror_module", "link": "http/ngx_http_mirror_module.html#mirror_request_body", "name": "mirror_request_body" }, { "table": "
Syntax:mp4;
Default:—
Context:location
", "doc": "

Turns on module processing in a surrounding location.

", "module": "ngx_http_mp4_module", "link": "http/ngx_http_mp4_module.html#mp4", "name": "mp4" }, { "table": "
Syntax:mp4_buffer_size size;
Default:
mp4_buffer_size 512K;
Context:http, server, location
", "doc": "

Sets the initial size of the buffer used for processing MP4 files.

", "module": "ngx_http_mp4_module", "link": "http/ngx_http_mp4_module.html#mp4_buffer_size", "name": "mp4_buffer_size" }, { "table": "
Syntax:mp4_max_buffer_size size;
Default:
mp4_max_buffer_size 10M;
Context:http, server, location
", "doc": "

During metadata processing, a larger buffer may become necessary. Its size cannot exceed the specified size, or else nginx will return the 500 (Internal Server Error) server error, and log the following message:

\n"/some/movie/file.mp4" mp4 moov atom is too large:\n12583268, you may want to increase mp4_max_buffer_size\n
", "module": "ngx_http_mp4_module", "link": "http/ngx_http_mp4_module.html#mp4_max_buffer_size", "name": "mp4_max_buffer_size" }, { "table": "
Syntax:mp4_limit_rate on | off | factor;
Default:
mp4_limit_rate off;
Context:http, server, location
", "doc": "

Limits the rate of response transmission to a client. The rate is limited based on the average bitrate of the MP4 file served. To calculate the rate, the bitrate is multiplied by the specified factor. The special value “on” corresponds to the factor of 1.1. The special value “off” disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit.

This directive is available as part of our commercial subscription.
", "module": "ngx_http_mp4_module", "link": "http/ngx_http_mp4_module.html#mp4_limit_rate", "name": "mp4_limit_rate" }, { "table": "
Syntax:mp4_limit_rate_after time;
Default:
mp4_limit_rate_after 60s;
Context:http, server, location
", "doc": "

Sets the initial amount of media data (measured in playback time) after which the further transmission of the response to a client will be rate limited.

This directive is available as part of our commercial subscription.
", "module": "ngx_http_mp4_module", "link": "http/ngx_http_mp4_module.html#mp4_limit_rate_after", "name": "mp4_limit_rate_after" }, { "table": "
Syntax:perl module::function|'sub { ... }';
Default:—
Context:location, limit_except
", "doc": "

Sets a Perl handler for the given location.

", "module": "ngx_http_perl_module", "link": "http/ngx_http_perl_module.html#perl", "name": "perl" }, { "table": "
Syntax:perl_modules path;
Default:—
Context:http
", "doc": "

Sets an additional path for Perl modules.

", "module": "ngx_http_perl_module", "link": "http/ngx_http_perl_module.html#perl_modules", "name": "perl_modules" }, { "table": "
Syntax:perl_require module;
Default:—
Context:http
", "doc": "

Defines the name of a module that will be loaded during each reconfiguration. Several perl_require directives can be present.

", "module": "ngx_http_perl_module", "link": "http/ngx_http_perl_module.html#perl_require", "name": "perl_require" }, { "table": "
Syntax:perl_set $variable module::function|'sub { ... }';
Default:—
Context:http
", "doc": "

Installs a Perl handler for the specified variable.

", "module": "ngx_http_perl_module", "link": "http/ngx_http_perl_module.html#perl_set", "name": "perl_set" }, { "table": "
Syntax:proxy_bind address [transparent] | off;
Default:—
Context:http, server, location

This directive appeared in version 0.8.22.

", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_bind", "name": "proxy_bind" }, { "table": "
Syntax:proxy_buffer_size size;
Default:
proxy_buffer_size 4k|8k;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_buffer_size", "name": "proxy_buffer_size" }, { "table": "
Syntax:proxy_buffering on | off;
Default:
proxy_buffering on;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_buffering", "name": "proxy_buffering" }, { "table": "
Syntax:proxy_buffers number size;
Default:
proxy_buffers 8 4k|8k;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_buffers", "name": "proxy_buffers" }, { "table": "
Syntax:proxy_busy_buffers_size size;
Default:
proxy_busy_buffers_size 8k|16k;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_busy_buffers_size", "name": "proxy_busy_buffers_size" }, { "table": "
Syntax:proxy_cache zone | off;
Default:
proxy_cache off;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cache", "name": "proxy_cache" }, { "table": "
Syntax:proxy_cache_background_update on | off;
Default:
proxy_cache_background_update off;
Context:http, server, location

This directive appeared in version 1.11.10.

", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cache_background_update", "name": "proxy_cache_background_update" }, { "table": "
Syntax:proxy_cache_bypass string ...;
Default:—
Context:http, server, location
", "doc": "

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:

\nproxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;\nproxy_cache_bypass $http_pragma    $http_authorization;\n

Can be used along with the proxy_no_cache directive.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cache_bypass", "name": "proxy_cache_bypass" }, { "table": "
Syntax:proxy_cache_convert_head on | off;
Default:
proxy_cache_convert_head on;
Context:http, server, location

This directive appeared in version 1.9.7.

", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cache_convert_head", "name": "proxy_cache_convert_head" }, { "table": "
Syntax:proxy_cache_key string;
Default:
proxy_cache_key $scheme$proxy_host$request_uri;
Context:http, server, location
", "doc": "

Defines a key for caching, for example

\nproxy_cache_key "$host$request_uri $cookie_user";\n

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

\nproxy_cache_key $scheme$proxy_host$uri$is_args$args;\n
", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cache_key", "name": "proxy_cache_key" }, { "table": "
Syntax:proxy_cache_lock on | off;
Default:
proxy_cache_lock off;
Context:http, server, location

This directive appeared in version 1.1.12.

", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cache_lock", "name": "proxy_cache_lock" }, { "table": "
Syntax:proxy_cache_lock_age time;
Default:
proxy_cache_lock_age 5s;
Context:http, server, location

This directive appeared in version 1.7.8.

", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cache_lock_age", "name": "proxy_cache_lock_age" }, { "table": "
Syntax:proxy_cache_lock_timeout time;
Default:
proxy_cache_lock_timeout 5s;
Context:http, server, location

This directive appeared in version 1.1.12.

", "doc": "

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.

Before 1.7.8, the response could be cached.
", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cache_lock_timeout", "name": "proxy_cache_lock_timeout" }, { "table": "
Syntax:proxy_cache_max_range_offset number;
Default:—
Context:http, server, location

This directive appeared in version 1.11.6.

", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cache_max_range_offset", "name": "proxy_cache_max_range_offset" }, { "table": "
Syntax:proxy_cache_methods GET | HEAD | POST ...;
Default:
proxy_cache_methods GET HEAD;
Context:http, server, location

This directive appeared in version 0.7.59.

", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cache_methods", "name": "proxy_cache_methods" }, { "table": "
Syntax:proxy_cache_min_uses number;
Default:
proxy_cache_min_uses 1;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cache_min_uses", "name": "proxy_cache_min_uses" }, { "table": "
Syntax:proxy_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time];
Default:—
Context:http
", "doc": "

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

\nproxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;\n

file names in a cache will look like this:

\n/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c\n

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.

As part of commercial subscription, the shared memory zone also stores extended cache information, thus, it is required to specify a larger zone size for the same number of keys. For example, one megabyte zone can store about 4 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. When this size is exceeded, 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.
In versions 1.7.3, 1.7.7, and 1.11.10 cache header format has been changed. Previously cached responses will be considered invalid after upgrading to a newer nginx version.
", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cache_path", "name": "proxy_cache_path" }, { "table": "
Syntax:proxy_cache_purge string ...;
Default:—
Context:http, server, location

This directive appeared in version 1.5.7.

", "doc": "

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.

Example configuration:

\nproxy_cache_path /data/nginx/cache keys_zone=cache_zone:10m;\n\nmap $request_method $purge_method {\n    PURGE   1;\n    default 0;\n}\n\nserver {\n    ...\n    location / {\n        proxy_pass http://backend;\n        proxy_cache cache_zone;\n        proxy_cache_key $uri;\n        proxy_cache_purge $purge_method;\n    }\n}\n
This functionality is available as part of our commercial subscription.
", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cache_purge", "name": "proxy_cache_purge" }, { "table": "
Syntax:proxy_cache_revalidate on | off;
Default:
proxy_cache_revalidate off;
Context:http, server, location

This directive appeared in version 1.5.7.

", "doc": "

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

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cache_revalidate", "name": "proxy_cache_revalidate" }, { "table": "
Syntax:proxy_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | off ...;
Default:
proxy_cache_use_stale off;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cache_use_stale", "name": "proxy_cache_use_stale" }, { "table": "
Syntax:proxy_cache_valid [code ...] time;
Default:—
Context:http, server, location
", "doc": "

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

\nproxy_cache_valid 200 302 10m;\nproxy_cache_valid 404      1m;\n

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

\nproxy_cache_valid 5m;\n

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

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

\nproxy_cache_valid 200 302 10m;\nproxy_cache_valid 301      1h;\nproxy_cache_valid any      1m;\n

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

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cache_valid", "name": "proxy_cache_valid" }, { "table": "
Syntax:proxy_connect_timeout time;
Default:
proxy_connect_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_connect_timeout", "name": "proxy_connect_timeout" }, { "table": "
Syntax:proxy_cookie_domain off;
proxy_cookie_domain domain replacement;
Default:
proxy_cookie_domain off;
Context:http, server, location

This directive appeared in version 1.1.15.

", "doc": "

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

\nproxy_cookie_domain localhost example.org;\n

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:

\nproxy_cookie_domain www.$host $host;\n

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:

\nproxy_cookie_domain ~\\.(?P<sl_domain>[-0-9a-z]+\\.[a-z]+)$ $sl_domain;\n

There could be several proxy_cookie_domain directives:

\nproxy_cookie_domain localhost example.org;\nproxy_cookie_domain ~\\.([a-z]+\\.[a-z]+)$ $1;\n

The off parameter cancels the effect of all proxy_cookie_domain directives on the current level:

\nproxy_cookie_domain off;\nproxy_cookie_domain localhost example.org;\nproxy_cookie_domain www.example.org example.org;\n
", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cookie_domain", "name": "proxy_cookie_domain" }, { "table": "
Syntax:proxy_cookie_path off;
proxy_cookie_path path replacement;
Default:
proxy_cookie_path off;
Context:http, server, location

This directive appeared in version 1.1.15.

", "doc": "

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

\nproxy_cookie_path /two/ /;\n

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

The path and replacement strings can contain variables:

\nproxy_cookie_path $uri /some$uri;\n

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:

\nproxy_cookie_path ~*^/user/([^/]+) /u/$1;\n

There could be several proxy_cookie_path directives:

\nproxy_cookie_path /one/ /;\nproxy_cookie_path / /two/;\n

The off parameter cancels the effect of all proxy_cookie_path directives on the current level:

\nproxy_cookie_path off;\nproxy_cookie_path /two/ /;\nproxy_cookie_path ~*^/user/([^/]+) /u/$1;\n
", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_cookie_path", "name": "proxy_cookie_path" }, { "table": "
Syntax:proxy_force_ranges on | off;
Default:
proxy_force_ranges off;
Context:http, server, location

This directive appeared in version 1.7.7.

", "doc": "

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

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_force_ranges", "name": "proxy_force_ranges" }, { "table": "
Syntax:proxy_headers_hash_bucket_size size;
Default:
proxy_headers_hash_bucket_size 64;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_headers_hash_bucket_size", "name": "proxy_headers_hash_bucket_size" }, { "table": "
Syntax:proxy_headers_hash_max_size size;
Default:
proxy_headers_hash_max_size 512;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_headers_hash_max_size", "name": "proxy_headers_hash_max_size" }, { "table": "
Syntax:proxy_hide_header field;
Default:—
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_hide_header", "name": "proxy_hide_header" }, { "table": "
Syntax:proxy_http_version 1.0 | 1.1;
Default:
proxy_http_version 1.0;
Context:http, server, location

This directive appeared in version 1.1.4.

", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_http_version", "name": "proxy_http_version" }, { "table": "
Syntax:proxy_ignore_client_abort on | off;
Default:
proxy_ignore_client_abort off;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_ignore_client_abort", "name": "proxy_ignore_client_abort" }, { "table": "
Syntax:proxy_ignore_headers field ...;
Default:—
Context:http, server, location
", "doc": "

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:

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_ignore_headers", "name": "proxy_ignore_headers" }, { "table": "
Syntax:proxy_intercept_errors on | off;
Default:
proxy_intercept_errors off;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_intercept_errors", "name": "proxy_intercept_errors" }, { "table": "
Syntax:proxy_limit_rate rate;
Default:
proxy_limit_rate 0;
Context:http, server, location

This directive appeared in version 1.7.7.

", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_limit_rate", "name": "proxy_limit_rate" }, { "table": "
Syntax:proxy_max_temp_file_size size;
Default:
proxy_max_temp_file_size 1024m;
Context:http, server, location
", "doc": "

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.

This restriction does not apply to responses that will be cached or stored on disk.
", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_max_temp_file_size", "name": "proxy_max_temp_file_size" }, { "table": "
Syntax:proxy_method method;
Default:—
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_method", "name": "proxy_method" }, { "table": "
Syntax:proxy_next_upstream error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off ...;
Default:
proxy_next_upstream error timeout;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_next_upstream", "name": "proxy_next_upstream" }, { "table": "
Syntax:proxy_next_upstream_timeout time;
Default:
proxy_next_upstream_timeout 0;
Context:http, server, location

This directive appeared in version 1.7.5.

", "doc": "

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

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_next_upstream_timeout", "name": "proxy_next_upstream_timeout" }, { "table": "
Syntax:proxy_next_upstream_tries number;
Default:
proxy_next_upstream_tries 0;
Context:http, server, location

This directive appeared in version 1.7.5.

", "doc": "

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

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_next_upstream_tries", "name": "proxy_next_upstream_tries" }, { "table": "
Syntax:proxy_no_cache string ...;
Default:—
Context:http, server, location
", "doc": "

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:

\nproxy_no_cache $cookie_nocache $arg_nocache$arg_comment;\nproxy_no_cache $http_pragma    $http_authorization;\n

Can be used along with the proxy_cache_bypass directive.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_no_cache", "name": "proxy_no_cache" }, { "table": "
Syntax:proxy_pass URL;
Default:—
Context:location, if in location, limit_except
", "doc": "

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:

\nproxy_pass http://localhost:8000/uri/;\n

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

\nproxy_pass http://unix:/tmp/backend.socket:/uri/;\n

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:

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_pass", "name": "proxy_pass" }, { "table": "
Syntax:proxy_pass_header field;
Default:—
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_pass_header", "name": "proxy_pass_header" }, { "table": "
Syntax:proxy_pass_request_body on | off;
Default:
proxy_pass_request_body on;
Context:http, server, location
", "doc": "

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

\nlocation /x-accel-redirect-here/ {\n    proxy_method GET;\n    proxy_pass_request_body off;\n    proxy_set_header Content-Length "";\n\n    proxy_pass ...\n}\n

See also the proxy_set_header and proxy_pass_request_headers directives.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_pass_request_body", "name": "proxy_pass_request_body" }, { "table": "
Syntax:proxy_pass_request_headers on | off;
Default:
proxy_pass_request_headers on;
Context:http, server, location
", "doc": "

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

\nlocation /x-accel-redirect-here/ {\n    proxy_method GET;\n    proxy_pass_request_headers off;\n    proxy_pass_request_body off;\n\n    proxy_pass ...\n}\n

See also the proxy_set_header and proxy_pass_request_body directives.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_pass_request_headers", "name": "proxy_pass_request_headers" }, { "table": "
Syntax:proxy_read_timeout time;
Default:
proxy_read_timeout 60s;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_read_timeout", "name": "proxy_read_timeout" }, { "table": "
Syntax:proxy_redirect default;
proxy_redirect off;
proxy_redirect redirect replacement;
Default:
proxy_redirect default;
Context:http, server, location
", "doc": "

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

\nproxy_redirect http://localhost:8000/two/ http://frontend/one/;\n

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

A server name may be omitted in the replacement string:

\nproxy_redirect http://localhost:8000/two/ /;\n

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:

\nlocation /one/ {\n    proxy_pass     http://upstream:port/two/;\n    proxy_redirect default;\n
\nlocation /one/ {\n    proxy_pass     http://upstream:port/two/;\n    proxy_redirect http://upstream:port/two/ /one/;\n

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

A replacement string can contain variables:

\nproxy_redirect http://localhost:8000/ http://$host:$server_port/;\n

A redirect can also contain (1.1.11) variables:

\nproxy_redirect http://$proxy_host:8000/ /;\n

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:

\nproxy_redirect ~^(http://[^:]+):\\d+(/.+)$ $1$2;\nproxy_redirect ~*/user/([^/]+)/(.+)$      http://$1.example.com/$2;\n

There could be several proxy_redirect directives:

\nproxy_redirect default;\nproxy_redirect http://localhost:8000/  /;\nproxy_redirect http://www.example.com/ /;\n

The off parameter cancels the effect of all proxy_redirect directives on the current level:

\nproxy_redirect off;\nproxy_redirect default;\nproxy_redirect http://localhost:8000/  /;\nproxy_redirect http://www.example.com/ /;\n

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

\nproxy_redirect / /;\n
", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_redirect", "name": "proxy_redirect" }, { "table": "
Syntax:proxy_request_buffering on | off;
Default:
proxy_request_buffering on;
Context:http, server, location

This directive appeared in version 1.7.11.

", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_request_buffering", "name": "proxy_request_buffering" }, { "table": "
Syntax:proxy_send_lowat size;
Default:
proxy_send_lowat 0;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_send_lowat", "name": "proxy_send_lowat" }, { "table": "
Syntax:proxy_send_timeout time;
Default:
proxy_send_timeout 60s;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_send_timeout", "name": "proxy_send_timeout" }, { "table": "
Syntax:proxy_set_body value;
Default:—
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_set_body", "name": "proxy_set_body" }, { "table": "
Syntax:proxy_set_header field value;
Default:
proxy_set_header Host $proxy_host;
proxy_set_header Connection close;
Context:http, server, location
", "doc": "

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 level if and only if there are no proxy_set_header directives defined on the current level. By default, only two fields are redefined:

\nproxy_set_header Host       $proxy_host;\nproxy_set_header Connection close;\n

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:

\nproxy_set_header Host       $http_host;\n

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:

\nproxy_set_header Host       $host;\n

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

\nproxy_set_header Host       $host:$proxy_port;\n

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

\nproxy_set_header Accept-Encoding "";\n
", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_set_header", "name": "proxy_set_header" }, { "table": "
Syntax:proxy_ssl_certificate file;
Default:—
Context:http, server, location

This directive appeared in version 1.7.8.

", "doc": "

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

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_ssl_certificate", "name": "proxy_ssl_certificate" }, { "table": "
Syntax:proxy_ssl_certificate_key file;
Default:—
Context:http, server, location

This directive appeared in version 1.7.8.

", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_ssl_certificate_key", "name": "proxy_ssl_certificate_key" }, { "table": "
Syntax:proxy_ssl_ciphers ciphers;
Default:
proxy_ssl_ciphers DEFAULT;
Context:http, server, location

This directive appeared in version 1.5.6.

", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_ssl_ciphers", "name": "proxy_ssl_ciphers" }, { "table": "
Syntax:proxy_ssl_crl file;
Default:—
Context:http, server, location

This directive appeared in version 1.7.0.

", "doc": "

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

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_ssl_crl", "name": "proxy_ssl_crl" }, { "table": "
Syntax:proxy_ssl_name name;
Default:
proxy_ssl_name $proxy_host;
Context:http, server, location

This directive appeared in version 1.7.0.

", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_ssl_name", "name": "proxy_ssl_name" }, { "table": "
Syntax:proxy_ssl_password_file file;
Default:—
Context:http, server, location

This directive appeared in version 1.7.8.

", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_ssl_password_file", "name": "proxy_ssl_password_file" }, { "table": "
Syntax:proxy_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default:
proxy_ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
Context:http, server, location

This directive appeared in version 1.5.6.

", "doc": "

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

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_ssl_protocols", "name": "proxy_ssl_protocols" }, { "table": "
Syntax:proxy_ssl_server_name on | off;
Default:
proxy_ssl_server_name off;
Context:http, server, location

This directive appeared in version 1.7.0.

", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_ssl_server_name", "name": "proxy_ssl_server_name" }, { "table": "
Syntax:proxy_ssl_session_reuse on | off;
Default:
proxy_ssl_session_reuse on;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_ssl_session_reuse", "name": "proxy_ssl_session_reuse" }, { "table": "
Syntax:proxy_ssl_trusted_certificate file;
Default:—
Context:http, server, location

This directive appeared in version 1.7.0.

", "doc": "

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

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_ssl_trusted_certificate", "name": "proxy_ssl_trusted_certificate" }, { "table": "
Syntax:proxy_ssl_verify on | off;
Default:
proxy_ssl_verify off;
Context:http, server, location

This directive appeared in version 1.7.0.

", "doc": "

Enables or disables verification of the proxied HTTPS server certificate.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_ssl_verify", "name": "proxy_ssl_verify" }, { "table": "
Syntax:proxy_ssl_verify_depth number;
Default:
proxy_ssl_verify_depth 1;
Context:http, server, location

This directive appeared in version 1.7.0.

", "doc": "

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

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_ssl_verify_depth", "name": "proxy_ssl_verify_depth" }, { "table": "
Syntax:proxy_store on | off | string;
Default:
proxy_store off;
Context:http, server, location
", "doc": "

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:

\nproxy_store /data/www$original_uri;\n

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

\nlocation /images/ {\n    root               /data/www;\n    error_page         404 = /fetch$uri;\n}\n\nlocation /fetch/ {\n    internal;\n\n    proxy_pass         http://backend/;\n    proxy_store        on;\n    proxy_store_access user:rw group:rw all:r;\n    proxy_temp_path    /data/temp;\n\n    alias              /data/www/;\n}\n

or like this:

\nlocation /images/ {\n    root               /data/www;\n    error_page         404 = @fetch;\n}\n\nlocation @fetch {\n    internal;\n\n    proxy_pass         http://backend;\n    proxy_store        on;\n    proxy_store_access user:rw group:rw all:r;\n    proxy_temp_path    /data/temp;\n\n    root               /data/www;\n}\n
", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_store", "name": "proxy_store" }, { "table": "
Syntax:proxy_store_access users:permissions ...;
Default:
proxy_store_access user:rw;
Context:http, server, location
", "doc": "

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

\nproxy_store_access user:rw group:rw all:r;\n

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

\nproxy_store_access group:rw all:r;\n
", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_store_access", "name": "proxy_store_access" }, { "table": "
Syntax:proxy_temp_file_write_size size;
Default:
proxy_temp_file_write_size 8k|16k;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_temp_file_write_size", "name": "proxy_temp_file_write_size" }, { "table": "
Syntax:proxy_temp_path path [level1 [level2 [level3]]];
Default:
proxy_temp_path proxy_temp;
Context:http, server, location
", "doc": "

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

\nproxy_temp_path /spool/nginx/proxy_temp 1 2;\n

a temporary file might look like this:

\n/spool/nginx/proxy_temp/7/45/00000123457\n

See also the use_temp_path parameter of the proxy_cache_path directive.

", "module": "ngx_http_proxy_module", "link": "http/ngx_http_proxy_module.html#proxy_temp_path", "name": "proxy_temp_path" }, { "table": "
Syntax:random_index on | off;
Default:
random_index off;
Context:location
", "doc": "

Enables or disables module processing in a surrounding location.

", "module": "ngx_http_random_index_module", "link": "http/ngx_http_random_index_module.html#random_index", "name": "random_index" }, { "table": "
Syntax:set_real_ip_from address | CIDR | unix:;
Default:—
Context:http, server, location
", "doc": "

Defines trusted addresses that are known to send correct replacement addresses. If the special value unix: is specified, all UNIX-domain sockets will be trusted. Trusted addresses may also be specified using a hostname (1.13.1).

IPv6 addresses are supported starting from versions 1.3.0 and 1.2.1.
", "module": "ngx_http_realip_module", "link": "http/ngx_http_realip_module.html#set_real_ip_from", "name": "set_real_ip_from" }, { "table": "
Syntax:real_ip_header field | X-Real-IP | X-Forwarded-For | proxy_protocol;
Default:
real_ip_header X-Real-IP;
Context:http, server, location
", "doc": "

Defines the request header field whose value will be used to replace the client address.

The request header field value that contains an optional port is also used to replace the client port (1.11.0). The address and port should be specified according to RFC 3986.

The proxy_protocol parameter (1.5.12) changes the client address to the one from the PROXY protocol header. The PROXY protocol must be previously enabled by setting the proxy_protocol parameter in the listen directive.

", "module": "ngx_http_realip_module", "link": "http/ngx_http_realip_module.html#real_ip_header", "name": "real_ip_header" }, { "table": "
Syntax:real_ip_recursive on | off;
Default:
real_ip_recursive off;
Context:http, server, location

This directive appeared in versions 1.3.0 and 1.2.1.

", "doc": "

If recursive search is disabled, the original client address that matches one of the trusted addresses is replaced by the last address sent in the request header field defined by the real_ip_header directive. If recursive search is enabled, the original client address that matches one of the trusted addresses is replaced by the last non-trusted address sent in the request header field.

", "module": "ngx_http_realip_module", "link": "http/ngx_http_realip_module.html#real_ip_recursive", "name": "real_ip_recursive" }, { "table": "
Syntax:referer_hash_bucket_size size;
Default:
referer_hash_bucket_size 64;
Context:server, location

This directive appeared in version 1.0.5.

", "doc": "

Sets the bucket size for the valid referers hash tables. The details of setting up hash tables are provided in a separate document.

", "module": "ngx_http_referer_module", "link": "http/ngx_http_referer_module.html#referer_hash_bucket_size", "name": "referer_hash_bucket_size" }, { "table": "
Syntax:referer_hash_max_size size;
Default:
referer_hash_max_size 2048;
Context:server, location

This directive appeared in version 1.0.5.

", "doc": "

Sets the maximum size of the valid referers hash tables. The details of setting up hash tables are provided in a separate document.

", "module": "ngx_http_referer_module", "link": "http/ngx_http_referer_module.html#referer_hash_max_size", "name": "referer_hash_max_size" }, { "table": "
Syntax:valid_referers none | blocked | server_names | string ...;
Default:—
Context:server, location
", "doc": "

Specifies the “Referer” request header field values that will cause the embedded $invalid_referer variable to be set to an empty string. Otherwise, the variable will be set to “1”. Search for a match is case-insensitive.

Parameters can be as follows:

none
the “Referer” field is missing in the request header;
blocked
the “Referer” field is present in the request header, but its value has been deleted by a firewall or proxy server; such values are strings that do not start with “http://” or “https://”;
server_names
the “Referer” request header field contains one of the server names;
arbitrary string
defines a server name and an optional URI prefix. A server name can have an “*” at the beginning or end. During the checking, the server’s port in the “Referer” field is ignored;
regular expression
the first symbol should be a “~”. It should be noted that an expression will be matched against the text starting after the “http://” or “https://”.

Example:

\nvalid_referers none blocked server_names\n               *.example.com example.* www.example.org/galleries/\n               ~\\.google\\.;\n
", "module": "ngx_http_referer_module", "link": "http/ngx_http_referer_module.html#valid_referers", "name": "valid_referers" }, { "table": "
Syntax:break;
Default:—
Context:server, location, if
", "doc": "

Stops processing the current set of ngx_http_rewrite_module directives.

If a directive is specified inside the location, further processing of the request continues in this location.

Example:

\nif ($slow) {\n    limit_rate 10k;\n    break;\n}\n
", "module": "ngx_http_rewrite_module", "link": "http/ngx_http_rewrite_module.html#break", "name": "break" }, { "table": "
Syntax:if (condition) { ... }
Default:—
Context:server, location
", "doc": "

The specified condition is evaluated. If true, this module directives specified inside the braces are executed, and the request is assigned the configuration inside the if directive. Configurations inside the if directives are inherited from the previous configuration level.

A condition may be any of the following:

", "module": "ngx_http_rewrite_module", "link": "http/ngx_http_rewrite_module.html#if", "name": "if" }, { "table": "
Syntax:return code [text];
return code URL;
return URL;
Default:—
Context:server, location, if
", "doc": "

Stops processing and returns the specified code to a client. The non-standard code 444 closes a connection without sending a response header.

Starting from version 0.8.42, it is possible to specify either a redirect URL (for codes 301, 302, 303, 307, and 308) or the response body text (for other codes). A response body text and redirect URL can contain variables. As a special case, a redirect URL can be specified as a URI local to this server, in which case the full redirect URL is formed according to the request scheme ($scheme) and the server_name_in_redirect and port_in_redirect directives.

In addition, a URL for temporary redirect with the code 302 can be specified as the sole parameter. Such a parameter should start with the “http://”, “https://”, or “$scheme” string. A URL can contain variables.

Only the following codes could be returned before version 0.7.51: 204, 400, 402 — 406, 408, 410, 411, 413, 416, and 500 — 504.
The code 307 was not treated as a redirect until versions 1.1.16 and 1.0.13.
The code 308 was not treated as a redirect until version 1.13.0.

See also the error_page directive.

", "module": "ngx_http_rewrite_module", "link": "http/ngx_http_rewrite_module.html#return", "name": "return" }, { "table": "
Syntax:rewrite regex replacement [flag];
Default:—
Context:server, location, if
", "doc": "

If the specified regular expression matches a request URI, URI is changed as specified in the replacement string. The rewrite directives are executed sequentially in order of their appearance in the configuration file. It is possible to terminate further processing of the directives using flags. If a replacement string starts with “http://”, “https://”, or “$scheme”, the processing stops and the redirect is returned to a client.

An optional flag parameter can be one of:

last
stops processing the current set of ngx_http_rewrite_module directives and starts a search for a new location matching the changed URI;
break
stops processing the current set of ngx_http_rewrite_module directives as with the break directive;
redirect
returns a temporary redirect with the 302 code; used if a replacement string does not start with “http://”, “https://”, or “$scheme”;
permanent
returns a permanent redirect with the 301 code.

The full redirect URL is formed according to the request scheme ($scheme) and the server_name_in_redirect and port_in_redirect directives.

Example:

\nserver {\n    ...\n    rewrite ^(/download/.*)/media/(.*)\\..*$ $1/mp3/$2.mp3 last;\n    rewrite ^(/download/.*)/audio/(.*)\\..*$ $1/mp3/$2.ra  last;\n    return  403;\n    ...\n}\n

But if these directives are put inside the “/download/” location, the last flag should be replaced by break, or otherwise nginx will make 10 cycles and return the 500 error:

\nlocation /download/ {\n    rewrite ^(/download/.*)/media/(.*)\\..*$ $1/mp3/$2.mp3 break;\n    rewrite ^(/download/.*)/audio/(.*)\\..*$ $1/mp3/$2.ra  break;\n    return  403;\n}\n

If a replacement string includes the new request arguments, the previous request arguments are appended after them. If this is undesired, putting a question mark at the end of a replacement string avoids having them appended, for example:

\nrewrite ^/users/(.*)$ /show?user=$1? last;\n

If a regular expression includes the “}” or “;” characters, the whole expressions should be enclosed in single or double quotes.

", "module": "ngx_http_rewrite_module", "link": "http/ngx_http_rewrite_module.html#rewrite", "name": "rewrite" }, { "table": "
Syntax:rewrite_log on | off;
Default:
rewrite_log off;
Context:http, server, location, if
", "doc": "

Enables or disables logging of ngx_http_rewrite_module module directives processing results into the error_log at the notice level.

", "module": "ngx_http_rewrite_module", "link": "http/ngx_http_rewrite_module.html#rewrite_log", "name": "rewrite_log" }, { "table": "
Syntax:set $variable value;
Default:—
Context:server, location, if
", "doc": "

Sets a value for the specified variable. The value can contain text, variables, and their combination.

", "module": "ngx_http_rewrite_module", "link": "http/ngx_http_rewrite_module.html#set", "name": "set" }, { "table": "
Syntax:uninitialized_variable_warn on | off;
Default:
uninitialized_variable_warn on;
Context:http, server, location, if
", "doc": "

Controls whether warnings about uninitialized variables are logged.

", "module": "ngx_http_rewrite_module", "link": "http/ngx_http_rewrite_module.html#uninitialized_variable_warn", "name": "uninitialized_variable_warn" }, { "table": "
Syntax:scgi_bind address [transparent] | off;
Default:—
Context:http, server, location
", "doc": "

Makes outgoing connections to an SCGI 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 scgi_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address and port.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_bind", "name": "scgi_bind" }, { "table": "
Syntax:scgi_buffer_size size;
Default:
scgi_buffer_size 4k|8k;
Context:http, server, location
", "doc": "

Sets the size of the buffer used for reading the first part of the response received from the SCGI 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.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_buffer_size", "name": "scgi_buffer_size" }, { "table": "
Syntax:scgi_buffering on | off;
Default:
scgi_buffering on;
Context:http, server, location
", "doc": "

Enables or disables buffering of responses from the SCGI server.

When buffering is enabled, nginx receives a response from the SCGI server as soon as possible, saving it into the buffers set by the scgi_buffer_size and scgi_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 scgi_max_temp_file_size and scgi_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 SCGI server. The maximum size of the data that nginx can receive from the server at a time is set by the scgi_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 scgi_ignore_headers directive.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_buffering", "name": "scgi_buffering" }, { "table": "
Syntax:scgi_buffers number size;
Default:
scgi_buffers 8 4k|8k;
Context:http, server, location
", "doc": "

Sets the number and size of the buffers used for reading a response from the SCGI 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.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_buffers", "name": "scgi_buffers" }, { "table": "
Syntax:scgi_busy_buffers_size size;
Default:
scgi_busy_buffers_size 8k|16k;
Context:http, server, location
", "doc": "

When buffering of responses from the SCGI 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 scgi_buffer_size and scgi_buffers directives.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_busy_buffers_size", "name": "scgi_busy_buffers_size" }, { "table": "
Syntax:scgi_cache zone | off;
Default:
scgi_cache off;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_cache", "name": "scgi_cache" }, { "table": "
Syntax:scgi_cache_background_update on | off;
Default:
scgi_cache_background_update off;
Context:http, server, location

This directive appeared in version 1.11.10.

", "doc": "

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.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_cache_background_update", "name": "scgi_cache_background_update" }, { "table": "
Syntax:scgi_cache_bypass string ...;
Default:—
Context:http, server, location
", "doc": "

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:

\nscgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;\nscgi_cache_bypass $http_pragma    $http_authorization;\n

Can be used along with the scgi_no_cache directive.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_cache_bypass", "name": "scgi_cache_bypass" }, { "table": "
Syntax:scgi_cache_key string;
Default:—
Context:http, server, location
", "doc": "

Defines a key for caching, for example

\nscgi_cache_key localhost:9000$request_uri;\n
", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_cache_key", "name": "scgi_cache_key" }, { "table": "
Syntax:scgi_cache_lock on | off;
Default:
scgi_cache_lock off;
Context:http, server, location

This directive appeared in version 1.1.12.

", "doc": "

When enabled, only one request at a time will be allowed to populate a new cache element identified according to the scgi_cache_key directive by passing a request to an SCGI 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 scgi_cache_lock_timeout directive.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_cache_lock", "name": "scgi_cache_lock" }, { "table": "
Syntax:scgi_cache_lock_age time;
Default:
scgi_cache_lock_age 5s;
Context:http, server, location

This directive appeared in version 1.7.8.

", "doc": "

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

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_cache_lock_age", "name": "scgi_cache_lock_age" }, { "table": "
Syntax:scgi_cache_lock_timeout time;
Default:
scgi_cache_lock_timeout 5s;
Context:http, server, location

This directive appeared in version 1.1.12.

", "doc": "

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

Before 1.7.8, the response could be cached.
", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_cache_lock_timeout", "name": "scgi_cache_lock_timeout" }, { "table": "
Syntax:scgi_cache_max_range_offset number;
Default:—
Context:http, server, location

This directive appeared in version 1.11.6.

", "doc": "

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

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_cache_max_range_offset", "name": "scgi_cache_max_range_offset" }, { "table": "
Syntax:scgi_cache_methods GET | HEAD | POST ...;
Default:
scgi_cache_methods GET HEAD;
Context:http, server, location
", "doc": "

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 scgi_no_cache directive.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_cache_methods", "name": "scgi_cache_methods" }, { "table": "
Syntax:scgi_cache_min_uses number;
Default:
scgi_cache_min_uses 1;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_cache_min_uses", "name": "scgi_cache_min_uses" }, { "table": "
Syntax:scgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time];
Default:—
Context:http
", "doc": "

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

\nscgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;\n

file names in a cache will look like this:

\n/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c\n

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. A 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 scgi_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.

As part of commercial subscription, the shared memory zone also stores extended cache information, thus, it is required to specify a larger zone size for the same number of keys. For example, one megabyte zone can store about 4 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. When this size is exceeded, 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.
In versions 1.7.3, 1.7.7, and 1.11.10 cache header format has been changed. Previously cached responses will be considered invalid after upgrading to a newer nginx version.
", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_cache_path", "name": "scgi_cache_path" }, { "table": "
Syntax:scgi_cache_purge string ...;
Default:—
Context:http, server, location

This directive appeared in version 1.5.7.

", "doc": "

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.

Example configuration:

\nscgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;\n\nmap $request_method $purge_method {\n    PURGE   1;\n    default 0;\n}\n\nserver {\n    ...\n    location / {\n        scgi_pass        backend;\n        scgi_cache       cache_zone;\n        scgi_cache_key   $uri;\n        scgi_cache_purge $purge_method;\n    }\n}\n
This functionality is available as part of our commercial subscription.
", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_cache_purge", "name": "scgi_cache_purge" }, { "table": "
Syntax:scgi_cache_revalidate on | off;
Default:
scgi_cache_revalidate off;
Context:http, server, location

This directive appeared in version 1.5.7.

", "doc": "

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

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_cache_revalidate", "name": "scgi_cache_revalidate" }, { "table": "
Syntax:scgi_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_503 | http_403 | http_404 | http_429 | off ...;
Default:
scgi_cache_use_stale off;
Context:http, server, location
", "doc": "

Determines in which cases a stale cached response can be used when an error occurs during communication with the SCGI server. The directive’s parameters match the parameters of the scgi_next_upstream directive.

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

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_cache_use_stale", "name": "scgi_cache_use_stale" }, { "table": "
Syntax:scgi_cache_valid [code ...] time;
Default:—
Context:http, server, location
", "doc": "

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

\nscgi_cache_valid 200 302 10m;\nscgi_cache_valid 404      1m;\n

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

\nscgi_cache_valid 5m;\n

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

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

\nscgi_cache_valid 200 302 10m;\nscgi_cache_valid 301      1h;\nscgi_cache_valid any      1m;\n

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

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_cache_valid", "name": "scgi_cache_valid" }, { "table": "
Syntax:scgi_connect_timeout time;
Default:
scgi_connect_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_connect_timeout", "name": "scgi_connect_timeout" }, { "table": "
Syntax:scgi_force_ranges on | off;
Default:
scgi_force_ranges off;
Context:http, server, location

This directive appeared in version 1.7.7.

", "doc": "

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

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_force_ranges", "name": "scgi_force_ranges" }, { "table": "
Syntax:scgi_hide_header field;
Default:—
Context:http, server, location
", "doc": "

By default, nginx does not pass the header fields “Status” and “X-Accel-...” from the response of an SCGI server to a client. The scgi_hide_header directive sets additional fields that will not be passed. If, on the contrary, the passing of fields needs to be permitted, the scgi_pass_header directive can be used.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_hide_header", "name": "scgi_hide_header" }, { "table": "
Syntax:scgi_ignore_client_abort on | off;
Default:
scgi_ignore_client_abort off;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_ignore_client_abort", "name": "scgi_ignore_client_abort" }, { "table": "
Syntax:scgi_ignore_headers field ...;
Default:—
Context:http, server, location
", "doc": "

Disables processing of certain response header fields from the SCGI 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:

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_ignore_headers", "name": "scgi_ignore_headers" }, { "table": "
Syntax:scgi_intercept_errors on | off;
Default:
scgi_intercept_errors off;
Context:http, server, location
", "doc": "

Determines whether an SCGI server 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.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_intercept_errors", "name": "scgi_intercept_errors" }, { "table": "
Syntax:scgi_limit_rate rate;
Default:
scgi_limit_rate 0;
Context:http, server, location

This directive appeared in version 1.7.7.

", "doc": "

Limits the speed of reading the response from the SCGI 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 SCGI server, the overall rate will be twice as much as the specified limit. The limitation works only if buffering of responses from the SCGI server is enabled.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_limit_rate", "name": "scgi_limit_rate" }, { "table": "
Syntax:scgi_max_temp_file_size size;
Default:
scgi_max_temp_file_size 1024m;
Context:http, server, location
", "doc": "

When buffering of responses from the SCGI server is enabled, and the whole response does not fit into the buffers set by the scgi_buffer_size and scgi_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 scgi_temp_file_write_size directive.

The zero value disables buffering of responses to temporary files.

This restriction does not apply to responses that will be cached or stored on disk.
", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_max_temp_file_size", "name": "scgi_max_temp_file_size" }, { "table": "
Syntax:scgi_next_upstream error | timeout | invalid_header | http_500 | http_503 | http_403 | http_404 | http_429 | non_idempotent | off ...;
Default:
scgi_next_upstream error timeout;
Context:http, server, location
", "doc": "

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_503
a server returned a response with the code 503;
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_503, 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.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_next_upstream", "name": "scgi_next_upstream" }, { "table": "
Syntax:scgi_next_upstream_timeout time;
Default:
scgi_next_upstream_timeout 0;
Context:http, server, location

This directive appeared in version 1.7.5.

", "doc": "

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

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_next_upstream_timeout", "name": "scgi_next_upstream_timeout" }, { "table": "
Syntax:scgi_next_upstream_tries number;
Default:
scgi_next_upstream_tries 0;
Context:http, server, location

This directive appeared in version 1.7.5.

", "doc": "

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

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_next_upstream_tries", "name": "scgi_next_upstream_tries" }, { "table": "
Syntax:scgi_no_cache string ...;
Default:—
Context:http, server, location
", "doc": "

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:

\nscgi_no_cache $cookie_nocache $arg_nocache$arg_comment;\nscgi_no_cache $http_pragma    $http_authorization;\n

Can be used along with the scgi_cache_bypass directive.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_no_cache", "name": "scgi_no_cache" }, { "table": "
Syntax:scgi_param parameter value [if_not_empty];
Default:—
Context:http, server, location
", "doc": "

Sets a parameter that should be passed to the SCGI server. The value can contain text, variables, and their combination. These directives are inherited from the previous level if and only if there are no scgi_param directives defined on the current level.

Standard CGI environment variables should be provided as SCGI headers, see the scgi_params file provided in the distribution:

\nlocation / {\n    include scgi_params;\n    ...\n}\n

If the directive is specified with if_not_empty (1.1.11) then such a parameter will be passed to the server only if its value is not empty:

\nscgi_param HTTPS $https if_not_empty;\n
", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_param", "name": "scgi_param" }, { "table": "
Syntax:scgi_pass address;
Default:—
Context:location, if in location
", "doc": "

Sets the address of an SCGI server. The address can be specified as a domain name or IP address, and a port:

\nscgi_pass localhost:9000;\n

or as a UNIX-domain socket path:

\nscgi_pass unix:/tmp/scgi.socket;\n

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.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_pass", "name": "scgi_pass" }, { "table": "
Syntax:scgi_pass_header field;
Default:—
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_pass_header", "name": "scgi_pass_header" }, { "table": "
Syntax:scgi_pass_request_body on | off;
Default:
scgi_pass_request_body on;
Context:http, server, location
", "doc": "

Indicates whether the original request body is passed to the SCGI server. See also the scgi_pass_request_headers directive.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_pass_request_body", "name": "scgi_pass_request_body" }, { "table": "
Syntax:scgi_pass_request_headers on | off;
Default:
scgi_pass_request_headers on;
Context:http, server, location
", "doc": "

Indicates whether the header fields of the original request are passed to the SCGI server. See also the scgi_pass_request_body directive.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_pass_request_headers", "name": "scgi_pass_request_headers" }, { "table": "
Syntax:scgi_read_timeout time;
Default:
scgi_read_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_read_timeout", "name": "scgi_read_timeout" }, { "table": "
Syntax:scgi_request_buffering on | off;
Default:
scgi_request_buffering on;
Context:http, server, location

This directive appeared in version 1.7.11.

", "doc": "

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 an SCGI server.

When buffering is disabled, the request body is sent to the SCGI 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.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_request_buffering", "name": "scgi_request_buffering" }, { "table": "
Syntax:scgi_send_timeout time;
Default:
scgi_send_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_send_timeout", "name": "scgi_send_timeout" }, { "table": "
Syntax:scgi_store on | off | string;
Default:
scgi_store off;
Context:http, server, location
", "doc": "

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:

\nscgi_store /data/www$original_uri;\n

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 scgi_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.:

\nlocation /images/ {\n    root              /data/www;\n    error_page        404 = /fetch$uri;\n}\n\nlocation /fetch/ {\n    internal;\n\n    scgi_pass         backend:9000;\n    ...\n\n    scgi_store        on;\n    scgi_store_access user:rw group:rw all:r;\n    scgi_temp_path    /data/temp;\n\n    alias             /data/www/;\n}\n
", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_store", "name": "scgi_store" }, { "table": "
Syntax:scgi_store_access users:permissions ...;
Default:
scgi_store_access user:rw;
Context:http, server, location
", "doc": "

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

\nscgi_store_access user:rw group:rw all:r;\n

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

\nscgi_store_access group:rw all:r;\n
", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_store_access", "name": "scgi_store_access" }, { "table": "
Syntax:scgi_temp_file_write_size size;
Default:
scgi_temp_file_write_size 8k|16k;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_temp_file_write_size", "name": "scgi_temp_file_write_size" }, { "table": "
Syntax:scgi_temp_path path [level1 [level2 [level3]]];
Default:
scgi_temp_path scgi_temp;
Context:http, server, location
", "doc": "

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

\nscgi_temp_path /spool/nginx/scgi_temp 1 2;\n

a temporary file might look like this:

\n/spool/nginx/scgi_temp/7/45/00000123457\n

See also the use_temp_path parameter of the scgi_cache_path directive.

", "module": "ngx_http_scgi_module", "link": "http/ngx_http_scgi_module.html#scgi_temp_path", "name": "scgi_temp_path" }, { "table": "
Syntax:secure_link expression;
Default:—
Context:http, server, location
", "doc": "

Defines a string with variables from which the checksum value and lifetime of a link will be extracted.

Variables used in an expression are usually associated with a request; see example below.

The checksum value extracted from the string is compared with the MD5 hash value of the expression defined by the secure_link_md5 directive. If the checksums are different, the $secure_link variable is set to an empty string. If the checksums are the same, the link lifetime is checked. If the link has a limited lifetime and the time has expired, the $secure_link variable is set to “0”. Otherwise, it is set to “1”. The MD5 hash value passed in a request is encoded in base64url.

If a link has a limited lifetime, the expiration time is set in seconds since Epoch (Thu, 01 Jan 1970 00:00:00 GMT). The value is specified in the expression after the MD5 hash, and is separated by a comma. The expiration time passed in a request is available through the $secure_link_expires variable for a use in the secure_link_md5 directive. If the expiration time is not specified, a link has the unlimited lifetime.

", "module": "ngx_http_secure_link_module", "link": "http/ngx_http_secure_link_module.html#secure_link", "name": "secure_link" }, { "table": "
Syntax:secure_link_md5 expression;
Default:—
Context:http, server, location
", "doc": "

Defines an expression for which the MD5 hash value will be computed and compared with the value passed in a request.

The expression should contain the secured part of a link (resource) and a secret ingredient. If the link has a limited lifetime, the expression should also contain $secure_link_expires.

To prevent unauthorized access, the expression may contain some information about the client, such as its address and browser version.

Example:

\nlocation /s/ {\n    secure_link $arg_md5,$arg_expires;\n    secure_link_md5 "$secure_link_expires$uri$remote_addr secret";\n\n    if ($secure_link = "") {\n        return 403;\n    }\n\n    if ($secure_link = "0") {\n        return 410;\n    }\n\n    ...\n}\n

The “/s/link?md5=_e4Nc3iduzkWRm01TBBNYw&expires=2147483647” link restricts access to “/s/link” for the client with the IP address 127.0.0.1. The link also has the limited lifetime until January 19, 2038 (GMT).

On UNIX, the md5 request argument value can be obtained as:

\necho -n '2147483647/s/link127.0.0.1 secret' | \\\n    openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =\n
", "module": "ngx_http_secure_link_module", "link": "http/ngx_http_secure_link_module.html#secure_link_md5", "name": "secure_link_md5" }, { "table": "
Syntax:secure_link_secret word;
Default:—
Context:location
", "doc": "

Defines a secret word used to check authenticity of requested links.

The full URI of a requested link looks as follows:

\n/prefix/hash/link\n

where hash is a hexadecimal representation of the MD5 hash computed for the concatenation of the link and secret word, and prefix is an arbitrary string without slashes.

If the requested link passes the authenticity check, the $secure_link variable is set to the link extracted from the request URI. Otherwise, the $secure_link variable is set to an empty string.

Example:

\nlocation /p/ {\n    secure_link_secret secret;\n\n    if ($secure_link = "") {\n        return 403;\n    }\n\n    rewrite ^ /secure/$secure_link;\n}\n\nlocation /secure/ {\n    internal;\n}\n

A request of “/p/5e814704a28d9bc1914ff19fa0c4a00a/link” will be internally redirected to “/secure/link”.

On UNIX, the hash value for this example can be obtained as:

\necho -n 'linksecret' | openssl md5 -hex\n
", "module": "ngx_http_secure_link_module", "link": "http/ngx_http_secure_link_module.html#secure_link_secret", "name": "secure_link_secret" }, { "table": "
Syntax:session_log name | off;
Default:
session_log off;
Context:http, server, location
", "doc": "

Enables the use of the specified session log. The special value off cancels all session_log directives inherited from the previous configuration level.

", "module": "ngx_http_session_log_module", "link": "http/ngx_http_session_log_module.html#session_log", "name": "session_log" }, { "table": "
Syntax:session_log_format name string ...;
Default:
session_log_format combined "...";
Context:http
", "doc": "

Specifies the output format of a log. The value of the $body_bytes_sent variable is aggregated across all requests in a session. The values of all other variables available for logging correspond to the first request in a session.

", "module": "ngx_http_session_log_module", "link": "http/ngx_http_session_log_module.html#session_log_format", "name": "session_log_format" }, { "table": "
Syntax:session_log_zone path zone=name:size [format=format] [timeout=time] [id=id] [md5=md5] ;
Default:—
Context:http
", "doc": "

Sets the path to a log file and configures the shared memory zone that is used to store currently active sessions.

A session is considered active for as long as the time elapsed since the last request in the session does not exceed the specified timeout (by default, 30 seconds). Once a session is no longer active, it is written to the log.

The id parameter identifies the session to which a request is mapped. The id parameter is set to the hexadecimal representation of an MD5 hash (for example, obtained from a cookie using variables). If this parameter is not specified or does not represent the valid MD5 hash, nginx computes the MD5 hash from the value of the md5 parameter and creates a new session using this hash. Both the id and md5 parameters can contain variables.

The format parameter sets the custom session log format configured by the session_log_format directive. If format is not specified, the predefined “combined” format is used.

", "module": "ngx_http_session_log_module", "link": "http/ngx_http_session_log_module.html#session_log_zone", "name": "session_log_zone" }, { "table": "
Syntax:slice size;
Default:
slice 0;
Context:http, server, location
", "doc": "

Sets the size of the slice. The zero value disables splitting responses into slices. Note that a too low value may result in excessive memory usage and opening a large number of files.

In order for a subrequest to return the required range, the $slice_range variable should be passed to the proxied server as the Range request header field. If caching is enabled, $slice_range should be added to the cache key and caching of responses with 206 status code should be enabled.

", "module": "ngx_http_slice_module", "link": "http/ngx_http_slice_module.html#slice", "name": "slice" }, { "table": "
Syntax:spdy_chunk_size size;
Default:
spdy_chunk_size 8k;
Context:http, server, location

This directive appeared in version 1.5.9.

", "doc": "

Sets the maximum size of chunks into which the response body is sliced. A too low value results in higher overhead. A too high value impairs prioritization due to HOL blocking.

", "module": "ngx_http_spdy_module", "link": "http/ngx_http_spdy_module.html#spdy_chunk_size", "name": "spdy_chunk_size" }, { "table": "
Syntax:spdy_headers_comp level;
Default:
spdy_headers_comp 0;
Context:http, server
", "doc": "

Sets the header compression level of a response in a range from 1 (fastest, less compression) to 9 (slowest, best compression). The special value 0 turns off the header compression.

", "module": "ngx_http_spdy_module", "link": "http/ngx_http_spdy_module.html#spdy_headers_comp", "name": "spdy_headers_comp" }, { "table": "
Syntax:split_clients string $variable { ... }
Default:—
Context:http
", "doc": "

Creates a variable for A/B testing, for example:

\nsplit_clients "${remote_addr}AAA" $variant {\n               0.5%               .one;\n               2.0%               .two;\n               *                  "";\n}\n

The value of the original string is hashed using MurmurHash2. In the example given, hash values from 0 to 21474835 (0.5%) correspond to the value ".one" of the $variant variable, hash values from 21474836 to 107374180 (2%) correspond to the value ".two", and hash values from 107374181 to 4294967295 correspond to the value "" (an empty string).

", "module": "ngx_http_split_clients_module", "link": "http/ngx_http_split_clients_module.html#split_clients", "name": "split_clients" }, { "table": "
Syntax:ssi on | off;
Default:
ssi off;
Context:http, server, location, if in location
", "doc": "

Enables or disables processing of SSI commands in responses.

", "module": "ngx_http_ssi_module", "link": "http/ngx_http_ssi_module.html#ssi", "name": "ssi" }, { "table": "
Syntax:ssi_last_modified on | off;
Default:
ssi_last_modified off;
Context:http, server, location

This directive appeared in version 1.5.1.

", "doc": "

Allows preserving the “Last-Modified” header field from the original response during SSI processing to facilitate response caching.

By default, the header field is removed as contents of the response are modified during processing and may contain dynamically generated elements or parts that are changed independently of the original response.

", "module": "ngx_http_ssi_module", "link": "http/ngx_http_ssi_module.html#ssi_last_modified", "name": "ssi_last_modified" }, { "table": "
Syntax:ssi_min_file_chunk size;
Default:
ssi_min_file_chunk 1k;
Context:http, server, location
", "doc": "

Sets the minimum size for parts of a response stored on disk, starting from which it makes sense to send them using sendfile.

", "module": "ngx_http_ssi_module", "link": "http/ngx_http_ssi_module.html#ssi_min_file_chunk", "name": "ssi_min_file_chunk" }, { "table": "
Syntax:ssi_silent_errors on | off;
Default:
ssi_silent_errors off;
Context:http, server, location
", "doc": "

If enabled, suppresses the output of the “[an error occurred while processing the directive]” string if an error occurred during SSI processing.

", "module": "ngx_http_ssi_module", "link": "http/ngx_http_ssi_module.html#ssi_silent_errors", "name": "ssi_silent_errors" }, { "table": "
Syntax:ssi_types mime-type ...;
Default:
ssi_types text/html;
Context:http, server, location
", "doc": "

Enables processing of SSI commands in responses with the specified MIME types in addition to “text/html”. The special value “*” matches any MIME type (0.8.29).

", "module": "ngx_http_ssi_module", "link": "http/ngx_http_ssi_module.html#ssi_types", "name": "ssi_types" }, { "table": "
Syntax:ssi_value_length length;
Default:
ssi_value_length 256;
Context:http, server, location
", "doc": "

Sets the maximum length of parameter values in SSI commands.

", "module": "ngx_http_ssi_module", "link": "http/ngx_http_ssi_module.html#ssi_value_length", "name": "ssi_value_length" }, { "table": "
Syntax:ssl on | off;
Default:
ssl off;
Context:http, server
", "doc": "

This directive was made obsolete in version 1.15.0. The ssl parameter of the listen directive should be used instead.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl", "name": "ssl" }, { "table": "
Syntax:ssl_buffer_size size;
Default:
ssl_buffer_size 16k;
Context:http, server

This directive appeared in version 1.5.9.

", "doc": "

Sets the size of the buffer used for sending data.

By default, the buffer size is 16k, which corresponds to minimal overhead when sending big responses. To minimize Time To First Byte it may be beneficial to use smaller values, for example:

\nssl_buffer_size 4k;\n
", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_buffer_size", "name": "ssl_buffer_size" }, { "table": "
Syntax:ssl_certificate file;
Default:—
Context:http, server
", "doc": "

Specifies a file with the certificate in the PEM format for the given virtual server. If intermediate certificates should be specified in addition to a primary certificate, they should be specified in the same file in the following order: the primary certificate comes first, then the intermediate certificates. A secret key in the PEM format may be placed in the same file.

Since version 1.11.0, this directive can be specified multiple times to load certificates of different types, for example, RSA and ECDSA:

\nserver {\n    listen              443 ssl;\n    server_name         example.com;\n\n    ssl_certificate     example.com.rsa.crt;\n    ssl_certificate_key example.com.rsa.key;\n\n    ssl_certificate     example.com.ecdsa.crt;\n    ssl_certificate_key example.com.ecdsa.key;\n\n    ...\n}\n
Only OpenSSL 1.0.2 or higher supports separate certificate chains for different certificates. With older versions, only one certificate chain can be used.

It should be kept in mind that due to the HTTPS protocol limitations for maximum interoperability virtual servers should listen on different IP addresses.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_certificate", "name": "ssl_certificate" }, { "table": "
Syntax:ssl_certificate_key file;
Default:—
Context:http, server
", "doc": "

Specifies a file with the secret key in the PEM format for the given virtual 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.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_certificate_key", "name": "ssl_certificate_key" }, { "table": "
Syntax:ssl_ciphers ciphers;
Default:
ssl_ciphers HIGH:!aNULL:!MD5;
Context:http, server
", "doc": "

Specifies the enabled ciphers. The ciphers are specified in the format understood by the OpenSSL library, for example:

\nssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;\n

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

The previous versions of nginx used different ciphers by default.
", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_ciphers", "name": "ssl_ciphers" }, { "table": "
Syntax:ssl_client_certificate file;
Default:—
Context:http, server
", "doc": "

Specifies a file with trusted CA certificates in the PEM format used to verify client certificates and OCSP responses if ssl_stapling is enabled.

The list of certificates will be sent to clients. If this is not desired, the ssl_trusted_certificate directive can be used.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_client_certificate", "name": "ssl_client_certificate" }, { "table": "
Syntax:ssl_crl file;
Default:—
Context:http, server

This directive appeared in version 0.8.7.

", "doc": "

Specifies a file with revoked certificates (CRL) in the PEM format used to verify client certificates.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_crl", "name": "ssl_crl" }, { "table": "
Syntax:ssl_dhparam file;
Default:—
Context:http, server

This directive appeared in version 0.7.2.

", "doc": "

Specifies a file with DH parameters for DHE ciphers.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_dhparam", "name": "ssl_dhparam" }, { "table": "
Syntax:ssl_ecdh_curve curve;
Default:
ssl_ecdh_curve auto;
Context:http, server

This directive appeared in versions 1.1.0 and 1.0.6.

", "doc": "

Specifies a curve for ECDHE ciphers.

When using OpenSSL 1.0.2 or higher, it is possible to specify multiple curves (1.11.0), for example:

\nssl_ecdh_curve prime256v1:secp384r1;\n

The special value auto (1.11.0) instructs nginx to use a list built into the OpenSSL library when using OpenSSL 1.0.2 or higher, or prime256v1 with older versions.

Prior to version 1.11.0, the prime256v1 curve was used by default.
", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_ecdh_curve", "name": "ssl_ecdh_curve" }, { "table": "
Syntax:ssl_password_file file;
Default:—
Context:http, server

This directive appeared in version 1.7.3.

", "doc": "

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.

Example:

\nhttp {\n    ssl_password_file /etc/keys/global.pass;\n    ...\n\n    server {\n        server_name www1.example.com;\n        ssl_certificate_key /etc/keys/first.key;\n    }\n\n    server {\n        server_name www2.example.com;\n\n        # named pipe can also be used instead of a file\n        ssl_password_file /etc/keys/fifo;\n        ssl_certificate_key /etc/keys/second.key;\n    }\n}\n
", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_password_file", "name": "ssl_password_file" }, { "table": "
Syntax:ssl_prefer_server_ciphers on | off;
Default:
ssl_prefer_server_ciphers off;
Context:http, server
", "doc": "

Specifies that server ciphers should be preferred over client ciphers when using the SSLv3 and TLS protocols.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_prefer_server_ciphers", "name": "ssl_prefer_server_ciphers" }, { "table": "
Syntax:ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default:
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
Context:http, server
", "doc": "

Enables the specified protocols.

The TLSv1.1 and TLSv1.2 parameters (1.1.13, 1.0.12) work only when OpenSSL 1.0.1 or higher is used.
The TLSv1.3 parameter (1.13.0) works only when OpenSSL 1.1.1 built with TLSv1.3 support is used.
", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_protocols", "name": "ssl_protocols" }, { "table": "
Syntax:ssl_session_cache off | none | [builtin[:size]] [shared:name:size];
Default:
ssl_session_cache none;
Context:http, server
", "doc": "

Sets the types and sizes of caches that store session parameters. A cache can be of any of the following types:

off
the use of a session cache is strictly prohibited: nginx explicitly tells a client that sessions may not be reused.
none
the use of a session cache is gently disallowed: nginx tells a client that sessions may be reused, but does not actually store session parameters in the cache.
builtin
a cache built in OpenSSL; used by one worker process only. The cache size is specified in sessions. If size is not given, it is equal to 20480 sessions. Use of the built-in cache can cause memory fragmentation.
shared
a cache shared between all worker processes. The cache size is specified in bytes; one megabyte can store about 4000 sessions. Each shared cache should have an arbitrary name. A cache with the same name can be used in several virtual servers.

Both cache types can be used simultaneously, for example:

\nssl_session_cache builtin:1000 shared:SSL:10m;\n

but using only shared cache without the built-in cache should be more efficient.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_session_cache", "name": "ssl_session_cache" }, { "table": "
Syntax:ssl_session_ticket_key file;
Default:—
Context:http, server

This directive appeared in version 1.5.7.

", "doc": "

Sets a file with the secret key used to encrypt and decrypt TLS session tickets. The directive is necessary if the same key has to be shared between multiple servers. By default, a randomly generated key is used.

If several keys are specified, only the first key is used to encrypt TLS session tickets. This allows configuring key rotation, for example:

\nssl_session_ticket_key current.key;\nssl_session_ticket_key previous.key;\n

The file must contain 80 or 48 bytes of random data and can be created using the following command:

\nopenssl rand 80 > ticket.key\n

Depending on the file size either AES256 (for 80-byte keys, 1.11.8) or AES128 (for 48-byte keys) is used for encryption.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_session_ticket_key", "name": "ssl_session_ticket_key" }, { "table": "
Syntax:ssl_session_tickets on | off;
Default:
ssl_session_tickets on;
Context:http, server

This directive appeared in version 1.5.9.

", "doc": "

Enables or disables session resumption through TLS session tickets.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_session_tickets", "name": "ssl_session_tickets" }, { "table": "
Syntax:ssl_session_timeout time;
Default:
ssl_session_timeout 5m;
Context:http, server
", "doc": "

Specifies a time during which a client may reuse the session parameters.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_session_timeout", "name": "ssl_session_timeout" }, { "table": "
Syntax:ssl_stapling on | off;
Default:
ssl_stapling off;
Context:http, server

This directive appeared in version 1.3.7.

", "doc": "

Enables or disables stapling of OCSP responses by the server. Example:

\nssl_stapling on;\nresolver 192.0.2.1;\n

For the OCSP stapling to work, the certificate of the server certificate issuer should be known. If the ssl_certificate file does not contain intermediate certificates, the certificate of the server certificate issuer should be present in the ssl_trusted_certificate file.

For a resolution of the OCSP responder hostname, the resolver directive should also be specified.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_stapling", "name": "ssl_stapling" }, { "table": "
Syntax:ssl_stapling_file file;
Default:—
Context:http, server

This directive appeared in version 1.3.7.

", "doc": "

When set, the stapled OCSP response will be taken from the specified file instead of querying the OCSP responder specified in the server certificate.

The file should be in the DER format as produced by the “openssl ocsp” command.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_stapling_file", "name": "ssl_stapling_file" }, { "table": "
Syntax:ssl_stapling_responder url;
Default:—
Context:http, server

This directive appeared in version 1.3.7.

", "doc": "

Overrides the URL of the OCSP responder specified in the “Authority Information Access” certificate extension.

Only “http://” OCSP responders are supported:

\nssl_stapling_responder http://ocsp.example.com/;\n
", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_stapling_responder", "name": "ssl_stapling_responder" }, { "table": "
Syntax:ssl_stapling_verify on | off;
Default:
ssl_stapling_verify off;
Context:http, server

This directive appeared in version 1.3.7.

", "doc": "

Enables or disables verification of OCSP responses by the server.

For verification to work, the certificate of the server certificate issuer, the root certificate, and all intermediate certificates should be configured as trusted using the ssl_trusted_certificate directive.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_stapling_verify", "name": "ssl_stapling_verify" }, { "table": "
Syntax:ssl_trusted_certificate file;
Default:—
Context:http, server

This directive appeared in version 1.3.7.

", "doc": "

Specifies a file with trusted CA certificates in the PEM format used to verify client certificates and OCSP responses if ssl_stapling is enabled.

In contrast to the certificate set by ssl_client_certificate, the list of these certificates will not be sent to clients.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_trusted_certificate", "name": "ssl_trusted_certificate" }, { "table": "
Syntax:ssl_verify_client on | off | optional | optional_no_ca;
Default:
ssl_verify_client off;
Context:http, server
", "doc": "

Enables verification of client certificates. The verification result is stored in the $ssl_client_verify variable.

The optional parameter (0.8.7+) requests the client certificate and verifies it if the certificate is present.

The optional_no_ca parameter (1.3.8, 1.2.5) requests the client certificate but does not require it to be signed by a trusted CA certificate. This is intended for the use in cases when a service that is external to nginx performs the actual certificate verification. The contents of the certificate is accessible through the $ssl_client_cert variable.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_verify_client", "name": "ssl_verify_client" }, { "table": "
Syntax:ssl_verify_depth number;
Default:
ssl_verify_depth 1;
Context:http, server
", "doc": "

Sets the verification depth in the client certificates chain.

", "module": "ngx_http_ssl_module", "link": "http/ngx_http_ssl_module.html#ssl_verify_depth", "name": "ssl_verify_depth" }, { "table": "
Syntax:status;
Default:—
Context:location
", "doc": "

The status information will be accessible from the surrounding location. Access to this location should be limited.

", "module": "ngx_http_status_module", "link": "http/ngx_http_status_module.html#status", "name": "status" }, { "table": "
Syntax:status_format json;
status_format jsonp [callback];
Default:
status_format json;
Context:http, server, location
", "doc": "

By default, status information is output in the JSON format.

Alternatively, data may be output as JSONP. The callback parameter specifies the name of a callback function. The value can contain variables. If parameter is omitted, or the computed value is an empty string, then “ngx_status_jsonp_callback” is used.

", "module": "ngx_http_status_module", "link": "http/ngx_http_status_module.html#status_format", "name": "status_format" }, { "table": "
Syntax:status_zone zone;
Default:—
Context:server
", "doc": "

Enables collection of virtual http or stream (1.7.11) server status information in the specified zone. Several servers may share the same zone.

", "module": "ngx_http_status_module", "link": "http/ngx_http_status_module.html#status_zone", "name": "status_zone" }, { "table": "
Syntax:stub_status;
Default:—
Context:server, location
", "doc": "

The basic status information will be accessible from the surrounding location.

In versions prior to 1.7.5, the directive syntax required an arbitrary argument, for example, “stub_status on”.
", "module": "ngx_http_stub_status_module", "link": "http/ngx_http_stub_status_module.html#stub_status", "name": "stub_status" }, { "table": "
Syntax:sub_filter string replacement;
Default:—
Context:http, server, location
", "doc": "

Sets a string to replace and a replacement string. The string to replace is matched ignoring the case. The string to replace (1.9.4) and replacement string can contain variables. Several sub_filter directives can be specified on one configuration level (1.9.4). These directives are inherited from the previous level if and only if there are no sub_filter directives defined on the current level.

", "module": "ngx_http_sub_module", "link": "http/ngx_http_sub_module.html#sub_filter", "name": "sub_filter" }, { "table": "
Syntax:sub_filter_last_modified on | off;
Default:
sub_filter_last_modified off;
Context:http, server, location

This directive appeared in version 1.5.1.

", "doc": "

Allows preserving the “Last-Modified” header field from the original response during replacement to facilitate response caching.

By default, the header field is removed as contents of the response are modified during processing.

", "module": "ngx_http_sub_module", "link": "http/ngx_http_sub_module.html#sub_filter_last_modified", "name": "sub_filter_last_modified" }, { "table": "
Syntax:sub_filter_once on | off;
Default:
sub_filter_once on;
Context:http, server, location
", "doc": "

Indicates whether to look for each string to replace once or repeatedly.

", "module": "ngx_http_sub_module", "link": "http/ngx_http_sub_module.html#sub_filter_once", "name": "sub_filter_once" }, { "table": "
Syntax:sub_filter_types mime-type ...;
Default:
sub_filter_types text/html;
Context:http, server, location
", "doc": "

Enables string replacement in responses with the specified MIME types in addition to “text/html”. The special value “*” matches any MIME type (0.8.29).

", "module": "ngx_http_sub_module", "link": "http/ngx_http_sub_module.html#sub_filter_types", "name": "sub_filter_types" }, { "table": "
Syntax:upstream name { ... }
Default:—
Context:http
", "doc": "

Defines a group of servers. Servers can listen on different ports. In addition, servers listening on TCP and UNIX-domain sockets can be mixed.

Example:

\nupstream backend {\n    server backend1.example.com weight=5;\n    server 127.0.0.1:8080       max_fails=3 fail_timeout=30s;\n    server unix:/tmp/backend3;\n\n    server backup1.example.com  backup;\n}\n

By default, requests are distributed between the servers using a weighted round-robin balancing method. In the above example, each 7 requests will be distributed as follows: 5 requests go to backend1.example.com and one request to each of the second and third servers. If an error occurs during communication with a server, the request will be passed to the next server, and so on until all of the functioning servers will be tried. If a successful response could not be obtained from any of the servers, the client will receive the result of the communication with the last server.

", "module": "ngx_http_upstream_module", "link": "http/ngx_http_upstream_module.html#upstream", "name": "upstream" }, { "table": "
Syntax:server address [parameters];
Default:—
Context:upstream
", "doc": "

Defines the address and other parameters of a server. The address can be specified as a domain name or IP address, with an optional port, or as a UNIX-domain socket path specified after the “unix:” prefix. If a port is not specified, the port 80 is used. A domain name that resolves to several IP addresses defines multiple servers at once.

The following parameters can be defined:

weight=number
sets the weight of the server, by default, 1.
max_conns=number
limits the maximum number of simultaneous active connections to the proxied server (1.11.5). Default value is zero, meaning there is no limit. If the server group does not reside in the shared memory, the limitation works per each worker process.
If idle keepalive connections, multiple workers, and the shared memory are enabled, the total number of active and idle connections to the proxied server may exceed the max_conns value.
Since version 1.5.9 and prior to version 1.11.5, this parameter was available as part of our commercial subscription.
max_fails=number
sets the number of unsuccessful attempts to communicate with the server that should happen in the duration set by the fail_timeout parameter to consider the server unavailable for a duration also set by the fail_timeout parameter. By default, the number of unsuccessful attempts is set to 1. The zero value disables the accounting of attempts. What is considered an unsuccessful attempt is defined by the proxy_next_upstream, fastcgi_next_upstream, uwsgi_next_upstream, scgi_next_upstream, memcached_next_upstream, and grpc_next_upstream directives.
fail_timeout=time
setsBy default, the parameter is set to 10 seconds.
backup
marks the server as a backup server. It will be passed requests when the primary servers are unavailable.
down
marks the server as permanently unavailable.

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

resolve
monitors changes of the IP addresses that correspond to a domain name of the server, and automatically modifies the upstream configuration without the need of restarting nginx (1.5.12). The server group must reside in the shared memory.

In order for this parameter to work, the resolver directive must be specified in the http block. Example:

\nhttp {\n    resolver 10.0.0.1;\n\n    upstream u {\n        zone ...;\n        ...\n        server example.com resolve;\n    }\n}\n

route=string
sets the server route name.
service=name
enables resolving of DNS SRV records and sets the service name (1.9.13). In order for this parameter to work, it is necessary to specify the resolve parameter for the server and specify a hostname without a port number.

If the service name does not contain a dot (“.”), then the RFC-compliant name is constructed and the TCP protocol is added to the service prefix. For example, to look up the _http._tcp.backend.example.com SRV record, it is necessary to specify the directive:

\nserver backend.example.com service=http resolve;\n

If the service name contains one or more dots, then the name is constructed by joining the service prefix and the server name. For example, to look up the _http._tcp.backend.example.com and server1.backend.example.com SRV records, it is necessary to specify the directives:

\nserver backend.example.com service=_http._tcp resolve;\nserver example.com service=server1.backend resolve;\n

Highest-priority SRV records (records with the same lowest-number priority value) are resolved as primary servers, the rest of SRV records are resolved as backup servers. If the backup parameter is specified for the server, high-priority SRV records are resolved as backup servers, the rest of SRV records are ignored.

slow_start=time
sets the time during which the server will recover its weight from zero to a nominal value, when unhealthy server becomes healthy, or when the server becomes available after a period of time it was considered unavailable. Default value is zero, i.e. slow start is disabled.
The parameter cannot be used along with the hash and ip_hash load balancing methods.
drain
puts the server into the “draining” mode (1.13.6). In this mode, only requests bound to the server will be proxied to it.
Prior to version 1.13.6, the parameter could be changed only with the API module.
If there is only a single server in a group, max_fails, fail_timeout and slow_start parameters are ignored, and such a server will never be considered unavailable.
", "module": "ngx_http_upstream_module", "link": "http/ngx_http_upstream_module.html#server", "name": "server" }, { "table": "
Syntax:zone name [size];
Default:—
Context:upstream

This directive appeared in version 1.9.0.

", "doc": "

Defines the name and size of the shared memory zone that keeps the group’s configuration and run-time state that are shared between worker processes. Several groups may share the same zone. In this case, it is enough to specify the size only once.

Additionally, as part of our commercial subscription, such groups allow changing the group membership or modifying the settings of a particular server without the need of restarting nginx. The configuration is accessible via the API module (1.13.3).

Prior to version 1.13.3, the configuration was accessible only via a special location handled by upstream_conf.
", "module": "ngx_http_upstream_module", "link": "http/ngx_http_upstream_module.html#zone", "name": "zone" }, { "table": "
Syntax:state file;
Default:—
Context:upstream

This directive appeared in version 1.9.7.

", "doc": "

Specifies a file that keeps the state of the dynamically configurable group.

Examples:

\nstate /var/lib/nginx/state/servers.conf; # path for Linux\nstate /var/db/nginx/state/servers.conf;  # path for FreeBSD\n

The state is currently limited to the list of servers with their parameters. The file is read when parsing the configuration and is updated each time the upstream configuration is changed. Changing the file content directly should be avoided. The directive cannot be used along with the server directive.

Changes made during configuration reload or binary upgrade can be lost.
This directive is available as part of our commercial subscription.
", "module": "ngx_http_upstream_module", "link": "http/ngx_http_upstream_module.html#state", "name": "state" }, { "table": "
Syntax:hash key [consistent];
Default:—
Context:upstream

This directive appeared in version 1.7.2.

", "doc": "

Specifies a load balancing method for a server group where the client-server mapping is based on the hashed key value. The key can contain text, variables, and their combinations. Note that adding or removing a server from the group may result in remapping most of the keys to different servers. The method is compatible with the Cache::Memcached Perl library.

If the consistent parameter is specified the ketama consistent hashing method will be used instead. The method ensures that only a few keys will be remapped to different servers when a server is added to or removed from the group. This helps to achieve a higher cache hit ratio for caching servers. The method is compatible with the Cache::Memcached::Fast Perl library with the ketama_points parameter set to 160.

", "module": "ngx_http_upstream_module", "link": "http/ngx_http_upstream_module.html#hash", "name": "hash" }, { "table": "
Syntax:ip_hash;
Default:—
Context:upstream
", "doc": "

Specifies that a group should use a load balancing method where requests are distributed between servers based on client IP addresses. The first three octets of the client IPv4 address, or the entire IPv6 address, are used as a hashing key. The method ensures that requests from the same client will always be passed to the same server except when this server is unavailable. In the latter case client requests will be passed to another server. Most probably, it will always be the same server as well.

IPv6 addresses are supported starting from versions 1.3.2 and 1.2.2.

If one of the servers needs to be temporarily removed, it should be marked with the down parameter in order to preserve the current hashing of client IP addresses.

Example:

\nupstream backend {\n    ip_hash;\n\n    server backend1.example.com;\n    server backend2.example.com;\n    server backend3.example.com down;\n    server backend4.example.com;\n}\n
Until versions 1.3.1 and 1.2.2, it was not possible to specify a weight for servers using the ip_hash load balancing method.
", "module": "ngx_http_upstream_module", "link": "http/ngx_http_upstream_module.html#ip_hash", "name": "ip_hash" }, { "table": "
Syntax:keepalive connections;
Default:—
Context:upstream

This directive appeared in version 1.1.4.

", "doc": "

Activates the cache for connections to upstream servers.

The connections parameter sets the maximum number of idle keepalive connections to upstream servers that are preserved in the cache of each worker process. When this number is exceeded, the least recently used connections are closed.

It should be particularly noted that the keepalive directive does not limit the total number of connections to upstream servers that an nginx worker process can open. The connections parameter should be set to a number small enough to let upstream servers process new incoming connections as well.

Example configuration of memcached upstream with keepalive connections:

\nupstream memcached_backend {\n    server 127.0.0.1:11211;\n    server 10.0.0.2:11211;\n\n    keepalive 32;\n}\n\nserver {\n    ...\n\n    location /memcached/ {\n        set $memcached_key $uri;\n        memcached_pass memcached_backend;\n    }\n\n}\n

For HTTP, the proxy_http_version directive should be set to “1.1” and the “Connection” header field should be cleared:

\nupstream http_backend {\n    server 127.0.0.1:8080;\n\n    keepalive 16;\n}\n\nserver {\n    ...\n\n    location /http/ {\n        proxy_pass http://http_backend;\n        proxy_http_version 1.1;\n        proxy_set_header Connection "";\n        ...\n    }\n}\n
Alternatively, HTTP/1.0 persistent connections can be used by passing the “Connection: Keep-Alive” header field to an upstream server, though this method is not recommended.

For FastCGI servers, it is required to set fastcgi_keep_conn for keepalive connections to work:

\nupstream fastcgi_backend {\n    server 127.0.0.1:9000;\n\n    keepalive 8;\n}\n\nserver {\n    ...\n\n    location /fastcgi/ {\n        fastcgi_pass fastcgi_backend;\n        fastcgi_keep_conn on;\n        ...\n    }\n}\n
When using load balancer methods other than the default round-robin method, it is necessary to activate them before the keepalive directive.
SCGI and uwsgi protocols do not have a notion of keepalive connections.
", "module": "ngx_http_upstream_module", "link": "http/ngx_http_upstream_module.html#keepalive", "name": "keepalive" }, { "table": "
Syntax:ntlm;
Default:—
Context:upstream

This directive appeared in version 1.9.2.

", "doc": "

Allows proxying requests with NTLM Authentication. The upstream connection is bound to the client connection once the client sends a request with the “Authorization” header field value starting with “Negotiate” or “NTLM”. Further client requests will be proxied through the same upstream connection, keeping the authentication context.

In order for NTLM authentication to work, it is necessary to enable keepalive connections to upstream servers. The proxy_http_version directive should be set to “1.1” and the “Connection” header field should be cleared:

\nupstream http_backend {\n    server 127.0.0.1:8080;\n\n    ntlm;\n}\n\nserver {\n    ...\n\n    location /http/ {\n        proxy_pass http://http_backend;\n        proxy_http_version 1.1;\n        proxy_set_header Connection "";\n        ...\n    }\n}\n
When using load balancer methods other than the default round-robin method, it is necessary to activate them before the ntlm directive.
This directive is available as part of our commercial subscription.
", "module": "ngx_http_upstream_module", "link": "http/ngx_http_upstream_module.html#ntlm", "name": "ntlm" }, { "table": "
Syntax:least_conn;
Default:—
Context:upstream

This directive appeared in versions 1.3.1 and 1.2.2.

", "doc": "

Specifies that a group should use a load balancing method where a request is passed to the server with the least number of active connections, taking into account weights of servers. If there are several such servers, they are tried in turn using a weighted round-robin balancing method.

", "module": "ngx_http_upstream_module", "link": "http/ngx_http_upstream_module.html#least_conn", "name": "least_conn" }, { "table": "
Syntax:least_time header | last_byte [inflight];
Default:—
Context:upstream

This directive appeared in version 1.7.10.

", "doc": "

Specifies that a group should use a load balancing method where a request is passed to the server with the least average response time and least number of active connections, taking into account weights of servers. If there are several such servers, they are tried in turn using a weighted round-robin balancing method.

If the header parameter is specified, time to receive the response header is used. If the last_byte parameter is specified, time to receive the full response is used. If the inflight parameter is specified (1.11.6), incomplete requests are also taken into account.

Prior to version 1.11.6, incomplete requests were taken into account by default.
This directive is available as part of our commercial subscription.
", "module": "ngx_http_upstream_module", "link": "http/ngx_http_upstream_module.html#least_time", "name": "least_time" }, { "table": "
Syntax:queue number [timeout=time];
Default:—
Context:upstream

This directive appeared in version 1.5.12.

", "doc": "

If an upstream server cannot be selected immediately while processing a request, the request will be placed into the queue. The directive specifies the maximum number of requests that can be in the queue at the same time. If the queue is filled up, or the server to pass the request to cannot be selected within the time period specified in the timeout parameter, the 502 (Bad Gateway) error will be returned to the client.

The default value of the timeout parameter is 60 seconds.

When using load balancer methods other than the default round-robin method, it is necessary to activate them before the queue directive.
This directive is available as part of our commercial subscription.
", "module": "ngx_http_upstream_module", "link": "http/ngx_http_upstream_module.html#queue", "name": "queue" }, { "table": "
Syntax:random [two [method]];
Default:—
Context:upstream

This directive appeared in version 1.15.1.

", "doc": "

Specifies that a group should use a load balancing method where a request is passed to a randomly selected server, taking into account weights of servers.

The optional two parameter instructs nginx to randomly select two servers and then choose a server using the specified method. The default method is least_conn which passes a request to a server with the least number of active connections.

", "module": "ngx_http_upstream_module", "link": "http/ngx_http_upstream_module.html#random", "name": "random" }, { "table": "
Syntax:sticky cookie name [expires=time] [domain=domain] [httponly] [secure] [path=path];
sticky route $variable ...;
sticky learn create=$variable lookup=$variable zone=name:size [timeout=time] [header] [sync];
Default:—
Context:upstream

This directive appeared in version 1.5.7.

", "doc": "

Enables session affinity, which causes requests from the same client to be passed to the same server in a group of servers. Three methods are available:

cookie

When the cookie method is used, information about the designated server is passed in an HTTP cookie generated by nginx:

\nupstream backend {\n    server backend1.example.com;\n    server backend2.example.com;\n\n    sticky cookie srv_id expires=1h domain=.example.com path=/;\n}\n

A request that comes from a client not yet bound to a particular server is passed to the server selected by the configured balancing method. Further requests with this cookie will be passed to the designated server. If the designated server cannot process a request, the new server is selected as if the client has not been bound yet.

The first parameter sets the name of the cookie to be set or inspected. The cookie value is a hexadecimal representation of the MD5 hash of the IP address and port, or of the UNIX-domain socket path. However, if the “route” parameter of the server directive is specified, the cookie value will be the value of the “route” parameter:

\nupstream backend {\n    server backend1.example.com route=a;\n    server backend2.example.com route=b;\n\n    sticky cookie srv_id expires=1h domain=.example.com path=/;\n}\n

In this case, the value of the “srv_id” cookie will be either a or b.

Additional parameters may be as follows:

expires=time
Sets the time for which a browser should keep the cookie. The special value max will cause the cookie to expire on “31 Dec 2037 23:55:55 GMT”. If the parameter is not specified, it will cause the cookie to expire at the end of a browser session.
domain=domain
Defines the domain for which the cookie is set. Parameter value can contain variables (1.11.5).
httponly
Adds the HttpOnly attribute to the cookie (1.7.11).
secure
Adds the Secure attribute to the cookie (1.7.11).
path=path
Defines the path for which the cookie is set.

If any parameters are omitted, the corresponding cookie fields are not set.

route

When the route method is used, proxied server assigns client a route on receipt of the first request. All subsequent requests from this client will carry routing information in a cookie or URI. This information is compared with the “route” parameter of the server directive to identify the server to which the request should be proxied. If the “route” parameter is not specified, the route name will be a hexadecimal representation of the MD5 hash of the IP address and port, or of the UNIX-domain socket path. If the designated server cannot process a request, the new server is selected by the configured balancing method as if there is no routing information in the request.

The parameters of the route method specify variables that may contain routing information. The first non-empty variable is used to find the matching server.

Example:

\nmap $cookie_jsessionid $route_cookie {\n    ~.+\\.(?P<route>\\w+)$ $route;\n}\n\nmap $request_uri $route_uri {\n    ~jsessionid=.+\\.(?P<route>\\w+)$ $route;\n}\n\nupstream backend {\n    server backend1.example.com route=a;\n    server backend2.example.com route=b;\n\n    sticky route $route_cookie $route_uri;\n}\n

Here, the route is taken from the “JSESSIONID” cookie if present in a request. Otherwise, the route from the URI is used.

learn

When the learn method (1.7.1) is used, nginx analyzes upstream server responses and learns server-initiated sessions usually passed in an HTTP cookie.

\nupstream backend {\n   server backend1.example.com:8080;\n   server backend2.example.com:8081;\n\n   sticky learn\n          create=$upstream_cookie_examplecookie\n          lookup=$cookie_examplecookie\n          zone=client_sessions:1m;\n}\n

In the example, the upstream server creates a session by setting the cookie “EXAMPLECOOKIE” in the response. Further requests with this cookie will be passed to the same server. If the server cannot process the request, the new server is selected as if the client has not been bound yet.

The parameters create and lookup specify variables that indicate how new sessions are created and existing sessions are searched, respectively. Both parameters may be specified more than once, in which case the first non-empty variable is used.

Sessions are stored in a shared memory zone, whose name and size are configured by the zone parameter. One megabyte zone can store about 4000 sessions on the 64-bit platform. The sessions that are not accessed during the time specified by the timeout parameter get removed from the zone. By default, timeout is set to 10 minutes.

The header parameter (1.13.1) allows creating a session right after receiving response headers from the upstream server.

The sync parameter (1.13.8) enables synchronization of the shared memory zone.

This directive is available as part of our commercial subscription.
", "module": "ngx_http_upstream_module", "link": "http/ngx_http_upstream_module.html#sticky", "name": "sticky" }, { "table": "
Syntax:sticky_cookie_insert name [expires=time] [domain=domain] [path=path];
Default:—
Context:upstream
", "doc": "

This directive is obsolete since version 1.5.7. An equivalent sticky directive with a new syntax should be used instead:

sticky cookie name [expires=time] [domain=domain] [path=path];
", "module": "ngx_http_upstream_module", "link": "http/ngx_http_upstream_module.html#sticky_cookie_insert", "name": "sticky_cookie_insert" }, { "table": "
Syntax:upstream_conf;
Default:—
Context:location
", "doc": "

Turns on the HTTP interface of upstream configuration in the surrounding location. Access to this location should be limited.

Configuration commands can be used to:

", "module": "ngx_http_upstream_conf_module", "link": "http/ngx_http_upstream_conf_module.html#upstream_conf", "name": "upstream_conf" }, { "table": "
Syntax:health_check [parameters];
Default:—
Context:location
", "doc": "

Enables periodic health checks of the servers in a group referenced in the surrounding location.

The following optional parameters are supported:

interval=time
sets the interval between two consecutive health checks, by default, 5 seconds.
jitter=time
sets the time within which each health check will be randomly delayed, by default, there is no delay.
fails=number
sets the number of consecutive failed health checks of a particular server after which this server will be considered unhealthy, by default, 1.
passes=number
sets the number of consecutive passed health checks of a particular server after which the server will be considered healthy, by default, 1.
uri=uri
defines the URI used in health check requests, by default, “/”.
mandatory
sets the initial “checking” state for a server until the first health check is completed (1.11.7). Client requests are not passed to servers in the “checking” state. If the parameter is not specified, the server will be initially considered healthy.
match=name
specifies the match block configuring the tests that a response should pass in order for a health check to pass. By default, the response should have status code 2xx or 3xx.
port=number
defines the port used when connecting to a server to perform a health check (1.9.7). By default, equals the server port.
", "module": "ngx_http_upstream_hc_module", "link": "http/ngx_http_upstream_hc_module.html#health_check", "name": "health_check" }, { "table": "
Syntax:match name { ... }
Default:—
Context:http
", "doc": "

Defines the named test set used to verify responses to health check requests.

The following items can be tested in a response:

status 200;
status is 200
status ! 500;
status is not 500
status 200 204;
status is 200 or 204
status ! 301 302;
status is neither 301 nor 302
status 200-399;
status is in the range from 200 to 399
status ! 400-599;
status is not in the range from 400 to 599
status 301-303 307;
status is either 301, 302, 303, or 307
header Content-Type = text/html;
header contains “Content-Type” with value text/html
header Content-Type != text/html;
header contains “Content-Type” with value other than text/html
header Connection ~ close;
header contains “Connection” with value matching regular expression close
header Connection !~ close;
header contains “Connection” with value not matching regular expression close
header Host;
header contains “Host”
header ! X-Accel-Redirect;
header lacks “X-Accel-Redirect”
body ~ "Welcome to nginx!";
body matches regular expression “Welcome to nginx!”
body !~ "Welcome to nginx!";
body does not match regular expression “Welcome to nginx!”

If several tests are specified, the response matches only if it matches all tests.

Only the first 256k of the response body are examined.

Examples:

\n# status is 200, content type is "text/html",\n# and body contains "Welcome to nginx!"\nmatch welcome {\n    status 200;\n    header Content-Type = text/html;\n    body ~ "Welcome to nginx!";\n}\n
\n# status is not one of 301, 302, 303, or 307, and header does not have "Refresh:"\nmatch not_redirect {\n    status ! 301-303 307;\n    header ! Refresh;\n}\n
\n# status ok and not in maintenance mode\nmatch server_ok {\n    status 200-399;\n    body !~ "maintenance mode";\n}\n
", "module": "ngx_http_upstream_hc_module", "link": "http/ngx_http_upstream_hc_module.html#match", "name": "match" }, { "table": "
Syntax:userid on | v1 | log | off;
Default:
userid off;
Context:http, server, location
", "doc": "

Enables or disables setting cookies and logging the received cookies:

on
enables the setting of version 2 cookies and logging of the received cookies;
v1
enables the setting of version 1 cookies and logging of the received cookies;
log
disables the setting of cookies, but enables logging of the received cookies;
off
disables the setting of cookies and logging of the received cookies.
", "module": "ngx_http_userid_module", "link": "http/ngx_http_userid_module.html#userid", "name": "userid" }, { "table": "
Syntax:userid_domain name | none;
Default:
userid_domain none;
Context:http, server, location
", "doc": "

Defines a domain for which the cookie is set. The none parameter disables setting of a domain for the cookie.

", "module": "ngx_http_userid_module", "link": "http/ngx_http_userid_module.html#userid_domain", "name": "userid_domain" }, { "table": "
Syntax:userid_expires time | max | off;
Default:
userid_expires off;
Context:http, server, location
", "doc": "

Sets a time during which a browser should keep the cookie. The parameter max will cause the cookie to expire on “31 Dec 2037 23:55:55 GMT”. The parameter off will cause the cookie to expire at the end of a browser session.

", "module": "ngx_http_userid_module", "link": "http/ngx_http_userid_module.html#userid_expires", "name": "userid_expires" }, { "table": "
Syntax:userid_mark letter | digit | = | off;
Default:
userid_mark off;
Context:http, server, location
", "doc": "

If the parameter is not off, enables the cookie marking mechanism and sets the character used as a mark. This mechanism is used to add or change userid_p3p and/or a cookie expiration time while preserving the client identifier. A mark can be any letter of the English alphabet (case-sensitive), digit, or the “=” character.

If the mark is set, it is compared with the first padding symbol in the base64 representation of the client identifier passed in a cookie. If they do not match, the cookie is resent with the specified mark, expiration time, and “P3P” header.

", "module": "ngx_http_userid_module", "link": "http/ngx_http_userid_module.html#userid_mark", "name": "userid_mark" }, { "table": "
Syntax:userid_name name;
Default:
userid_name uid;
Context:http, server, location
", "doc": "

Sets the cookie name.

", "module": "ngx_http_userid_module", "link": "http/ngx_http_userid_module.html#userid_name", "name": "userid_name" }, { "table": "
Syntax:userid_p3p string | none;
Default:
userid_p3p none;
Context:http, server, location
", "doc": "

Sets a value for the “P3P” header field that will be sent along with the cookie. If the directive is set to the special value none, the “P3P” header will not be sent in a response.

", "module": "ngx_http_userid_module", "link": "http/ngx_http_userid_module.html#userid_p3p", "name": "userid_p3p" }, { "table": "
Syntax:userid_path path;
Default:
userid_path /;
Context:http, server, location
", "doc": "

Defines a path for which the cookie is set.

", "module": "ngx_http_userid_module", "link": "http/ngx_http_userid_module.html#userid_path", "name": "userid_path" }, { "table": "
Syntax:userid_service number;
Default:
userid_service IP address of the server;
Context:http, server, location
", "doc": "

If identifiers are issued by multiple servers (services), each service should be assigned its own number to ensure that client identifiers are unique. For version 1 cookies, the default value is zero. For version 2 cookies, the default value is the number composed from the last four octets of the server’s IP address.

", "module": "ngx_http_userid_module", "link": "http/ngx_http_userid_module.html#userid_service", "name": "userid_service" }, { "table": "
Syntax:uwsgi_bind address [transparent] | off;
Default:—
Context:http, server, location
", "doc": "

Makes outgoing connections to a uwsgi 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 uwsgi_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address and port.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_bind", "name": "uwsgi_bind" }, { "table": "
Syntax:uwsgi_buffer_size size;
Default:
uwsgi_buffer_size 4k|8k;
Context:http, server, location
", "doc": "

Sets the size of the buffer used for reading the first part of the response received from the uwsgi 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.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_buffer_size", "name": "uwsgi_buffer_size" }, { "table": "
Syntax:uwsgi_buffering on | off;
Default:
uwsgi_buffering on;
Context:http, server, location
", "doc": "

Enables or disables buffering of responses from the uwsgi server.

When buffering is enabled, nginx receives a response from the uwsgi server as soon as possible, saving it into the buffers set by the uwsgi_buffer_size and uwsgi_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 uwsgi_max_temp_file_size and uwsgi_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 uwsgi server. The maximum size of the data that nginx can receive from the server at a time is set by the uwsgi_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 uwsgi_ignore_headers directive.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_buffering", "name": "uwsgi_buffering" }, { "table": "
Syntax:uwsgi_buffers number size;
Default:
uwsgi_buffers 8 4k|8k;
Context:http, server, location
", "doc": "

Sets the number and size of the buffers used for reading a response from the uwsgi 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.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_buffers", "name": "uwsgi_buffers" }, { "table": "
Syntax:uwsgi_busy_buffers_size size;
Default:
uwsgi_busy_buffers_size 8k|16k;
Context:http, server, location
", "doc": "

When buffering of responses from the uwsgi 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 uwsgi_buffer_size and uwsgi_buffers directives.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_busy_buffers_size", "name": "uwsgi_busy_buffers_size" }, { "table": "
Syntax:uwsgi_cache zone | off;
Default:
uwsgi_cache off;
Context:http, server, location
", "doc": "

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.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_cache", "name": "uwsgi_cache" }, { "table": "
Syntax:uwsgi_cache_background_update on | off;
Default:
uwsgi_cache_background_update off;
Context:http, server, location

This directive appeared in version 1.11.10.

", "doc": "

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.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_cache_background_update", "name": "uwsgi_cache_background_update" }, { "table": "
Syntax:uwsgi_cache_bypass string ...;
Default:—
Context:http, server, location
", "doc": "

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:

\nuwsgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;\nuwsgi_cache_bypass $http_pragma    $http_authorization;\n

Can be used along with the uwsgi_no_cache directive.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_cache_bypass", "name": "uwsgi_cache_bypass" }, { "table": "
Syntax:uwsgi_cache_key string;
Default:—
Context:http, server, location
", "doc": "

Defines a key for caching, for example

\nuwsgi_cache_key localhost:9000$request_uri;\n
", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_cache_key", "name": "uwsgi_cache_key" }, { "table": "
Syntax:uwsgi_cache_lock on | off;
Default:
uwsgi_cache_lock off;
Context:http, server, location

This directive appeared in version 1.1.12.

", "doc": "

When enabled, only one request at a time will be allowed to populate a new cache element identified according to the uwsgi_cache_key directive by passing a request to a uwsgi 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 uwsgi_cache_lock_timeout directive.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_cache_lock", "name": "uwsgi_cache_lock" }, { "table": "
Syntax:uwsgi_cache_lock_age time;
Default:
uwsgi_cache_lock_age 5s;
Context:http, server, location

This directive appeared in version 1.7.8.

", "doc": "

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_cache_lock_age", "name": "uwsgi_cache_lock_age" }, { "table": "
Syntax:uwsgi_cache_lock_timeout time;
Default:
uwsgi_cache_lock_timeout 5s;
Context:http, server, location

This directive appeared in version 1.1.12.

", "doc": "

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

Before 1.7.8, the response could be cached.
", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_cache_lock_timeout", "name": "uwsgi_cache_lock_timeout" }, { "table": "
Syntax:uwsgi_cache_max_range_offset number;
Default:—
Context:http, server, location

This directive appeared in version 1.11.6.

", "doc": "

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_cache_max_range_offset", "name": "uwsgi_cache_max_range_offset" }, { "table": "
Syntax:uwsgi_cache_methods GET | HEAD | POST ...;
Default:
uwsgi_cache_methods GET HEAD;
Context:http, server, location
", "doc": "

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 uwsgi_no_cache directive.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_cache_methods", "name": "uwsgi_cache_methods" }, { "table": "
Syntax:uwsgi_cache_min_uses number;
Default:
uwsgi_cache_min_uses 1;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_cache_min_uses", "name": "uwsgi_cache_min_uses" }, { "table": "
Syntax:uwsgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time];
Default:—
Context:http
", "doc": "

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

\nuwsgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;\n

file names in a cache will look like this:

\n/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c\n

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. A 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 uwsgi_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.

As part of commercial subscription, the shared memory zone also stores extended cache information, thus, it is required to specify a larger zone size for the same number of keys. For example, one megabyte zone can store about 4 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. When this size is exceeded, 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.
In versions 1.7.3, 1.7.7, and 1.11.10 cache header format has been changed. Previously cached responses will be considered invalid after upgrading to a newer nginx version.
", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_cache_path", "name": "uwsgi_cache_path" }, { "table": "
Syntax:uwsgi_cache_purge string ...;
Default:—
Context:http, server, location

This directive appeared in version 1.5.7.

", "doc": "

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.

Example configuration:

\nuwsgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;\n\nmap $request_method $purge_method {\n    PURGE   1;\n    default 0;\n}\n\nserver {\n    ...\n    location / {\n        uwsgi_pass        backend;\n        uwsgi_cache       cache_zone;\n        uwsgi_cache_key   $uri;\n        uwsgi_cache_purge $purge_method;\n    }\n}\n
This functionality is available as part of our commercial subscription.
", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_cache_purge", "name": "uwsgi_cache_purge" }, { "table": "
Syntax:uwsgi_cache_revalidate on | off;
Default:
uwsgi_cache_revalidate off;
Context:http, server, location

This directive appeared in version 1.5.7.

", "doc": "

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_cache_revalidate", "name": "uwsgi_cache_revalidate" }, { "table": "
Syntax:uwsgi_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_503 | http_403 | http_404 | http_429 | off ...;
Default:
uwsgi_cache_use_stale off;
Context:http, server, location
", "doc": "

Determines in which cases a stale cached response can be used when an error occurs during communication with the uwsgi server. The directive’s parameters match the parameters of the uwsgi_next_upstream directive.

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_cache_use_stale", "name": "uwsgi_cache_use_stale" }, { "table": "
Syntax:uwsgi_cache_valid [code ...] time;
Default:—
Context:http, server, location
", "doc": "

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

\nuwsgi_cache_valid 200 302 10m;\nuwsgi_cache_valid 404      1m;\n

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

\nuwsgi_cache_valid 5m;\n

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

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

\nuwsgi_cache_valid 200 302 10m;\nuwsgi_cache_valid 301      1h;\nuwsgi_cache_valid any      1m;\n

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_cache_valid", "name": "uwsgi_cache_valid" }, { "table": "
Syntax:uwsgi_connect_timeout time;
Default:
uwsgi_connect_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_connect_timeout", "name": "uwsgi_connect_timeout" }, { "table": "
Syntax:uwsgi_force_ranges on | off;
Default:
uwsgi_force_ranges off;
Context:http, server, location

This directive appeared in version 1.7.7.

", "doc": "

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_force_ranges", "name": "uwsgi_force_ranges" }, { "table": "
Syntax:uwsgi_hide_header field;
Default:—
Context:http, server, location
", "doc": "

By default, nginx does not pass the header fields “Status” and “X-Accel-...” from the response of a uwsgi server to a client. The uwsgi_hide_header directive sets additional fields that will not be passed. If, on the contrary, the passing of fields needs to be permitted, the uwsgi_pass_header directive can be used.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_hide_header", "name": "uwsgi_hide_header" }, { "table": "
Syntax:uwsgi_ignore_client_abort on | off;
Default:
uwsgi_ignore_client_abort off;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_ignore_client_abort", "name": "uwsgi_ignore_client_abort" }, { "table": "
Syntax:uwsgi_ignore_headers field ...;
Default:—
Context:http, server, location
", "doc": "

Disables processing of certain response header fields from the uwsgi 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:

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_ignore_headers", "name": "uwsgi_ignore_headers" }, { "table": "
Syntax:uwsgi_intercept_errors on | off;
Default:
uwsgi_intercept_errors off;
Context:http, server, location
", "doc": "

Determines whether a uwsgi server 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.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_intercept_errors", "name": "uwsgi_intercept_errors" }, { "table": "
Syntax:uwsgi_limit_rate rate;
Default:
uwsgi_limit_rate 0;
Context:http, server, location

This directive appeared in version 1.7.7.

", "doc": "

Limits the speed of reading the response from the uwsgi 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 uwsgi server, the overall rate will be twice as much as the specified limit. The limitation works only if buffering of responses from the uwsgi server is enabled.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_limit_rate", "name": "uwsgi_limit_rate" }, { "table": "
Syntax:uwsgi_max_temp_file_size size;
Default:
uwsgi_max_temp_file_size 1024m;
Context:http, server, location
", "doc": "

When buffering of responses from the uwsgi server is enabled, and the whole response does not fit into the buffers set by the uwsgi_buffer_size and uwsgi_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 uwsgi_temp_file_write_size directive.

The zero value disables buffering of responses to temporary files.

This restriction does not apply to responses that will be cached or stored on disk.
", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_max_temp_file_size", "name": "uwsgi_max_temp_file_size" }, { "table": "
Syntax:uwsgi_modifier1 number;
Default:
uwsgi_modifier1 0;
Context:http, server, location
", "doc": "

Sets the value of the modifier1 field in the uwsgi packet header.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_modifier1", "name": "uwsgi_modifier1" }, { "table": "
Syntax:uwsgi_modifier2 number;
Default:
uwsgi_modifier2 0;
Context:http, server, location
", "doc": "

Sets the value of the modifier2 field in the uwsgi packet header.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_modifier2", "name": "uwsgi_modifier2" }, { "table": "
Syntax:uwsgi_next_upstream error | timeout | invalid_header | http_500 | http_503 | http_403 | http_404 | http_429 | non_idempotent | off ...;
Default:
uwsgi_next_upstream error timeout;
Context:http, server, location
", "doc": "

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_503
a server returned a response with the code 503;
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_503, 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.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_next_upstream", "name": "uwsgi_next_upstream" }, { "table": "
Syntax:uwsgi_next_upstream_timeout time;
Default:
uwsgi_next_upstream_timeout 0;
Context:http, server, location

This directive appeared in version 1.7.5.

", "doc": "

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_next_upstream_timeout", "name": "uwsgi_next_upstream_timeout" }, { "table": "
Syntax:uwsgi_next_upstream_tries number;
Default:
uwsgi_next_upstream_tries 0;
Context:http, server, location

This directive appeared in version 1.7.5.

", "doc": "

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_next_upstream_tries", "name": "uwsgi_next_upstream_tries" }, { "table": "
Syntax:uwsgi_no_cache string ...;
Default:—
Context:http, server, location
", "doc": "

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:

\nuwsgi_no_cache $cookie_nocache $arg_nocache$arg_comment;\nuwsgi_no_cache $http_pragma    $http_authorization;\n

Can be used along with the uwsgi_cache_bypass directive.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_no_cache", "name": "uwsgi_no_cache" }, { "table": "
Syntax:uwsgi_param parameter value [if_not_empty];
Default:—
Context:http, server, location
", "doc": "

Sets a parameter that should be passed to the uwsgi server. The value can contain text, variables, and their combination. These directives are inherited from the previous level if and only if there are no uwsgi_param directives defined on the current level.

Standard CGI environment variables should be provided as uwsgi headers, see the uwsgi_params file provided in the distribution:

\nlocation / {\n    include uwsgi_params;\n    ...\n}\n

If the directive is specified with if_not_empty (1.1.11) then such a parameter will be passed to the server only if its value is not empty:

\nuwsgi_param HTTPS $https if_not_empty;\n
", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_param", "name": "uwsgi_param" }, { "table": "
Syntax:uwsgi_pass [protocol://]address;
Default:—
Context:location, if in location
", "doc": "

Sets the protocol and address of a uwsgi server. As a protocol, “uwsgi” or “suwsgi” (secured uwsgi, uwsgi over SSL) can be specified. The address can be specified as a domain name or IP address, and a port:

\nuwsgi_pass localhost:9000;\nuwsgi_pass uwsgi://localhost:9000;\nuwsgi_pass suwsgi://[2001:db8::1]:9090;\n

or as a UNIX-domain socket path:

\nuwsgi_pass unix:/tmp/uwsgi.socket;\n

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.

Secured uwsgi protocol is supported since version 1.5.8.
", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_pass", "name": "uwsgi_pass" }, { "table": "
Syntax:uwsgi_pass_header field;
Default:—
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_pass_header", "name": "uwsgi_pass_header" }, { "table": "
Syntax:uwsgi_pass_request_body on | off;
Default:
uwsgi_pass_request_body on;
Context:http, server, location
", "doc": "

Indicates whether the original request body is passed to the uwsgi server. See also the uwsgi_pass_request_headers directive.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_pass_request_body", "name": "uwsgi_pass_request_body" }, { "table": "
Syntax:uwsgi_pass_request_headers on | off;
Default:
uwsgi_pass_request_headers on;
Context:http, server, location
", "doc": "

Indicates whether the header fields of the original request are passed to the uwsgi server. See also the uwsgi_pass_request_body directive.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_pass_request_headers", "name": "uwsgi_pass_request_headers" }, { "table": "
Syntax:uwsgi_read_timeout time;
Default:
uwsgi_read_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_read_timeout", "name": "uwsgi_read_timeout" }, { "table": "
Syntax:uwsgi_request_buffering on | off;
Default:
uwsgi_request_buffering on;
Context:http, server, location

This directive appeared in version 1.7.11.

", "doc": "

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 uwsgi server.

When buffering is disabled, the request body is sent to the uwsgi 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.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_request_buffering", "name": "uwsgi_request_buffering" }, { "table": "
Syntax:uwsgi_send_timeout time;
Default:
uwsgi_send_timeout 60s;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_send_timeout", "name": "uwsgi_send_timeout" }, { "table": "
Syntax:uwsgi_ssl_certificate file;
Default:—
Context:http, server, location

This directive appeared in version 1.7.8.

", "doc": "

Specifies a file with the certificate in the PEM format used for authentication to a secured uwsgi server.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_ssl_certificate", "name": "uwsgi_ssl_certificate" }, { "table": "
Syntax:uwsgi_ssl_certificate_key file;
Default:—
Context:http, server, location

This directive appeared in version 1.7.8.

", "doc": "

Specifies a file with the secret key in the PEM format used for authentication to a secured uwsgi 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.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_ssl_certificate_key", "name": "uwsgi_ssl_certificate_key" }, { "table": "
Syntax:uwsgi_ssl_ciphers ciphers;
Default:
uwsgi_ssl_ciphers DEFAULT;
Context:http, server, location

This directive appeared in version 1.5.8.

", "doc": "

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

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_ssl_ciphers", "name": "uwsgi_ssl_ciphers" }, { "table": "
Syntax:uwsgi_ssl_crl file;
Default:—
Context:http, server, location

This directive appeared in version 1.7.0.

", "doc": "

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_ssl_crl", "name": "uwsgi_ssl_crl" }, { "table": "
Syntax:uwsgi_ssl_name name;
Default:
uwsgi_ssl_name host from uwsgi_pass;
Context:http, server, location

This directive appeared in version 1.7.0.

", "doc": "

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

By default, the host part from uwsgi_pass is used.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_ssl_name", "name": "uwsgi_ssl_name" }, { "table": "
Syntax:uwsgi_ssl_password_file file;
Default:—
Context:http, server, location

This directive appeared in version 1.7.8.

", "doc": "

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.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_ssl_password_file", "name": "uwsgi_ssl_password_file" }, { "table": "
Syntax:uwsgi_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default:
uwsgi_ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
Context:http, server, location

This directive appeared in version 1.5.8.

", "doc": "

Enables the specified protocols for requests to a secured uwsgi server.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_ssl_protocols", "name": "uwsgi_ssl_protocols" }, { "table": "
Syntax:uwsgi_ssl_server_name on | off;
Default:
uwsgi_ssl_server_name off;
Context:http, server, location

This directive appeared in version 1.7.0.

", "doc": "

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_ssl_server_name", "name": "uwsgi_ssl_server_name" }, { "table": "
Syntax:uwsgi_ssl_session_reuse on | off;
Default:
uwsgi_ssl_session_reuse on;
Context:http, server, location

This directive appeared in version 1.5.8.

", "doc": "

Determines whether SSL sessions can be reused when working with a secured uwsgi server. If the errors “SSL3_GET_FINISHED:digest check failed” appear in the logs, try disabling session reuse.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_ssl_session_reuse", "name": "uwsgi_ssl_session_reuse" }, { "table": "
Syntax:uwsgi_ssl_trusted_certificate file;
Default:—
Context:http, server, location

This directive appeared in version 1.7.0.

", "doc": "

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_ssl_trusted_certificate", "name": "uwsgi_ssl_trusted_certificate" }, { "table": "
Syntax:uwsgi_ssl_verify on | off;
Default:
uwsgi_ssl_verify off;
Context:http, server, location

This directive appeared in version 1.7.0.

", "doc": "

Enables or disables verification of the secured uwsgi server certificate.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_ssl_verify", "name": "uwsgi_ssl_verify" }, { "table": "
Syntax:uwsgi_ssl_verify_depth number;
Default:
uwsgi_ssl_verify_depth 1;
Context:http, server, location

This directive appeared in version 1.7.0.

", "doc": "

Sets the verification depth in the secured uwsgi server certificates chain.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_ssl_verify_depth", "name": "uwsgi_ssl_verify_depth" }, { "table": "
Syntax:uwsgi_store on | off | string;
Default:
uwsgi_store off;
Context:http, server, location
", "doc": "

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:

\nuwsgi_store /data/www$original_uri;\n

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 uwsgi_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.:

\nlocation /images/ {\n    root               /data/www;\n    error_page         404 = /fetch$uri;\n}\n\nlocation /fetch/ {\n    internal;\n\n    uwsgi_pass         backend:9000;\n    ...\n\n    uwsgi_store        on;\n    uwsgi_store_access user:rw group:rw all:r;\n    uwsgi_temp_path    /data/temp;\n\n    alias              /data/www/;\n}\n
", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_store", "name": "uwsgi_store" }, { "table": "
Syntax:uwsgi_store_access users:permissions ...;
Default:
uwsgi_store_access user:rw;
Context:http, server, location
", "doc": "

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

\nuwsgi_store_access user:rw group:rw all:r;\n

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

\nuwsgi_store_access group:rw all:r;\n
", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_store_access", "name": "uwsgi_store_access" }, { "table": "
Syntax:uwsgi_temp_file_write_size size;
Default:
uwsgi_temp_file_write_size 8k|16k;
Context:http, server, location
", "doc": "

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

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_temp_file_write_size", "name": "uwsgi_temp_file_write_size" }, { "table": "
Syntax:uwsgi_temp_path path [level1 [level2 [level3]]];
Default:
uwsgi_temp_path uwsgi_temp;
Context:http, server, location
", "doc": "

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

\nuwsgi_temp_path /spool/nginx/uwsgi_temp 1 2;\n

a temporary file might look like this:

\n/spool/nginx/uwsgi_temp/7/45/00000123457\n

See also the use_temp_path parameter of the uwsgi_cache_path directive.

", "module": "ngx_http_uwsgi_module", "link": "http/ngx_http_uwsgi_module.html#uwsgi_temp_path", "name": "uwsgi_temp_path" }, { "table": "
Syntax:http2_body_preread_size size;
Default:
http2_body_preread_size 64k;
Context:http, server

This directive appeared in version 1.11.0.

", "doc": "

Sets the size of the buffer per each request in which the request body may be saved before it is started to be processed.

", "module": "ngx_http_v2_module", "link": "http/ngx_http_v2_module.html#http2_body_preread_size", "name": "http2_body_preread_size" }, { "table": "
Syntax:http2_chunk_size size;
Default:
http2_chunk_size 8k;
Context:http, server, location
", "doc": "

Sets the maximum size of chunks into which the response body is sliced. A too low value results in higher overhead. A too high value impairs prioritization due to HOL blocking.

", "module": "ngx_http_v2_module", "link": "http/ngx_http_v2_module.html#http2_chunk_size", "name": "http2_chunk_size" }, { "table": "
Syntax:http2_idle_timeout time;
Default:
http2_idle_timeout 3m;
Context:http, server
", "doc": "

Sets the timeout of inactivity after which the connection is closed.

", "module": "ngx_http_v2_module", "link": "http/ngx_http_v2_module.html#http2_idle_timeout", "name": "http2_idle_timeout" }, { "table": "
Syntax:http2_max_concurrent_pushes number;
Default:
http2_max_concurrent_pushes 10;
Context:http, server

This directive appeared in version 1.13.9.

", "doc": "

Limits the maximum number of concurrent push requests in a connection.

", "module": "ngx_http_v2_module", "link": "http/ngx_http_v2_module.html#http2_max_concurrent_pushes", "name": "http2_max_concurrent_pushes" }, { "table": "
Syntax:http2_max_concurrent_streams number;
Default:
http2_max_concurrent_streams 128;
Context:http, server
", "doc": "

Sets the maximum number of concurrent HTTP/2 streams in a connection.

", "module": "ngx_http_v2_module", "link": "http/ngx_http_v2_module.html#http2_max_concurrent_streams", "name": "http2_max_concurrent_streams" }, { "table": "
Syntax:http2_max_field_size size;
Default:
http2_max_field_size 4k;
Context:http, server
", "doc": "

Limits the maximum size of an HPACK-compressed request header field. The limit applies equally to both name and value. Note that if Huffman encoding is applied, the actual size of decompressed name and value strings may be larger. For most requests, the default limit should be enough.

", "module": "ngx_http_v2_module", "link": "http/ngx_http_v2_module.html#http2_max_field_size", "name": "http2_max_field_size" }, { "table": "
Syntax:http2_max_header_size size;
Default:
http2_max_header_size 16k;
Context:http, server
", "doc": "

Limits the maximum size of the entire request header list after HPACK decompression. For most requests, the default limit should be enough.

", "module": "ngx_http_v2_module", "link": "http/ngx_http_v2_module.html#http2_max_header_size", "name": "http2_max_header_size" }, { "table": "
Syntax:http2_max_requests number;
Default:
http2_max_requests 1000;
Context:http, server

This directive appeared in version 1.11.6.

", "doc": "

Sets the maximum number of requests (including push requests) that can be served through one HTTP/2 connection, after which the next client request will lead to connection closing and the need of establishing a new connection.

", "module": "ngx_http_v2_module", "link": "http/ngx_http_v2_module.html#http2_max_requests", "name": "http2_max_requests" }, { "table": "
Syntax:http2_push uri | off;
Default:
http2_push off;
Context:http, server, location

This directive appeared in version 1.13.9.

", "doc": "

Pre-emptively sends (pushes) a request to the specified uri along with the response to the original request. Only relative URIs with absolute path will be processed, for example:

\nhttp2_push /static/css/main.css;\n

The uri value can contain variables.

Several http2_push directives can be specified on the same configuration level. The off parameter cancels the effect of the http2_push directives inherited from the previous configuration level.

", "module": "ngx_http_v2_module", "link": "http/ngx_http_v2_module.html#http2_push", "name": "http2_push" }, { "table": "
Syntax:http2_push_preload on | off;
Default:
http2_push_preload off;
Context:http, server, location

This directive appeared in version 1.13.9.

", "doc": "

Enables automatic conversion of preload links specified in the “Link” response header fields into push requests.

", "module": "ngx_http_v2_module", "link": "http/ngx_http_v2_module.html#http2_push_preload", "name": "http2_push_preload" }, { "table": "
Syntax:http2_recv_buffer_size size;
Default:
http2_recv_buffer_size 256k;
Context:http
", "doc": "

Sets the size of the per worker input buffer.

", "module": "ngx_http_v2_module", "link": "http/ngx_http_v2_module.html#http2_recv_buffer_size", "name": "http2_recv_buffer_size" }, { "table": "
Syntax:http2_recv_timeout time;
Default:
http2_recv_timeout 30s;
Context:http, server
", "doc": "

Sets the timeout for expecting more data from the client, after which the connection is closed.

", "module": "ngx_http_v2_module", "link": "http/ngx_http_v2_module.html#http2_recv_timeout", "name": "http2_recv_timeout" }, { "table": "
Syntax:xml_entities path;
Default:—
Context:http, server, location
", "doc": "

Specifies the DTD file that declares character entities. This file is compiled at the configuration stage. For technical reasons, the module is unable to use the external subset declared in the processed XML, so it is ignored and a specially defined file is used instead. This file should not describe the XML structure. It is enough to declare just the required character entities, for example:

\n<!ENTITY nbsp "&#xa0;">\n
", "module": "ngx_http_xslt_module", "link": "http/ngx_http_xslt_module.html#xml_entities", "name": "xml_entities" }, { "table": "
Syntax:xslt_last_modified on | off;
Default:
xslt_last_modified off;
Context:http, server, location

This directive appeared in version 1.5.1.

", "doc": "

Allows preserving the “Last-Modified” header field from the original response during XSLT transformations to facilitate response caching.

By default, the header field is removed as contents of the response are modified during transformations and may contain dynamically generated elements or parts that are changed independently of the original response.

", "module": "ngx_http_xslt_module", "link": "http/ngx_http_xslt_module.html#xslt_last_modified", "name": "xslt_last_modified" }, { "table": "
Syntax:xslt_param parameter value;
Default:—
Context:http, server, location

This directive appeared in version 1.1.18.

", "doc": "

Defines the parameters for XSLT stylesheets. The value is treated as an XPath expression. The value can contain variables. To pass a string value to a stylesheet, the xslt_string_param directive can be used.

There could be several xslt_param directives. These directives are inherited from the previous level if and only if there are no xslt_param and xslt_string_param directives defined on the current level.

", "module": "ngx_http_xslt_module", "link": "http/ngx_http_xslt_module.html#xslt_param", "name": "xslt_param" }, { "table": "
Syntax:xslt_string_param parameter value;
Default:—
Context:http, server, location

This directive appeared in version 1.1.18.

", "doc": "

Defines the string parameters for XSLT stylesheets. XPath expressions in the value are not interpreted. The value can contain variables.

There could be several xslt_string_param directives. These directives are inherited from the previous level if and only if there are no xslt_param and xslt_string_param directives defined on the current level.

", "module": "ngx_http_xslt_module", "link": "http/ngx_http_xslt_module.html#xslt_string_param", "name": "xslt_string_param" }, { "table": "
Syntax:xslt_stylesheet stylesheet [parameter=value ...];
Default:—
Context:location
", "doc": "

Defines the XSLT stylesheet and its optional parameters. A stylesheet is compiled at the configuration stage.

Parameters can either be specified separately, or grouped in a single line using the “:” delimiter. If a parameter includes the “:” character, it should be escaped as “%3A”. Also, libxslt requires to enclose parameters that contain non-alphanumeric characters into single or double quotes, for example:

\nparam1='http%3A//www.example.com':param2=value2\n

The parameters description can contain variables, for example, the whole line of parameters can be taken from a single variable:

\nlocation / {\n    xslt_stylesheet /site/xslt/one.xslt\n                    $arg_xslt_params\n                    param1='$value1':param2=value2\n                    param3=value3;\n}\n

It is possible to specify several stylesheets. They will be applied sequentially in the specified order.

", "module": "ngx_http_xslt_module", "link": "http/ngx_http_xslt_module.html#xslt_stylesheet", "name": "xslt_stylesheet" }, { "table": "
Syntax:xslt_types mime-type ...;
Default:
xslt_types text/xml;
Context:http, server, location
", "doc": "

Enables transformations in responses with the specified MIME types in addition to “text/xml”. The special value “*” matches any MIME type (0.8.29). If the transformation result is an HTML response, its MIME type is changed to “text/html”.

", "module": "ngx_http_xslt_module", "link": "http/ngx_http_xslt_module.html#xslt_types", "name": "xslt_types" }, { "table": "
Syntax:listen address:port [ssl] [backlog=number] [rcvbuf=size] [sndbuf=size] [bind] [ipv6only=on|off] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
Default:—
Context:server
", "doc": "

Sets the address and port for the socket on which the server will accept requests. It is possible to specify just the port. The address can also be a hostname, for example:

\nlisten 127.0.0.1:110;\nlisten *:110;\nlisten 110;     # same as *:110\nlisten localhost:110;\n

IPv6 addresses (0.7.58) are specified in square brackets:

\nlisten [::1]:110;\nlisten [::]:110;\n

UNIX-domain sockets (1.3.5) are specified with the “unix:” prefix:

\nlisten unix:/var/run/nginx.sock;\n

Different servers must listen on different address:port pairs.

The ssl parameter allows specifying that all connections accepted on this port should work in SSL mode.

The listen directive can have several additional parameters specific to socket-related system calls.

backlog=number
sets the backlog parameter in the listen() call that limits the maximum length for the queue of pending connections (1.9.2). By default, backlog is set to -1 on FreeBSD, DragonFly BSD, and macOS, and to 511 on other platforms.
rcvbuf=size
sets the receive buffer size (the SO_RCVBUF option) for the listening socket (1.11.13).
sndbuf=size
sets the send buffer size (the SO_SNDBUF option) for the listening socket (1.11.13).
bind
this parameter instructs to make a separate bind() call for a given address:port pair. The fact is that if there are several listen directives with the same port but different addresses, and one of the listen directives listens on all addresses for the given port (*:port), nginx will bind() only to *:port. It should be noted that the getsockname() system call will be made in this case to determine the address that accepted the connection. If the ipv6only or so_keepalive parameters are used then for a given address:port pair a separate bind() call will always be made.
ipv6only=on|off
this parameter determines (via the IPV6_V6ONLY socket option) whether an IPv6 socket listening on a wildcard address [::] will accept only IPv6 connections or both IPv6 and IPv4 connections. This parameter is turned on by default. It can only be set once on start.
so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]
this parameter configures the “TCP keepalive” behavior for the listening socket. If this parameter is omitted then the operating system’s settings will be in effect for the socket. If it is set to the value “on”, the SO_KEEPALIVE option is turned on for the socket. If it is set to the value “off”, the SO_KEEPALIVE option is turned off for the socket. Some operating systems support setting of TCP keepalive parameters on a per-socket basis using the TCP_KEEPIDLE, TCP_KEEPINTVL, and TCP_KEEPCNT socket options. On such systems (currently, Linux 2.4+, NetBSD 5+, and FreeBSD 9.0-STABLE), they can be configured using the keepidle, keepintvl, and keepcnt parameters. One or two parameters may be omitted, in which case the system default setting for the corresponding socket option will be in effect. For example,
so_keepalive=30m::10
will set the idle timeout (TCP_KEEPIDLE) to 30 minutes, leave the probe interval (TCP_KEEPINTVL) at its system default, and set the probes count (TCP_KEEPCNT) to 10 probes.
", "module": "ngx_mail_core_module", "link": "mail/ngx_mail_core_module.html#listen", "name": "listen" }, { "table": "
Syntax:mail { ... }
Default:—
Context:main
", "doc": "

Provides the configuration file context in which the mail server directives are specified.

", "module": "ngx_mail_core_module", "link": "mail/ngx_mail_core_module.html#mail", "name": "mail" }, { "table": "
Syntax:protocol imap | pop3 | smtp;
Default:—
Context:server
", "doc": "

Sets the protocol for a proxied server. Supported protocols are IMAP, POP3, and SMTP.

If the directive is not set, the protocol can be detected automatically based on the well-known port specified in the listen directive:

", "module": "ngx_mail_core_module", "link": "mail/ngx_mail_core_module.html#protocol", "name": "protocol" }, { "table": "
Syntax:resolver address ... [valid=time];
resolver off;
Default:
resolver off;
Context:mail, server
", "doc": "

Configures name servers used to find the client’s hostname to pass it to the authentication server, and in the XCLIENT command when proxying SMTP. For example:

\nresolver 127.0.0.1 [::1]:5353;\n

An address can be specified as a domain name or IP address, and an optional port (1.3.1, 1.2.2). If port is not specified, the port 53 is used. Name servers are queried in a round-robin fashion.

Before version 1.1.7, only a single name server could be configured. Specifying name servers using IPv6 addresses is supported starting from versions 1.3.1 and 1.2.2.

By default, nginx caches answers using the TTL value of a response. An optional valid parameter allows overriding it:

\nresolver 127.0.0.1 [::1]:5353 valid=30s;\n
Before version 1.1.9, tuning of caching time was not possible, and nginx always cached answers for the duration of 5 minutes.

The special value off disables resolving.

", "module": "ngx_mail_core_module", "link": "mail/ngx_mail_core_module.html#resolver", "name": "resolver" }, { "table": "
Syntax:resolver_timeout time;
Default:
resolver_timeout 30s;
Context:mail, server
", "doc": "

Sets a timeout for DNS operations, for example:

\nresolver_timeout 5s;\n
", "module": "ngx_mail_core_module", "link": "mail/ngx_mail_core_module.html#resolver_timeout", "name": "resolver_timeout" }, { "table": "
Syntax:server { ... }
Default:—
Context:mail
", "doc": "

Sets the configuration for a server.

", "module": "ngx_mail_core_module", "link": "mail/ngx_mail_core_module.html#server", "name": "server" }, { "table": "
Syntax:server_name name;
Default:
server_name hostname;
Context:mail, server
", "doc": "

Sets the server name that is used:

", "module": "ngx_mail_core_module", "link": "mail/ngx_mail_core_module.html#server_name", "name": "server_name" }, { "table": "
Syntax:timeout time;
Default:
timeout 60s;
Context:mail, server
", "doc": "

Sets the timeout that is used before proxying to the backend starts.

", "module": "ngx_mail_core_module", "link": "mail/ngx_mail_core_module.html#timeout", "name": "timeout" }, { "table": "
Syntax:auth_http URL;
Default:—
Context:mail, server
", "doc": "

Sets the URL of the HTTP authentication server. The protocol is described below.

", "module": "ngx_mail_auth_http_module", "link": "mail/ngx_mail_auth_http_module.html#auth_http", "name": "auth_http" }, { "table": "
Syntax:auth_http_header header value;
Default:—
Context:mail, server
", "doc": "

Appends the specified header to requests sent to the authentication server. This header can be used as the shared secret to verify that the request comes from nginx. For example:

\nauth_http_header X-Auth-Key "secret_string";\n
", "module": "ngx_mail_auth_http_module", "link": "mail/ngx_mail_auth_http_module.html#auth_http_header", "name": "auth_http_header" }, { "table": "
Syntax:auth_http_pass_client_cert on | off;
Default:
auth_http_pass_client_cert off;
Context:mail, server

This directive appeared in version 1.7.11.

", "doc": "

Appends the “Auth-SSL-Cert” header with the client certificate in the PEM format (urlencoded) to requests sent to the authentication server.

", "module": "ngx_mail_auth_http_module", "link": "mail/ngx_mail_auth_http_module.html#auth_http_pass_client_cert", "name": "auth_http_pass_client_cert" }, { "table": "
Syntax:auth_http_timeout time;
Default:
auth_http_timeout 60s;
Context:mail, server
", "doc": "

Sets the timeout for communication with the authentication server.

", "module": "ngx_mail_auth_http_module", "link": "mail/ngx_mail_auth_http_module.html#auth_http_timeout", "name": "auth_http_timeout" }, { "table": "
Syntax:proxy_buffer size;
Default:
proxy_buffer 4k|8k;
Context:mail, server
", "doc": "

Sets the size of the buffer used for proxying. By default, the buffer size is equal to one memory page. Depending on a platform, it is either 4K or 8K.

", "module": "ngx_mail_proxy_module", "link": "mail/ngx_mail_proxy_module.html#proxy_buffer", "name": "proxy_buffer" }, { "table": "
Syntax:proxy_pass_error_message on | off;
Default:
proxy_pass_error_message off;
Context:mail, server
", "doc": "

Indicates whether to pass the error message obtained during the authentication on the backend to the client.

Usually, if the authentication in nginx is a success, the backend cannot return an error. If it nevertheless returns an error, it means some internal error has occurred. In such case the backend message can contain information that should not be shown to the client. However, responding with an error for the correct password is a normal behavior for some POP3 servers. For example, CommuniGatePro informs a user about mailbox overflow or other events by periodically outputting the authentication error. The directive should be enabled in this case.

", "module": "ngx_mail_proxy_module", "link": "mail/ngx_mail_proxy_module.html#proxy_pass_error_message", "name": "proxy_pass_error_message" }, { "table": "
Syntax:proxy_timeout timeout;
Default:
proxy_timeout 24h;
Context:mail, server
", "doc": "

Sets the timeout between two successive read or write operations on client or proxied server connections. If no data is transmitted within this time, the connection is closed.

", "module": "ngx_mail_proxy_module", "link": "mail/ngx_mail_proxy_module.html#proxy_timeout", "name": "proxy_timeout" }, { "table": "
Syntax:xclient on | off;
Default:
xclient on;
Context:mail, server
", "doc": "

Enables or disables the passing of the XCLIENT command with client parameters when connecting to the SMTP backend.

With XCLIENT, the MTA is able to write client information to the log and apply various limitations based on this data.

If XCLIENT is enabled then nginx passes the following commands when connecting to the backend:

", "module": "ngx_mail_proxy_module", "link": "mail/ngx_mail_proxy_module.html#xclient", "name": "xclient" }, { "table": "
Syntax:ssl on | off;
Default:
ssl off;
Context:mail, server
", "doc": "

This directive was made obsolete in version 1.15.0. The ssl parameter of the listen directive should be used instead.

", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl", "name": "ssl" }, { "table": "
Syntax:ssl_certificate file;
Default:—
Context:mail, server
", "doc": "

Specifies a file with the certificate in the PEM format for the given server. If intermediate certificates should be specified in addition to a primary certificate, they should be specified in the same file in the following order: the primary certificate comes first, then the intermediate certificates. A secret key in the PEM format may be placed in the same file.

Since version 1.11.0, this directive can be specified multiple times to load certificates of different types, for example, RSA and ECDSA:

\nserver {\n    listen              993 ssl;\n\n    ssl_certificate     example.com.rsa.crt;\n    ssl_certificate_key example.com.rsa.key;\n\n    ssl_certificate     example.com.ecdsa.crt;\n    ssl_certificate_key example.com.ecdsa.key;\n\n    ...\n}\n
Only OpenSSL 1.0.2 or higher supports separate certificate chains for different certificates. With older versions, only one certificate chain can be used.
", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_certificate", "name": "ssl_certificate" }, { "table": "
Syntax:ssl_certificate_key file;
Default:—
Context:mail, server
", "doc": "

Specifies a file with the secret key in the PEM format for the given 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.

", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_certificate_key", "name": "ssl_certificate_key" }, { "table": "
Syntax:ssl_ciphers ciphers;
Default:
ssl_ciphers HIGH:!aNULL:!MD5;
Context:mail, server
", "doc": "

Specifies the enabled ciphers. The ciphers are specified in the format understood by the OpenSSL library, for example:

\nssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;\n

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

The previous versions of nginx used different ciphers by default.
", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_ciphers", "name": "ssl_ciphers" }, { "table": "
Syntax:ssl_client_certificate file;
Default:—
Context:mail, server

This directive appeared in version 1.7.11.

", "doc": "

Specifies a file with trusted CA certificates in the PEM format used to verify client certificates.

The list of certificates will be sent to clients. If this is not desired, the ssl_trusted_certificate directive can be used.

", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_client_certificate", "name": "ssl_client_certificate" }, { "table": "
Syntax:ssl_crl file;
Default:—
Context:mail, server

This directive appeared in version 1.7.11.

", "doc": "

Specifies a file with revoked certificates (CRL) in the PEM format used to verify client certificates.

", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_crl", "name": "ssl_crl" }, { "table": "
Syntax:ssl_dhparam file;
Default:—
Context:mail, server

This directive appeared in version 0.7.2.

", "doc": "

Specifies a file with DH parameters for DHE ciphers.

", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_dhparam", "name": "ssl_dhparam" }, { "table": "
Syntax:ssl_ecdh_curve curve;
Default:
ssl_ecdh_curve auto;
Context:mail, server

This directive appeared in versions 1.1.0 and 1.0.6.

", "doc": "

Specifies a curve for ECDHE ciphers.

When using OpenSSL 1.0.2 or higher, it is possible to specify multiple curves (1.11.0), for example:

\nssl_ecdh_curve prime256v1:secp384r1;\n

The special value auto (1.11.0) instructs nginx to use a list built into the OpenSSL library when using OpenSSL 1.0.2 or higher, or prime256v1 with older versions.

Prior to version 1.11.0, the prime256v1 curve was used by default.
", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_ecdh_curve", "name": "ssl_ecdh_curve" }, { "table": "
Syntax:ssl_password_file file;
Default:—
Context:mail, server

This directive appeared in version 1.7.3.

", "doc": "

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.

Example:

\nmail {\n    ssl_password_file /etc/keys/global.pass;\n    ...\n\n    server {\n        server_name mail1.example.com;\n        ssl_certificate_key /etc/keys/first.key;\n    }\n\n    server {\n        server_name mail2.example.com;\n\n        # named pipe can also be used instead of a file\n        ssl_password_file /etc/keys/fifo;\n        ssl_certificate_key /etc/keys/second.key;\n    }\n}\n
", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_password_file", "name": "ssl_password_file" }, { "table": "
Syntax:ssl_prefer_server_ciphers on | off;
Default:
ssl_prefer_server_ciphers off;
Context:mail, server
", "doc": "

Specifies that server ciphers should be preferred over client ciphers when the SSLv3 and TLS protocols are used.

", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_prefer_server_ciphers", "name": "ssl_prefer_server_ciphers" }, { "table": "
Syntax:ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default:
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
Context:mail, server
", "doc": "

Enables the specified protocols.

The TLSv1.1 and TLSv1.2 parameters (1.1.13, 1.0.12) work only when OpenSSL 1.0.1 or higher is used.
The TLSv1.3 parameter (1.13.0) works only when OpenSSL 1.1.1 built with TLSv1.3 support is used.
", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_protocols", "name": "ssl_protocols" }, { "table": "
Syntax:ssl_session_cache off | none | [builtin[:size]] [shared:name:size];
Default:
ssl_session_cache none;
Context:mail, server
", "doc": "

Sets the types and sizes of caches that store session parameters. A cache can be of any of the following types:

off
the use of a session cache is strictly prohibited: nginx explicitly tells a client that sessions may not be reused.
none
the use of a session cache is gently disallowed: nginx tells a client that sessions may be reused, but does not actually store session parameters in the cache.
builtin
a cache built in OpenSSL; used by one worker process only. The cache size is specified in sessions. If size is not given, it is equal to 20480 sessions. Use of the built-in cache can cause memory fragmentation.
shared
a cache shared between all worker processes. The cache size is specified in bytes; one megabyte can store about 4000 sessions. Each shared cache should have an arbitrary name. A cache with the same name can be used in several servers.

Both cache types can be used simultaneously, for example:

\nssl_session_cache builtin:1000 shared:SSL:10m;\n

but using only shared cache without the built-in cache should be more efficient.

", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_session_cache", "name": "ssl_session_cache" }, { "table": "
Syntax:ssl_session_ticket_key file;
Default:—
Context:mail, server

This directive appeared in version 1.5.7.

", "doc": "

Sets a file with the secret key used to encrypt and decrypt TLS session tickets. The directive is necessary if the same key has to be shared between multiple servers. By default, a randomly generated key is used.

If several keys are specified, only the first key is used to encrypt TLS session tickets. This allows configuring key rotation, for example:

\nssl_session_ticket_key current.key;\nssl_session_ticket_key previous.key;\n

The file must contain 80 or 48 bytes of random data and can be created using the following command:

\nopenssl rand 80 > ticket.key\n

Depending on the file size either AES256 (for 80-byte keys, 1.11.8) or AES128 (for 48-byte keys) is used for encryption.

", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_session_ticket_key", "name": "ssl_session_ticket_key" }, { "table": "
Syntax:ssl_session_tickets on | off;
Default:
ssl_session_tickets on;
Context:mail, server

This directive appeared in version 1.5.9.

", "doc": "

Enables or disables session resumption through TLS session tickets.

", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_session_tickets", "name": "ssl_session_tickets" }, { "table": "
Syntax:ssl_session_timeout time;
Default:
ssl_session_timeout 5m;
Context:mail, server
", "doc": "

Specifies a time during which a client may reuse the session parameters.

", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_session_timeout", "name": "ssl_session_timeout" }, { "table": "
Syntax:ssl_trusted_certificate file;
Default:—
Context:mail, server

This directive appeared in version 1.7.11.

", "doc": "

Specifies a file with trusted CA certificates in the PEM format used to verify client certificates.

In contrast to the certificate set by ssl_client_certificate, the list of these certificates will not be sent to clients.

", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_trusted_certificate", "name": "ssl_trusted_certificate" }, { "table": "
Syntax:ssl_verify_client on | off | optional | optional_no_ca;
Default:
ssl_verify_client off;
Context:mail, server

This directive appeared in version 1.7.11.

", "doc": "

Enables verification of client certificates. The verification result is passed in the “Auth-SSL-Verify” header of the authentication request.

The optional parameter requests the client certificate and verifies it if the certificate is present.

The optional_no_ca parameter requests the client certificate but does not require it to be signed by a trusted CA certificate. This is intended for the use in cases when a service that is external to nginx performs the actual certificate verification. The contents of the certificate is accessible through requests sent to the authentication server.

", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_verify_client", "name": "ssl_verify_client" }, { "table": "
Syntax:ssl_verify_depth number;
Default:
ssl_verify_depth 1;
Context:mail, server

This directive appeared in version 1.7.11.

", "doc": "

Sets the verification depth in the client certificates chain.

", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#ssl_verify_depth", "name": "ssl_verify_depth" }, { "table": "
Syntax:starttls on | off | only;
Default:
starttls off;
Context:mail, server
", "doc": "
on
allow usage of the STLS command for the POP3 and the STARTTLS command for the IMAP and SMTP;
off
deny usage of the STLS and STARTTLS commands;
only
require preliminary TLS transition.
", "module": "ngx_mail_ssl_module", "link": "mail/ngx_mail_ssl_module.html#starttls", "name": "starttls" }, { "table": "
Syntax:imap_auth method ...;
Default:
imap_auth plain;
Context:mail, server
", "doc": "

Sets permitted methods of authentication for IMAP clients. Supported methods are:

login
AUTH=LOGIN
plain
AUTH=PLAIN
cram-md5
AUTH=CRAM-MD5. In order for this method to work, the password must be stored unencrypted.
external
AUTH=EXTERNAL (1.11.6).
", "module": "ngx_mail_imap_module", "link": "mail/ngx_mail_imap_module.html#imap_auth", "name": "imap_auth" }, { "table": "
Syntax:imap_capabilities extension ...;
Default:
imap_capabilities IMAP4 IMAP4rev1 UIDPLUS;
Context:mail, server
", "doc": "

Sets the IMAP protocol extensions list that is passed to the client in response to the CAPABILITY command. The authentication methods specified in the imap_auth directive and STARTTLS are automatically added to this list depending on the starttls directive value.

It makes sense to specify the extensions supported by the IMAP backends to which the clients are proxied (if these extensions are related to commands used after the authentication, when nginx transparently proxies a client connection to the backend).

The current list of standardized extensions is published at www.iana.org.

", "module": "ngx_mail_imap_module", "link": "mail/ngx_mail_imap_module.html#imap_capabilities", "name": "imap_capabilities" }, { "table": "
Syntax:imap_client_buffer size;
Default:
imap_client_buffer 4k|8k;
Context:mail, server
", "doc": "

Sets the size of the buffer used for reading IMAP commands. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.

", "module": "ngx_mail_imap_module", "link": "mail/ngx_mail_imap_module.html#imap_client_buffer", "name": "imap_client_buffer" }, { "table": "
Syntax:pop3_auth method ...;
Default:
pop3_auth plain;
Context:mail, server
", "doc": "

Sets permitted methods of authentication for POP3 clients. Supported methods are:

plain
USER/PASS, AUTH PLAIN, AUTH LOGIN. It is not possible to disable these methods.
apop
APOP. In order for this method to work, the password must be stored unencrypted.
cram-md5
AUTH CRAM-MD5. In order for this method to work, the password must be stored unencrypted.
external
AUTH EXTERNAL (1.11.6).
", "module": "ngx_mail_pop3_module", "link": "mail/ngx_mail_pop3_module.html#pop3_auth", "name": "pop3_auth" }, { "table": "
Syntax:pop3_capabilities extension ...;
Default:
pop3_capabilities TOP USER UIDL;
Context:mail, server
", "doc": "

Sets the POP3 protocol extensions list that is passed to the client in response to the CAPA command. The authentication methods specified in the pop3_auth directive (SASL extension) and STLS are automatically added to this list depending on the starttls directive value.

It makes sense to specify the extensions supported by the POP3 backends to which the clients are proxied (if these extensions are related to commands used after the authentication, when nginx transparently proxies the client connection to the backend).

The current list of standardized extensions is published at www.iana.org.

", "module": "ngx_mail_pop3_module", "link": "mail/ngx_mail_pop3_module.html#pop3_capabilities", "name": "pop3_capabilities" }, { "table": "
Syntax:smtp_auth method ...;
Default:
smtp_auth login plain;
Context:mail, server
", "doc": "

Sets permitted methods of SASL authentication for SMTP clients. Supported methods are:

login
AUTH LOGIN
plain
AUTH PLAIN
cram-md5
AUTH CRAM-MD5. In order for this method to work, the password must be stored unencrypted.
external
AUTH EXTERNAL (1.11.6).
none
Authentication is not required.
", "module": "ngx_mail_smtp_module", "link": "mail/ngx_mail_smtp_module.html#smtp_auth", "name": "smtp_auth" }, { "table": "
Syntax:smtp_capabilities extension ...;
Default:—
Context:mail, server
", "doc": "

Sets the SMTP protocol extensions list that is passed to the client in response to the EHLO command. The authentication methods specified in the smtp_auth directive and STARTTLS are automatically added to this list depending on the starttls directive value.

It makes sense to specify the extensions supported by the MTA to which the clients are proxied (if these extensions are related to commands used after the authentication, when nginx transparently proxies the client connection to the backend).

The current list of standardized extensions is published at www.iana.org.

", "module": "ngx_mail_smtp_module", "link": "mail/ngx_mail_smtp_module.html#smtp_capabilities", "name": "smtp_capabilities" }, { "table": "
Syntax:smtp_client_buffer size;
Default:
smtp_client_buffer 4k|8k;
Context:mail, server
", "doc": "

Sets the size of the buffer used for reading SMTP commands. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.

", "module": "ngx_mail_smtp_module", "link": "mail/ngx_mail_smtp_module.html#smtp_client_buffer", "name": "smtp_client_buffer" }, { "table": "
Syntax:smtp_greeting_delay time;
Default:
smtp_greeting_delay 0;
Context:mail, server
", "doc": "

Allows setting a delay before sending an SMTP greeting in order to reject clients who fail to wait for the greeting before sending SMTP commands.

", "module": "ngx_mail_smtp_module", "link": "mail/ngx_mail_smtp_module.html#smtp_greeting_delay", "name": "smtp_greeting_delay" }, { "table": "
Syntax:listen address:port [ssl] [udp] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
Default:—
Context:server
", "doc": "

Sets the address and port for the socket on which the server will accept connections. It is possible to specify just the port. The address can also be a hostname, for example:

\nlisten 127.0.0.1:12345;\nlisten *:12345;\nlisten 12345;     # same as *:12345\nlisten localhost:12345;\n

IPv6 addresses are specified in square brackets:

\nlisten [::1]:12345;\nlisten [::]:12345;\n

UNIX-domain sockets are specified with the “unix:” prefix:

\nlisten unix:/var/run/nginx.sock;\n

The ssl parameter allows specifying that all connections accepted on this port should work in SSL mode.

", "module": "ngx_stream_core_module", "link": "stream/ngx_stream_core_module.html#listen", "name": "listen" }, { "table": "
Syntax:preread_buffer_size size;
Default:
preread_buffer_size 16k;
Context:stream, server

This directive appeared in version 1.11.5.

", "doc": "

Specifies a size of the preread buffer.

", "module": "ngx_stream_core_module", "link": "stream/ngx_stream_core_module.html#preread_buffer_size", "name": "preread_buffer_size" }, { "table": "
Syntax:preread_timeout timeout;
Default:
preread_timeout 30s;
Context:stream, server

This directive appeared in version 1.11.5.

", "doc": "

Specifies a timeout of the preread phase.

", "module": "ngx_stream_core_module", "link": "stream/ngx_stream_core_module.html#preread_timeout", "name": "preread_timeout" }, { "table": "
Syntax:proxy_protocol_timeout timeout;
Default:
proxy_protocol_timeout 30s;
Context:stream, server

This directive appeared in version 1.11.4.

", "doc": "

Specifies a timeout for reading the PROXY protocol header to complete. If no entire header is transmitted within this time, the connection is closed.

", "module": "ngx_stream_core_module", "link": "stream/ngx_stream_core_module.html#proxy_protocol_timeout", "name": "proxy_protocol_timeout" }, { "table": "
Syntax:resolver address ... [valid=time] [ipv6=on|off];
Default:—
Context:stream, server

This directive appeared in version 1.11.3.

", "doc": "

Configures name servers used to resolve names of upstream servers into addresses, for example:

\nresolver 127.0.0.1 [::1]:5353;\n

An address can be specified as a domain name or IP address, and an optional port. If port is not specified, the port 53 is used. Name servers are queried in a round-robin fashion.

By default, nginx will look up both IPv4 and IPv6 addresses while resolving. If looking up of IPv6 addresses is not desired, the ipv6=off parameter can be specified.

By default, nginx caches answers using the TTL value of a response. The optional valid parameter allows overriding it:

\nresolver 127.0.0.1 [::1]:5353 valid=30s;\n
Before version 1.11.3, this directive was available as part of our commercial subscription.
", "module": "ngx_stream_core_module", "link": "stream/ngx_stream_core_module.html#resolver", "name": "resolver" }, { "table": "
Syntax:resolver_timeout time;
Default:
resolver_timeout 30s;
Context:stream, server

This directive appeared in version 1.11.3.

", "doc": "

Sets a timeout for name resolution, for example:

\nresolver_timeout 5s;\n
Before version 1.11.3, this directive was available as part of our commercial subscription.
", "module": "ngx_stream_core_module", "link": "stream/ngx_stream_core_module.html#resolver_timeout", "name": "resolver_timeout" }, { "table": "
Syntax:server { ... }
Default:—
Context:stream
", "doc": "

Sets the configuration for a server.

", "module": "ngx_stream_core_module", "link": "stream/ngx_stream_core_module.html#server", "name": "server" }, { "table": "
Syntax:stream { ... }
Default:—
Context:main
", "doc": "

Provides the configuration file context in which the stream server directives are specified.

", "module": "ngx_stream_core_module", "link": "stream/ngx_stream_core_module.html#stream", "name": "stream" }, { "table": "
Syntax:tcp_nodelay on | off;
Default:
tcp_nodelay on;
Context:stream, server

This directive appeared in version 1.9.4.

", "doc": "

Enables or disables the use of the TCP_NODELAY option. The option is enabled for both client and proxied server connections.

", "module": "ngx_stream_core_module", "link": "stream/ngx_stream_core_module.html#tcp_nodelay", "name": "tcp_nodelay" }, { "table": "
Syntax:variables_hash_bucket_size size;
Default:
variables_hash_bucket_size 64;
Context:stream

This directive appeared in version 1.11.2.

", "doc": "

Sets the bucket size for the variables hash table. The details of setting up hash tables are provided in a separate document.

", "module": "ngx_stream_core_module", "link": "stream/ngx_stream_core_module.html#variables_hash_bucket_size", "name": "variables_hash_bucket_size" }, { "table": "
Syntax:variables_hash_max_size size;
Default:
variables_hash_max_size 1024;
Context:stream

This directive appeared in version 1.11.2.

", "doc": "

Sets the maximum size of the variables hash table. The details of setting up hash tables are provided in a separate document.

", "module": "ngx_stream_core_module", "link": "stream/ngx_stream_core_module.html#variables_hash_max_size", "name": "variables_hash_max_size" }, { "table": "
Syntax:allow address | CIDR | unix: | all;
Default:—
Context:stream, server
", "doc": "

Allows access for the specified network or address. If the special value unix: is specified, allows access for all UNIX-domain sockets.

", "module": "ngx_stream_access_module", "link": "stream/ngx_stream_access_module.html#allow", "name": "allow" }, { "table": "
Syntax:deny address | CIDR | unix: | all;
Default:—
Context:stream, server
", "doc": "

Denies access for the specified network or address. If the special value unix: is specified, denies access for all UNIX-domain sockets.

", "module": "ngx_stream_access_module", "link": "stream/ngx_stream_access_module.html#deny", "name": "deny" }, { "table": "
Syntax:geo [$address] $variable { ... }
Default:—
Context:stream
", "doc": "

Describes the dependency of values of the specified variable on the client IP address. By default, the address is taken from the $remote_addr variable, but it can also be taken from another variable, for example:

\ngeo $arg_remote_addr $geo {\n    ...;\n}\n
Since variables are evaluated only when used, the mere existence of even a large number of declared “geo” variables does not cause any extra costs for connection processing.

If the value of a variable does not represent a valid IP address then the “255.255.255.255” address is used.

Addresses are specified either as prefixes in CIDR notation (including individual addresses) or as ranges.

The following special parameters are also supported:

delete
deletes the specified network.
default
a value set to the variable if the client address does not match any of the specified addresses. When addresses are specified in CIDR notation, “0.0.0.0/0” and “::/0” can be used instead of default. When default is not specified, the default value will be an empty string.
include
includes a file with addresses and values. There can be several inclusions.
ranges
indicates that addresses are specified as ranges. This parameter should be the first. To speed up loading of a geo base, addresses should be put in ascending order.

Example:

\ngeo $country {\n    default        ZZ;\n    include        conf/geo.conf;\n    delete         127.0.0.0/16;\n\n    127.0.0.0/24   US;\n    127.0.0.1/32   RU;\n    10.1.0.0/16    RU;\n    192.168.1.0/24 UK;\n}\n

The conf/geo.conf file could contain the following lines:

\n10.2.0.0/16    RU;\n192.168.2.0/24 RU;\n

A value of the most specific match is used. For example, for the 127.0.0.1 address the value “RU” will be chosen, not “US”.

Example with ranges:

\ngeo $country {\n    ranges;\n    default                   ZZ;\n    127.0.0.0-127.0.0.0       US;\n    127.0.0.1-127.0.0.1       RU;\n    127.0.0.1-127.0.0.255     US;\n    10.1.0.0-10.1.255.255     RU;\n    192.168.1.0-192.168.1.255 UK;\n}\n
", "module": "ngx_stream_geo_module", "link": "stream/ngx_stream_geo_module.html#geo", "name": "geo" }, { "table": "
Syntax:geoip_country file;
Default:—
Context:stream
", "doc": "

Specifies a database used to determine the country depending on the client IP address. The following variables are available when using this database:

$geoip_country_code
two-letter country code, for example, “RU”, “US”.
$geoip_country_code3
three-letter country code, for example, “RUS”, “USA”.
$geoip_country_name
country name, for example, “Russian Federation”, “United States”.
", "module": "ngx_stream_geoip_module", "link": "stream/ngx_stream_geoip_module.html#geoip_country", "name": "geoip_country" }, { "table": "
Syntax:geoip_city file;
Default:—
Context:stream
", "doc": "

Specifies a database used to determine the country, region, and city depending on the client IP address. The following variables are available when using this database:

$geoip_area_code
telephone area code (US only).
This variable may contain outdated information since the corresponding database field is deprecated.
$geoip_city_continent_code
two-letter continent code, for example, “EU”, “NA”.
$geoip_city_country_code
two-letter country code, for example, “RU”, “US”.
$geoip_city_country_code3
three-letter country code, for example, “RUS”, “USA”.
$geoip_city_country_name
country name, for example, “Russian Federation”, “United States”.
$geoip_dma_code
DMA region code in US (also known as “metro code”), according to the geotargeting in Google AdWords API.
$geoip_latitude
latitude.
$geoip_longitude
longitude.
$geoip_region
two-symbol country region code (region, territory, state, province, federal land and the like), for example, “48”, “DC”.
$geoip_region_name
country region name (region, territory, state, province, federal land and the like), for example, “Moscow City”, “District of Columbia”.
$geoip_city
city name, for example, “Moscow”, “Washington”.
$geoip_postal_code
postal code.
", "module": "ngx_stream_geoip_module", "link": "stream/ngx_stream_geoip_module.html#geoip_city", "name": "geoip_city" }, { "table": "
Syntax:geoip_org file;
Default:—
Context:stream
", "doc": "

Specifies a database used to determine the organization depending on the client IP address. The following variable is available when using this database:

$geoip_org
organization name, for example, “The University of Melbourne”.
", "module": "ngx_stream_geoip_module", "link": "stream/ngx_stream_geoip_module.html#geoip_org", "name": "geoip_org" }, { "table": "
Syntax:js_access function;
Default:—
Context:stream, server
", "doc": "

Sets an njs function which will be called at the access phase.

", "module": "ngx_stream_js_module", "link": "stream/ngx_stream_js_module.html#js_access", "name": "js_access" }, { "table": "
Syntax:js_filter function;
Default:—
Context:stream, server
", "doc": "

Sets a data filter.

", "module": "ngx_stream_js_module", "link": "stream/ngx_stream_js_module.html#js_filter", "name": "js_filter" }, { "table": "
Syntax:js_include file;
Default:—
Context:stream
", "doc": "

Specifies a file that implements server and variable handlers in njs.

", "module": "ngx_stream_js_module", "link": "stream/ngx_stream_js_module.html#js_include", "name": "js_include" }, { "table": "
Syntax:js_preread function;
Default:—
Context:stream, server
", "doc": "

Sets an njs function which will be called at the preread phase.

", "module": "ngx_stream_js_module", "link": "stream/ngx_stream_js_module.html#js_preread", "name": "js_preread" }, { "table": "
Syntax:js_set $variable function;
Default:—
Context:stream
", "doc": "

Sets an njs function for the specified variable.

", "module": "ngx_stream_js_module", "link": "stream/ngx_stream_js_module.html#js_set", "name": "js_set" }, { "table": "
Syntax:keyval key $variable zone=name;
Default:—
Context:stream
", "doc": "

Creates a new $variable whose value is looked up by the key in the key-value database. Strings are matched ignoring the case. The database is stored in a shared memory zone specified by the zone parameter.

", "module": "ngx_stream_keyval_module", "link": "stream/ngx_stream_keyval_module.html#keyval", "name": "keyval" }, { "table": "
Syntax:keyval_zone zone=name:size [state=file];
Default:—
Context:stream
", "doc": "

Sets the name and size of the shared memory zone that keeps the key-value database. Key-value pairs are managed by the API.

The optional state parameter specifies a file that keeps the current state of the key-value database in the JSON format and makes it persistent across nginx restarts.

", "module": "ngx_stream_keyval_module", "link": "stream/ngx_stream_keyval_module.html#keyval_zone", "name": "keyval_zone" }, { "table": "
Syntax:limit_conn zone number;
Default:—
Context:stream, server
", "doc": "

Sets the shared memory zone and the maximum allowed number of connections for a given key value. When this limit is exceeded, the server will close the connection. For example, the directives

\nlimit_conn_zone $binary_remote_addr zone=addr:10m;\n\nserver {\n    ...\n    limit_conn addr 1;\n}\n

allow only one connection per an IP address at a time.

When several limit_conn directives are specified, any configured limit will apply.

The directives are inherited from the previous level if and only if there are no limit_conn directives on the current level.

", "module": "ngx_stream_limit_conn_module", "link": "stream/ngx_stream_limit_conn_module.html#limit_conn", "name": "limit_conn" }, { "table": "
Syntax:limit_conn_log_level info | notice | warn | error;
Default:
limit_conn_log_level error;
Context:stream, server
", "doc": "

Sets the desired logging level for cases when the server limits the number of connections.

", "module": "ngx_stream_limit_conn_module", "link": "stream/ngx_stream_limit_conn_module.html#limit_conn_log_level", "name": "limit_conn_log_level" }, { "table": "
Syntax:limit_conn_zone key zone=name:size;
Default:—
Context:stream
", "doc": "

Sets parameters for a shared memory zone that will keep states for various keys. In particular, the state includes the current number of connections. The key can contain text, variables, and their combinations (1.11.2). Connections with an empty key value are not accounted. Usage example:

\nlimit_conn_zone $binary_remote_addr zone=addr:10m;\n

Here, the key is a client IP address set by the $binary_remote_addr variable. The size of $binary_remote_addr is 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses. The stored state always occupies 32 or 64 bytes on 32-bit platforms and 64 bytes on 64-bit platforms. One megabyte zone can keep about 32 thousand 32-byte states or about 16 thousand 64-byte states. If the zone storage is exhausted, the server will close the connection.

", "module": "ngx_stream_limit_conn_module", "link": "stream/ngx_stream_limit_conn_module.html#limit_conn_zone", "name": "limit_conn_zone" }, { "table": "
Syntax:access_log path format [buffer=size] [gzip[=level]] [flush=time] [if=condition];
access_log off;
Default:
access_log off;
Context:stream, server
", "doc": "

Sets the path, format, and configuration for a buffered log write. Several logs can be specified on the same level. Logging to syslog can be configured by specifying the “syslog:” prefix in the first parameter. The special value off cancels all access_log directives on the current level.

If either the buffer or gzip parameter is used, writes to log will be buffered.

The buffer size must not exceed the size of an atomic write to a disk file. For FreeBSD this size is unlimited.

When buffering is enabled, the data will be written to the file:

", "module": "ngx_stream_log_module", "link": "stream/ngx_stream_log_module.html#access_log", "name": "access_log" }, { "table": "
Syntax:log_format name [escape=default|json|none] string ...;
Default:—
Context:stream
", "doc": "

Specifies the log format, for example:

\nlog_format proxy '$remote_addr [$time_local] '\n                 '$protocol $status $bytes_sent $bytes_received '\n                 '$session_time "$upstream_addr" '\n                 '"$upstream_bytes_sent" "$upstream_bytes_received" "$upstream_connect_time"';\n
", "module": "ngx_stream_log_module", "link": "stream/ngx_stream_log_module.html#log_format", "name": "log_format" }, { "table": "
Syntax:open_log_file_cache max=N [inactive=time] [min_uses=N] [valid=time];
open_log_file_cache off;
Default:
open_log_file_cache off;
Context:stream, server
", "doc": "

Defines a cache that stores the file descriptors of frequently used logs whose names contain variables. The directive has the following parameters:

max
sets the maximum number of descriptors in a cache; if the cache becomes full the least recently used (LRU) descriptors are closed
inactive
sets the time after which the cached descriptor is closed if there were no access during this time; by default, 10 seconds
min_uses
sets the minimum number of file uses during the time defined by the inactive parameter to let the descriptor stay open in a cache; by default, 1
valid
sets the time after which it should be checked that the file still exists with the same name; by default, 60 seconds
off
disables caching

Usage example:

\nopen_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;\n
", "module": "ngx_stream_log_module", "link": "stream/ngx_stream_log_module.html#open_log_file_cache", "name": "open_log_file_cache" }, { "table": "
Syntax:map string $variable { ... }
Default:—
Context:stream
", "doc": "

Creates a new variable whose value depends on values of one or more of the source variables specified in the first parameter.

Since variables are evaluated only when they are used, the mere declaration even of a large number of “map” variables does not add any extra costs to connection processing.

Parameters inside the map block specify a mapping between source and resulting values.

Source values are specified as strings or regular expressions.

Strings are matched ignoring the case.

A regular expression should either start from the “~” symbol for a case-sensitive matching, or from the “~*” symbols for case-insensitive matching. A regular expression can contain named and positional captures that can later be used in other directives along with the resulting variable.

If a source value matches one of the names of special parameters described below, it should be prefixed with the “\\” symbol.

The resulting value can contain text, variable, and their combination.

The following special parameters are also supported:

default value
sets the resulting value if the source value matches none of the specified variants. When default is not specified, the default resulting value will be an empty string.
hostnames
indicates that source values can be hostnames with a prefix or suffix mask:
\n*.example.com 1;\nexample.*     1;\n
The following two records
\nexample.com   1;\n*.example.com 1;\n
can be combined:
\n.example.com  1;\n
This parameter should be specified before the list of values.
include file
includes a file with values. There can be several inclusions.
volatile
indicates that the variable is not cacheable (1.11.7).

If the source value matches more than one of the specified variants, e.g. both a mask and a regular expression match, the first matching variant will be chosen, in the following order of priority:

", "module": "ngx_stream_map_module", "link": "stream/ngx_stream_map_module.html#map", "name": "map" }, { "table": "
Syntax:map_hash_bucket_size size;
Default:
map_hash_bucket_size 32|64|128;
Context:stream
", "doc": "

Sets the bucket size for the map variables hash tables. Default value depends on the processor’s cache line size. The details of setting up hash tables are provided in a separate document.

", "module": "ngx_stream_map_module", "link": "stream/ngx_stream_map_module.html#map_hash_bucket_size", "name": "map_hash_bucket_size" }, { "table": "
Syntax:map_hash_max_size size;
Default:
map_hash_max_size 2048;
Context:stream
", "doc": "

Sets the maximum size of the map variables hash tables. The details of setting up hash tables are provided in a separate document.

", "module": "ngx_stream_map_module", "link": "stream/ngx_stream_map_module.html#map_hash_max_size", "name": "map_hash_max_size" }, { "table": "
Syntax:proxy_bind address [transparent] | off;
Default:—
Context:stream, server

This directive appeared in version 1.9.2.

", "doc": "

Makes outgoing connections to a proxied server originate from the specified local IP address. Parameter value can contain variables (1.11.2). The special value off 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.

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_bind", "name": "proxy_bind" }, { "table": "
Syntax:proxy_buffer_size size;
Default:
proxy_buffer_size 16k;
Context:stream, server

This directive appeared in version 1.9.4.

", "doc": "

Sets the size of the buffer used for reading data from the proxied server. Also sets the size of the buffer used for reading data from the client.

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_buffer_size", "name": "proxy_buffer_size" }, { "table": "
Syntax:proxy_connect_timeout time;
Default:
proxy_connect_timeout 60s;
Context:stream, server
", "doc": "

Defines a timeout for establishing a connection with a proxied server.

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_connect_timeout", "name": "proxy_connect_timeout" }, { "table": "
Syntax:proxy_download_rate rate;
Default:
proxy_download_rate 0;
Context:stream, server

This directive appeared in version 1.9.3.

", "doc": "

Limits the speed of reading the data from the proxied server. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a connection, so if nginx simultaneously opens two connections to the proxied server, the overall rate will be twice as much as the specified limit.

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_download_rate", "name": "proxy_download_rate" }, { "table": "
Syntax:proxy_next_upstream on | off;
Default:
proxy_next_upstream on;
Context:stream, server
", "doc": "

When a connection to the proxied server cannot be established, determines whether a client connection will be passed to the next server.

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

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_next_upstream", "name": "proxy_next_upstream" }, { "table": "
Syntax:proxy_next_upstream_timeout time;
Default:
proxy_next_upstream_timeout 0;
Context:stream, server
", "doc": "

Limits the time allowed to pass a connection to the next server. The 0 value turns off this limitation.

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_next_upstream_timeout", "name": "proxy_next_upstream_timeout" }, { "table": "
Syntax:proxy_next_upstream_tries number;
Default:
proxy_next_upstream_tries 0;
Context:stream, server
", "doc": "

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

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_next_upstream_tries", "name": "proxy_next_upstream_tries" }, { "table": "
Syntax:proxy_pass address;
Default:—
Context:server
", "doc": "

Sets the address of a proxied server. The address can be specified as a domain name or IP address, and a port:

\nproxy_pass localhost:12345;\n

or as a UNIX-domain socket path:

\nproxy_pass unix:/tmp/stream.socket;\n

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.

The address can also be specified using variables (1.11.3):

\nproxy_pass $upstream;\n

In this case, the server name is searched among the described server groups, and, if not found, is determined using a resolver.

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_pass", "name": "proxy_pass" }, { "table": "
Syntax:proxy_protocol on | off;
Default:
proxy_protocol off;
Context:stream, server

This directive appeared in version 1.9.2.

", "doc": "

Enables the PROXY protocol for connections to a proxied server.

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_protocol", "name": "proxy_protocol" }, { "table": "
Syntax:proxy_responses number;
Default:—
Context:stream, server

This directive appeared in version 1.9.13.

", "doc": "

Sets the number of datagrams expected from the proxied server in response to a client datagram if the UDP protocol is used. The number serves as a hint for session termination. By default, the number of datagrams is not limited.

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_responses", "name": "proxy_responses" }, { "table": "
Syntax:proxy_ssl on | off;
Default:
proxy_ssl off;
Context:stream, server
", "doc": "

Enables the SSL/TLS protocol for connections to a proxied server.

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_ssl", "name": "proxy_ssl" }, { "table": "
Syntax:proxy_ssl_certificate file;
Default:—
Context:stream, server
", "doc": "

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

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_ssl_certificate", "name": "proxy_ssl_certificate" }, { "table": "
Syntax:proxy_ssl_certificate_key file;
Default:—
Context:stream, server
", "doc": "

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

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_ssl_certificate_key", "name": "proxy_ssl_certificate_key" }, { "table": "
Syntax:proxy_ssl_ciphers ciphers;
Default:
proxy_ssl_ciphers DEFAULT;
Context:stream, server
", "doc": "

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

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

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_ssl_ciphers", "name": "proxy_ssl_ciphers" }, { "table": "
Syntax:proxy_ssl_crl file;
Default:—
Context:stream, server
", "doc": "

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

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_ssl_crl", "name": "proxy_ssl_crl" }, { "table": "
Syntax:proxy_ssl_name name;
Default:
proxy_ssl_name host from proxy_pass;
Context:stream, server
", "doc": "

Allows overriding the server name used to verify the certificate of the proxied server and to be passed through SNI when establishing a connection with the proxied server. The server name can also be specified using variables (1.11.3).

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

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_ssl_name", "name": "proxy_ssl_name" }, { "table": "
Syntax:proxy_ssl_password_file file;
Default:—
Context:stream, server
", "doc": "

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.

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_ssl_password_file", "name": "proxy_ssl_password_file" }, { "table": "
Syntax:proxy_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default:
proxy_ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
Context:stream, server
", "doc": "

Enables the specified protocols for connections to a proxied server.

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_ssl_protocols", "name": "proxy_ssl_protocols" }, { "table": "
Syntax:proxy_ssl_server_name on | off;
Default:
proxy_ssl_server_name off;
Context:stream, server
", "doc": "

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

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_ssl_server_name", "name": "proxy_ssl_server_name" }, { "table": "
Syntax:proxy_ssl_session_reuse on | off;
Default:
proxy_ssl_session_reuse on;
Context:stream, server
", "doc": "

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.

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_ssl_session_reuse", "name": "proxy_ssl_session_reuse" }, { "table": "
Syntax:proxy_ssl_trusted_certificate file;
Default:—
Context:stream, server
", "doc": "

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

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_ssl_trusted_certificate", "name": "proxy_ssl_trusted_certificate" }, { "table": "
Syntax:proxy_ssl_verify on | off;
Default:
proxy_ssl_verify off;
Context:stream, server
", "doc": "

Enables or disables verification of the proxied server certificate.

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_ssl_verify", "name": "proxy_ssl_verify" }, { "table": "
Syntax:proxy_ssl_verify_depth number;
Default:
proxy_ssl_verify_depth 1;
Context:stream, server
", "doc": "

Sets the verification depth in the proxied server certificates chain.

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_ssl_verify_depth", "name": "proxy_ssl_verify_depth" }, { "table": "
Syntax:proxy_timeout timeout;
Default:
proxy_timeout 10m;
Context:stream, server
", "doc": "

Sets the timeout between two successive read or write operations on client or proxied server connections. If no data is transmitted within this time, the connection is closed.

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_timeout", "name": "proxy_timeout" }, { "table": "
Syntax:proxy_upload_rate rate;
Default:
proxy_upload_rate 0;
Context:stream, server

This directive appeared in version 1.9.3.

", "doc": "

Limits the speed of reading the data from the client. The rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a connection, so if the client simultaneously opens two connections, the overall rate will be twice as much as the specified limit.

", "module": "ngx_stream_proxy_module", "link": "stream/ngx_stream_proxy_module.html#proxy_upload_rate", "name": "proxy_upload_rate" }, { "table": "
Syntax:set_real_ip_from address | CIDR | unix:;
Default:—
Context:stream, server
", "doc": "

Defines trusted addresses that are known to send correct replacement addresses. If the special value unix: is specified, all UNIX-domain sockets will be trusted.

", "module": "ngx_stream_realip_module", "link": "stream/ngx_stream_realip_module.html#set_real_ip_from", "name": "set_real_ip_from" }, { "table": "
Syntax:return value;
Default:—
Context:server
", "doc": "

Specifies a value to send to the client. The value can contain text, variables, and their combination.

", "module": "ngx_stream_return_module", "link": "stream/ngx_stream_return_module.html#return", "name": "return" }, { "table": "
Syntax:split_clients string $variable { ... }
Default:—
Context:stream
", "doc": "

Creates a variable for A/B testing, for example:

\nsplit_clients "${remote_addr}AAA" $variant {\n               0.5%               .one;\n               2.0%               .two;\n               *                  "";\n}\n

The value of the original string is hashed using MurmurHash2. In the example given, hash values from 0 to 21474835 (0.5%) correspond to the value ".one" of the $variant variable, hash values from 21474836 to 107374180 (2%) correspond to the value ".two", and hash values from 107374181 to 4294967295 correspond to the value "" (an empty string).

", "module": "ngx_stream_split_clients_module", "link": "stream/ngx_stream_split_clients_module.html#split_clients", "name": "split_clients" }, { "table": "
Syntax:ssl_certificate file;
Default:—
Context:stream, server
", "doc": "

Specifies a file with the certificate in the PEM format for the given server. If intermediate certificates should be specified in addition to a primary certificate, they should be specified in the same file in the following order: the primary certificate comes first, then the intermediate certificates. A secret key in the PEM format may be placed in the same file.

Since version 1.11.0, this directive can be specified multiple times to load certificates of different types, for example, RSA and ECDSA:

\nserver {\n    listen              12345 ssl;\n\n    ssl_certificate     example.com.rsa.crt;\n    ssl_certificate_key example.com.rsa.key;\n\n    ssl_certificate     example.com.ecdsa.crt;\n    ssl_certificate_key example.com.ecdsa.key;\n\n    ...\n}\n
Only OpenSSL 1.0.2 or higher supports separate certificate chains for different certificates. With older versions, only one certificate chain can be used.
", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_certificate", "name": "ssl_certificate" }, { "table": "
Syntax:ssl_certificate_key file;
Default:—
Context:stream, server
", "doc": "

Specifies a file with the secret key in the PEM format for the given server.

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

", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_certificate_key", "name": "ssl_certificate_key" }, { "table": "
Syntax:ssl_ciphers ciphers;
Default:
ssl_ciphers HIGH:!aNULL:!MD5;
Context:stream, server
", "doc": "

Specifies the enabled ciphers. The ciphers are specified in the format understood by the OpenSSL library, for example:

\nssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;\n

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

", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_ciphers", "name": "ssl_ciphers" }, { "table": "
Syntax:ssl_client_certificate file;
Default:—
Context:stream, server

This directive appeared in version 1.11.8.

", "doc": "

Specifies a file with trusted CA certificates in the PEM format used to verify client certificates.

The list of certificates will be sent to clients. If this is not desired, the ssl_trusted_certificate directive can be used.

", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_client_certificate", "name": "ssl_client_certificate" }, { "table": "
Syntax:ssl_crl file;
Default:—
Context:stream, server

This directive appeared in version 1.11.8.

", "doc": "

Specifies a file with revoked certificates (CRL) in the PEM format used to verify client certificates.

", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_crl", "name": "ssl_crl" }, { "table": "
Syntax:ssl_dhparam file;
Default:—
Context:stream, server
", "doc": "

Specifies a file with DH parameters for DHE ciphers.

", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_dhparam", "name": "ssl_dhparam" }, { "table": "
Syntax:ssl_ecdh_curve curve;
Default:
ssl_ecdh_curve auto;
Context:stream, server
", "doc": "

Specifies a curve for ECDHE ciphers.

When using OpenSSL 1.0.2 or higher, it is possible to specify multiple curves (1.11.0), for example:

\nssl_ecdh_curve prime256v1:secp384r1;\n

The special value auto (1.11.0) instructs nginx to use a list built into the OpenSSL library when using OpenSSL 1.0.2 or higher, or prime256v1 with older versions.

Prior to version 1.11.0, the prime256v1 curve was used by default.
", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_ecdh_curve", "name": "ssl_ecdh_curve" }, { "table": "
Syntax:ssl_handshake_timeout time;
Default:
ssl_handshake_timeout 60s;
Context:stream, server
", "doc": "

Specifies a timeout for the SSL handshake to complete.

", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_handshake_timeout", "name": "ssl_handshake_timeout" }, { "table": "
Syntax:ssl_password_file file;
Default:—
Context:stream, server
", "doc": "

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.

Example:

\nstream {\n    ssl_password_file /etc/keys/global.pass;\n    ...\n\n    server {\n        listen 127.0.0.1:12345;\n        ssl_certificate_key /etc/keys/first.key;\n    }\n\n    server {\n        listen 127.0.0.1:12346;\n\n        # named pipe can also be used instead of a file\n        ssl_password_file /etc/keys/fifo;\n        ssl_certificate_key /etc/keys/second.key;\n    }\n}\n
", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_password_file", "name": "ssl_password_file" }, { "table": "
Syntax:ssl_prefer_server_ciphers on | off;
Default:
ssl_prefer_server_ciphers off;
Context:stream, server
", "doc": "

Specifies that server ciphers should be preferred over client ciphers when the SSLv3 and TLS protocols are used.

", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_prefer_server_ciphers", "name": "ssl_prefer_server_ciphers" }, { "table": "
Syntax:ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default:
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
Context:stream, server
", "doc": "

Enables the specified protocols.

The TLSv1.1 and TLSv1.2 parameters work only when OpenSSL 1.0.1 or higher is used.
The TLSv1.3 parameter (1.13.0) works only when OpenSSL 1.1.1 built with TLSv1.3 support is used.
", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_protocols", "name": "ssl_protocols" }, { "table": "
Syntax:ssl_session_cache off | none | [builtin[:size]] [shared:name:size];
Default:
ssl_session_cache none;
Context:stream, server
", "doc": "

Sets the types and sizes of caches that store session parameters. A cache can be of any of the following types:

off
the use of a session cache is strictly prohibited: nginx explicitly tells a client that sessions may not be reused.
none
the use of a session cache is gently disallowed: nginx tells a client that sessions may be reused, but does not actually store session parameters in the cache.
builtin
a cache built in OpenSSL; used by one worker process only. The cache size is specified in sessions. If size is not given, it is equal to 20480 sessions. Use of the built-in cache can cause memory fragmentation.
shared
a cache shared between all worker processes. The cache size is specified in bytes; one megabyte can store about 4000 sessions. Each shared cache should have an arbitrary name. A cache with the same name can be used in several servers.

Both cache types can be used simultaneously, for example:

\nssl_session_cache builtin:1000 shared:SSL:10m;\n

but using only shared cache without the built-in cache should be more efficient.

", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_session_cache", "name": "ssl_session_cache" }, { "table": "
Syntax:ssl_session_ticket_key file;
Default:—
Context:stream, server
", "doc": "

Sets a file with the secret key used to encrypt and decrypt TLS session tickets. The directive is necessary if the same key has to be shared between multiple servers. By default, a randomly generated key is used.

If several keys are specified, only the first key is used to encrypt TLS session tickets. This allows configuring key rotation, for example:

\nssl_session_ticket_key current.key;\nssl_session_ticket_key previous.key;\n

The file must contain 80 or 48 bytes of random data and can be created using the following command:

\nopenssl rand 80 > ticket.key\n

Depending on the file size either AES256 (for 80-byte keys, 1.11.8) or AES128 (for 48-byte keys) is used for encryption.

", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_session_ticket_key", "name": "ssl_session_ticket_key" }, { "table": "
Syntax:ssl_session_tickets on | off;
Default:
ssl_session_tickets on;
Context:stream, server
", "doc": "

Enables or disables session resumption through TLS session tickets.

", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_session_tickets", "name": "ssl_session_tickets" }, { "table": "
Syntax:ssl_session_timeout time;
Default:
ssl_session_timeout 5m;
Context:stream, server
", "doc": "

Specifies a time during which a client may reuse the session parameters.

", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_session_timeout", "name": "ssl_session_timeout" }, { "table": "
Syntax:ssl_trusted_certificate file;
Default:—
Context:stream, server

This directive appeared in version 1.11.8.

", "doc": "

Specifies a file with trusted CA certificates in the PEM format used to verify client certificates.

In contrast to the certificate set by ssl_client_certificate, the list of these certificates will not be sent to clients.

", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_trusted_certificate", "name": "ssl_trusted_certificate" }, { "table": "
Syntax:ssl_verify_client on | off | optional | optional_no_ca;
Default:
ssl_verify_client off;
Context:stream, server

This directive appeared in version 1.11.8.

", "doc": "

Enables verification of client certificates. The verification result is stored in the $ssl_client_verify variable. If an error has occurred during the client certificate verification or a client has not presented the required certificate, the connection is closed.

The optional parameter requests the client certificate and verifies it if the certificate is present.

The optional_no_ca parameter requests the client certificate but does not require it to be signed by a trusted CA certificate. This is intended for the use in cases when a service that is external to nginx performs the actual certificate verification. The contents of the certificate is accessible through the $ssl_client_cert variable.

", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_verify_client", "name": "ssl_verify_client" }, { "table": "
Syntax:ssl_verify_depth number;
Default:
ssl_verify_depth 1;
Context:stream, server

This directive appeared in version 1.11.8.

", "doc": "

Sets the verification depth in the client certificates chain.

", "module": "ngx_stream_ssl_module", "link": "stream/ngx_stream_ssl_module.html#ssl_verify_depth", "name": "ssl_verify_depth" }, { "table": "
Syntax:ssl_preread on | off;
Default:
ssl_preread off;
Context:stream, server
", "doc": "

Enables extracting information from the ClientHello message at the preread phase.

", "module": "ngx_stream_ssl_preread_module", "link": "stream/ngx_stream_ssl_preread_module.html#ssl_preread", "name": "ssl_preread" }, { "table": "
Syntax:upstream name { ... }
Default:—
Context:stream
", "doc": "

Defines a group of servers. Servers can listen on different ports. In addition, servers listening on TCP and UNIX-domain sockets can be mixed.

Example:

\nupstream backend {\n    server backend1.example.com:12345 weight=5;\n    server 127.0.0.1:12345            max_fails=3 fail_timeout=30s;\n    server unix:/tmp/backend2;\n    server backend3.example.com:12345 resolve;\n\n    server backup1.example.com:12345  backup;\n}\n

By default, connections are distributed between the servers using a weighted round-robin balancing method. In the above example, each 7 connections will be distributed as follows: 5 connections go to backend1.example.com:12345 and one connection to each of the second and third servers. If an error occurs during communication with a server, the connection will be passed to the next server, and so on until all of the functioning servers will be tried. If communication with all servers fails, the connection will be closed.

", "module": "ngx_stream_upstream_module", "link": "stream/ngx_stream_upstream_module.html#upstream", "name": "upstream" }, { "table": "
Syntax:server address [parameters];
Default:—
Context:upstream
", "doc": "

Defines the address and other parameters of a server. The address can be specified as a domain name or IP address with an obligatory port, or as a UNIX-domain socket path specified after the “unix:” prefix. A domain name that resolves to several IP addresses defines multiple servers at once.

The following parameters can be defined:

weight=number
sets the weight of the server, by default, 1.
max_conns=number
limits the maximum number of simultaneous connections to the proxied server (1.11.5). Default value is zero, meaning there is no limit. If the server group does not reside in the shared memory, the limitation works per each worker process.
Prior to version 1.11.5, this parameter was available as part of our commercial subscription.
max_fails=number
sets the number of unsuccessful attempts to communicate with the server that should happen in the duration set by the fail_timeout parameter to consider the server unavailable for a duration also set by the fail_timeout parameter. By default, the number of unsuccessful attempts is set to 1. The zero value disables the accounting of attempts. Here, an unsuccessful attempt is an error or timeout while establishing a connection with the server.
fail_timeout=time
setsBy default, the parameter is set to 10 seconds.
backup
marks the server as a backup server. Connections to the backup server will be passed when the primary servers are unavailable.
down
marks the server as permanently unavailable.

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

resolve
monitors changes of the IP addresses that correspond to a domain name of the server, and automatically modifies the upstream configuration without the need of restarting nginx. The server group must reside in the shared memory.

In order for this parameter to work, the resolver directive must be specified in the stream block. Example:

\nstream {\n    resolver 10.0.0.1;\n\n    upstream u {\n        zone ...;\n        ...\n        server example.com:12345 resolve;\n    }\n}\n

service=name
enables resolving of DNS SRV records and sets the service name (1.9.13). In order for this parameter to work, it is necessary to specify the resolve parameter for the server and specify a hostname without a port number.

If the service name does not contain a dot (“.”), then the RFC-compliant name is constructed and the TCP protocol is added to the service prefix. For example, to look up the _http._tcp.backend.example.com SRV record, it is necessary to specify the directive:

\nserver backend.example.com service=http resolve;\n

If the service name contains one or more dots, then the name is constructed by joining the service prefix and the server name. For example, to look up the _http._tcp.backend.example.com and server1.backend.example.com SRV records, it is necessary to specify the directives:

\nserver backend.example.com service=_http._tcp resolve;\nserver example.com service=server1.backend resolve;\n

Highest-priority SRV records (records with the same lowest-number priority value) are resolved as primary servers, the rest of SRV records are resolved as backup servers. If the backup parameter is specified for the server, high-priority SRV records are resolved as backup servers, the rest of SRV records are ignored.

slow_start=time
sets the time during which the server will recover its weight from zero to a nominal value, when unhealthy server becomes healthy, or when the server becomes available after a period of time it was considered unavailable. Default value is zero, i.e. slow start is disabled.
The parameter cannot be used along with the hash load balancing method.
If there is only a single server in a group, max_fails, fail_timeout and slow_start parameters are ignored, and such a server will never be considered unavailable.
", "module": "ngx_stream_upstream_module", "link": "stream/ngx_stream_upstream_module.html#server", "name": "server" }, { "table": "
Syntax:zone name [size];
Default:—
Context:upstream
", "doc": "

Defines the name and size of the shared memory zone that keeps the group’s configuration and run-time state that are shared between worker processes. Several groups may share the same zone. In this case, it is enough to specify the zone size only once.

Additionally, as part of our commercial subscription, such groups allow changing the group membership or modifying the settings of a particular server without the need of restarting nginx. The configuration is accessible via the API module (1.13.3).

Prior to version 1.13.3, the configuration was accessible only via a special location handled by upstream_conf.
", "module": "ngx_stream_upstream_module", "link": "stream/ngx_stream_upstream_module.html#zone", "name": "zone" }, { "table": "
Syntax:state file;
Default:—
Context:upstream

This directive appeared in version 1.9.7.

", "doc": "

Specifies a file that keeps the state of the dynamically configurable group.

Examples:

\nstate /var/lib/nginx/state/servers.conf; # path for Linux\nstate /var/db/nginx/state/servers.conf;  # path for FreeBSD\n

The state is currently limited to the list of servers with their parameters. The file is read when parsing the configuration and is updated each time the upstream configuration is changed. Changing the file content directly should be avoided. The directive cannot be used along with the server directive.

Changes made during configuration reload or binary upgrade can be lost.
This directive is available as part of our commercial subscription.
", "module": "ngx_stream_upstream_module", "link": "stream/ngx_stream_upstream_module.html#state", "name": "state" }, { "table": "
Syntax:hash key [consistent];
Default:—
Context:upstream
", "doc": "

Specifies a load balancing method for a server group where client-server mapping is based on the hashed key value. The key can contain text, variables, and their combinations (1.11.2). Usage example:

\nhash $remote_addr;\n

Note that adding or removing a server from the group may result in remapping most of the keys to different servers. The method is compatible with the Cache::Memcached Perl library.

If the consistent parameter is specified, the ketama consistent hashing method will be used instead. The method ensures that only a few keys will be remapped to different servers when a server is added to or removed from the group. This helps to achieve a higher cache hit ratio for caching servers. The method is compatible with the Cache::Memcached::Fast Perl library with the ketama_points parameter set to 160.

", "module": "ngx_stream_upstream_module", "link": "stream/ngx_stream_upstream_module.html#hash", "name": "hash" }, { "table": "
Syntax:least_conn;
Default:—
Context:upstream
", "doc": "

Specifies that a server group should use a load balancing method where a connection is passed to the server with the least number of active connections, taking into account weights of servers. If there are several such servers, they are tried in turn using a weighted round-robin balancing method.

", "module": "ngx_stream_upstream_module", "link": "stream/ngx_stream_upstream_module.html#least_conn", "name": "least_conn" }, { "table": "
Syntax:least_time connect | first_byte | last_byte [inflight];
Default:—
Context:upstream
", "doc": "

Specifies that a group should use a load balancing method where a connection is passed to the server with the least average time and least number of active connections, taking into account weights of servers. If there are several such servers, they are tried in turn using a weighted round-robin balancing method.

If the connect parameter is specified, time to connect to the upstream server is used. If the first_byte parameter is specified, time to receive the first byte of data is used. If the last_byte is specified, time to receive the last byte of data is used. If the inflight parameter is specified (1.11.6), incomplete connections are also taken into account.

Prior to version 1.11.6, incomplete connections were taken into account by default.
This directive is available as part of our commercial subscription.
", "module": "ngx_stream_upstream_module", "link": "stream/ngx_stream_upstream_module.html#least_time", "name": "least_time" }, { "table": "
Syntax:random [two [method]];
Default:—
Context:upstream

This directive appeared in version 1.15.1.

", "doc": "

Specifies that a group should use a load balancing method where a connection is passed to a randomly selected server, taking into account weights of servers.

The optional two parameter instructs nginx to randomly select two servers and then choose a server using the specified method. The default method is least_conn which passes a connection to a server with the least number of active connections.

", "module": "ngx_stream_upstream_module", "link": "stream/ngx_stream_upstream_module.html#random", "name": "random" }, { "table": "
Syntax:health_check [parameters];
Default:—
Context:server
", "doc": "

Enables periodic health checks of the servers in a group.

The following optional parameters are supported:

interval=time
sets the interval between two consecutive health checks, by default, 5 seconds.
jitter=time
sets the time within which each health check will be randomly delayed, by default, there is no delay.
fails=number
sets the number of consecutive failed health checks of a particular server after which this server will be considered unhealthy, by default, 1.
passes=number
sets the number of consecutive passed health checks of a particular server after which the server will be considered healthy, by default, 1.
mandatory
sets the initial “checking” state for a server until the first health check is completed (1.11.7). Client connections are not passed to servers in the “checking” state. If the parameter is not specified, the server will be initially considered healthy.
match=name
specifies the match block configuring the tests that a successful connection should pass in order for a health check to pass. By default, for TCP, only the ability to establish a TCP connection with the server is checked. For UDP, the absence of ICMP “Destination Unreachable” message is expected in reply to the sent string “nginx health check”.
Prior to version 1.11.7, by default, UDP health check required a match block with the send and expect parameters.
port=number
defines the port used when connecting to a server to perform a health check (1.9.7). By default, equals the server port.
udp
specifies that the UDP protocol should be used for health checks instead of the default TCP protocol (1.9.13).
", "module": "ngx_stream_upstream_hc_module", "link": "stream/ngx_stream_upstream_hc_module.html#health_check", "name": "health_check" }, { "table": "
Syntax:health_check_timeout timeout;
Default:
health_check_timeout 5s;
Context:stream, server
", "doc": "

Overrides the proxy_timeout value for health checks.

", "module": "ngx_stream_upstream_hc_module", "link": "stream/ngx_stream_upstream_hc_module.html#health_check_timeout", "name": "health_check_timeout" }, { "table": "
Syntax:match name { ... }
Default:—
Context:stream
", "doc": "

Defines the named test set used to verify server responses to health checks.

The following parameters can be configured:

send string;
sends a string to the server;
expect string | ~ regex;
a literal string (1.9.12) or a regular expression that the data obtained from the server should match. The regular expression is specified with the preceding “~*” modifier (for case-insensitive matching), or the “~” modifier (for case-sensitive matching).

Both send and expect parameters can contain hexadecimal literals with the prefix “\\x” followed by two hex digits, for example, “\\x80” (1.9.12).

Health check is passed if:

", "module": "ngx_stream_upstream_hc_module", "link": "stream/ngx_stream_upstream_hc_module.html#match", "name": "match" }, { "table": "
Syntax:zone_sync;
Default:—
Context:server
", "doc": "

Enables the synchronization of shared memory zones between cluster nodes. Cluster nodes are defined using zone_sync_server directives.

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync", "name": "zone_sync" }, { "table": "
Syntax:zone_sync_buffers number size;
Default:
zone_sync_buffers 256 4k|8k;
Context:stream, server
", "doc": "

Sets the number and size of the per-zone buffers used for pushing zone contents. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_buffers", "name": "zone_sync_buffers" }, { "table": "
Syntax:zone_sync_connect_retry_interval time;
Default:
zone_sync_connect_retry_interval 1s;
Context:stream, server
", "doc": "

Defines an interval between connection attempts to another cluster node.

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_connect_retry_interval", "name": "zone_sync_connect_retry_interval" }, { "table": "
Syntax:zone_sync_connect_timeout time;
Default:
zone_sync_connect_timeout 5s;
Context:stream, server
", "doc": "

Defines a timeout for establishing a connection with another cluster node.

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_connect_timeout", "name": "zone_sync_connect_timeout" }, { "table": "
Syntax:zone_sync_interval time;
Default:
zone_sync_interval 1s;
Context:stream, server
", "doc": "

Defines an interval for polling updates in a shared memory zone.

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_interval", "name": "zone_sync_interval" }, { "table": "
Syntax:zone_sync_recv_buffer_size size;
Default:
zone_sync_recv_buffer_size 4k|8k;
Context:stream, server
", "doc": "

Sets size of a per-connection receive buffer used to parse incoming stream of synchronization messages. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_recv_buffer_size", "name": "zone_sync_recv_buffer_size" }, { "table": "
Syntax:zone_sync_server address [resolve];
Default:—
Context:server
", "doc": "

Defines the address of a cluster node. The address can be specified as a domain name or IP address with a mandatory port, or as a UNIX-domain socket path specified after the “unix:” prefix. A domain name that resolves to several IP addresses defines multiple nodes at once.

The resolve parameter instructs nginx to monitor changes of the IP addresses that correspond to a domain name of the node and automatically modify the configuration without the need of restarting nginx.

Cluster nodes are specified either dynamically as a single zone_sync_server directive with the resolve parameter, or statically as a series of several directives without the parameter.

Each cluster node should be specified only once.
All cluster nodes should use the same configuration.

In order for the resolve parameter to work, the resolver directive must be specified in the stream block. Example:

\nstream {\n    resolver 10.0.0.1;\n\n    server {\n        zone_sync;\n        zone_sync_server cluster.example.com resolve;\n        ...\n    }\n}\n
", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_server", "name": "zone_sync_server" }, { "table": "
Syntax:zone_sync_ssl on | off;
Default:
zone_sync_ssl off;
Context:stream, server
", "doc": "

Enables the SSL/TLS protocol for connections to another cluster server.

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_ssl", "name": "zone_sync_ssl" }, { "table": "
Syntax:zone_sync_ssl_certificate file;
Default:—
Context:stream, server
", "doc": "

Specifies a file with the certificate in the PEM format used for authentication to another cluster server.

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_ssl_certificate", "name": "zone_sync_ssl_certificate" }, { "table": "
Syntax:zone_sync_ssl_certificate_key file;
Default:—
Context:stream, server
", "doc": "

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

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_ssl_certificate_key", "name": "zone_sync_ssl_certificate_key" }, { "table": "
Syntax:zone_sync_ssl_ciphers ciphers;
Default:
zone_sync_ssl_ciphers DEFAULT;
Context:stream, server
", "doc": "

Specifies the enabled ciphers for connections to another cluster server. The ciphers are specified in the format understood by the OpenSSL library.

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

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_ssl_ciphers", "name": "zone_sync_ssl_ciphers" }, { "table": "
Syntax:zone_sync_ssl_crl file;
Default:—
Context:stream, server
", "doc": "

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

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_ssl_crl", "name": "zone_sync_ssl_crl" }, { "table": "
Syntax:zone_sync_ssl_password_file file;
Default:—
Context:stream, server
", "doc": "

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.

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_ssl_password_file", "name": "zone_sync_ssl_password_file" }, { "table": "
Syntax:zone_sync_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default:
zone_sync_ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
Context:stream, server
", "doc": "

Enables the specified protocols for connections to another cluster server.

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_ssl_protocols", "name": "zone_sync_ssl_protocols" }, { "table": "
Syntax:zone_sync_ssl_trusted_certificate file;
Default:—
Context:stream, server
", "doc": "

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

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_ssl_trusted_certificate", "name": "zone_sync_ssl_trusted_certificate" }, { "table": "
Syntax:zone_sync_ssl_verify on | off;
Default:
zone_sync_ssl_verify off;
Context:stream, server
", "doc": "

Enables or disables verification of another cluster server certificate.

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_ssl_verify", "name": "zone_sync_ssl_verify" }, { "table": "
Syntax:zone_sync_ssl_verify_depth number;
Default:
zone_sync_ssl_verify_depth 1;
Context:stream, server
", "doc": "

Sets the verification depth in another cluster server certificates chain.

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_ssl_verify_depth", "name": "zone_sync_ssl_verify_depth" }, { "table": "
Syntax:zone_sync_timeout timeout;
Default:
zone_sync_timeout 5s;
Context:stream, server
", "doc": "

Sets the timeout between two successive read or write operations on connection to another cluster node. If no data is transmitted within this time, the connection is closed.

", "module": "ngx_stream_zone_sync_module", "link": "stream/ngx_stream_zone_sync_module.html#zone_sync_timeout", "name": "zone_sync_timeout" }, { "table": "
Syntax:google_perftools_profiles file;
Default:—
Context:main
", "doc": "

Sets a file name that keeps profiling information of nginx worker process. The ID of the worker process is always a part of the file name and is appended to the end of the file name, after a dot.

", "module": "ngx_google_perftools_module", "link": "ngx_google_perftools_module.html#google_perftools_profiles", "name": "google_perftools_profiles" } ]