Nginx Configuration All In One¶

Core functionality¶

accept_mutex¶

Syntax: accept_mutex on | off;
Default: accept_mutex off;
Context: events
@Since: None

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.

Note

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.

accept_mutex_delay¶

Syntax: accept_mutex_delay time;
Default: accept_mutex_delay 500ms;
Context: events
@Since: None

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.

daemon¶

Syntax: daemon on | off;
Default: daemon on;
Context: main
@Since: None

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

debug_connection¶

Syntax: debug_connection address | CIDR | unix;
Default: —
Context: events
@Since: None

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.

events {
    debug_connection 127.0.0.1;
    debug_connection localhost;
    debug_connection 192.0.2.0/24;
    debug_connection ::1;
    debug_connection 2001:0db8::/32;
    debug_connection unix:;
    ...
}

For this directive to work, nginx needs to be built with --with-debug, see “A debugging log”.

debug_points¶

Syntax: debug_points abort | stop;
Default: —
Context: main
@Since: None

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.

env¶

Syntax: env variable[=value];
Default: env TZ;
Context: main
@Since: None

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:

inherited during a live upgrade of an executable file;
used by the ngx_http_perl_module module;
used by worker processes. One should bear in mind that controlling system libraries in this way is not always possible as it is common for libraries to check variables only during initialization, well before they can be set using this directive. An exception from this is an above mentioned live upgrade of an executable file.

The TZ variable is always inherited and available to the ngx_http_perl_module module, unless it is configured explicitly.

Usage example:

env MALLOC_OPTIONS;
env PERL5LIB=/data/site/modules;
env OPENSSL_ALLOW_PROXY_CERTS=1;

The NGINX environment variable is used internally by nginx and should not be set directly by the user.

error_log¶

Syntax: error_log file [level];
Default: error_log logs/error.log error;
Context: main, http, mail, stream, server, location
@Since: None

Configures logging. Several logs can be specified on the same configuration 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 “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”.

Note

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.

events¶

Syntax: events { ... }
Default: —
Context: main
@Since: None

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

include¶

Syntax: include file | mask;
Default: —
Context: any
@Since: None

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

Usage example:

include mime.types;
include vhosts/*.conf;

load_module¶

Syntax: load_module file;
Default: —
Context: main
@Since: This directive appeared in version 1.9.11.

Loads a dynamic module.

Example:

load_module modules/ngx_mail_module.so;

lock_file¶

Syntax: lock_file file;
Default: lock_file logs/nginx.lock;
Context: main
@Since: None

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.

master_process¶

Syntax: master_process on | off;
Default: master_process on;
Context: main
@Since: None

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

multi_accept¶

Syntax: multi_accept on | off;
Default: multi_accept off;
Context: events
@Since: None

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.

pcre_jit¶

Syntax: pcre_jit on | off;
Default: pcre_jit off;
Context: main
@Since: This directive appeared in version 1.1.12.

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.

pid¶

Syntax: pid file;
Default: pid logs/nginx.pid;
Context: main
@Since: None

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

ssl_engine¶

Syntax: ssl_engine device;
Default: —
Context: main
@Since: None

Defines the name of the hardware SSL accelerator.

The module may be dynamically loaded by OpenSSL during configuration testing.

ssl_object_cache_inheritable¶

Syntax: ssl_object_cache_inheritable on | off;
Default: ssl_object_cache_inheritable on;
Context: main
@Since: This directive appeared in version 1.27.4.

If enabled, SSL objects (SSL certificates, secret keys, trusted CA certificates, CRL lists) will be inherited across configuration reloads.

SSL objects loaded from a file are inherited if the modification time and file index has not been changed since the previous configuration load. Secret keys specified as engine:name:id are never inherited. Secret keys specified as data:value are always inherited.

SSL objects loaded from variables cannot be inherited.

Example:

ssl_object_cache_inheritable on;
http {
    ...
    server {
        ...
        ssl_certificate     example.com.crt;
        ssl_certificate_key example.com.key;
    }
}

stall_threshold [commercial]¶

Syntax: stall_threshold time;
Default: stall_threshold 1000ms;
Context: events
@Since: This directive appeared in version 1.29.0.

Allows overriding the default time threshold for the event loop iteration before a stall is reported. By default, a stall is reported when an event loop iteration exceeds 1000ms. If the timer_resolution directive is enabled, the time threshold will be ignored.

This directive is available as part of our commercial subscription.

thread_pool¶

Syntax: thread_pool name threads=number [max_queue=number];
Default: thread_pool default threads=32 max_queue=65536;
Context: main
@Since: This directive appeared in version 1.7.11.

Defines the name and parameters of a thread pool 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.

timer_resolution¶

Syntax: timer_resolution interval;
Default: —
Context: main
@Since: None

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:

timer_resolution 100ms;

Internal implementation of the interval depends on the method used:

the EVFILT_TIMER filter if kqueue is used;
timer_create() if eventport is used;
setitimer() otherwise.

use¶

Syntax: use method;
Default: —
Context: events
@Since: None

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.

user¶

Syntax: user user [group];
Default: user nobody nobody;
Context: main
@Since: None

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

worker_aio_requests¶

Syntax: worker_aio_requests number;
Default: worker_aio_requests 32;
Context: events
@Since: This directive appeared in versions 1.1.4 and 1.0.7.

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

worker_connections¶

Syntax: worker_connections number;
Default: worker_connections 512;
Context: events
@Since: None

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.

worker_cpu_affinity¶

Syntax: worker_cpu_affinity cpumask ...; worker_cpu_affinity auto [cpumask];
Default: —
Context: main
@Since: None

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:

worker_processes    4;
worker_cpu_affinity 0001 0010 0100 1000;

binds each worker process to a separate CPU, while

worker_processes    2;
worker_cpu_affinity 0101 1010;

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:

worker_processes auto;
worker_cpu_affinity auto;

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

worker_cpu_affinity auto 01010101;

The directive is only available on FreeBSD and Linux.

worker_priority¶

Syntax: worker_priority number;
Default: worker_priority 0;
Context: main
@Since: None

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:

worker_priority -10;

worker_processes¶

Syntax: worker_processes number | auto;
Default: worker_processes 1;
Context: main
@Since: None

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.

worker_rlimit_core¶

Syntax: worker_rlimit_core size;
Default: —
Context: main
@Since: None

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.

worker_rlimit_nofile¶

Syntax: worker_rlimit_nofile number;
Default: —
Context: main
@Since: None

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.

worker_shutdown_timeout¶

Syntax: worker_shutdown_timeout time;
Default: —
Context: main
@Since: This directive appeared in version 1.11.11.

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.

working_directory¶

Syntax: working_directory directory;
Default: —
Context: main
@Since: None

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.

ngx_http_core_module¶

absolute_redirect¶

Syntax: absolute_redirect on | off;
Default: absolute_redirect on;
Context: http, server, location
@Since: This directive appeared in version 1.11.8.

If disabled, redirects issued by nginx will be relative.

See also server_name_in_redirect and port_in_redirect directives.

aio¶

Syntax: aio on | off | threads[=pool];
Default: aio off;
Context: http, server, location
@Since: This directive appeared in version 0.8.11.

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

location /video/ {
    aio            on;
    output_buffers 1 64k;
}

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:

options VFS_AIO

or loaded dynamically as a kernel loadable module:

kldload aio

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:

location /video/ {
    aio            on;
    directio       512;
    output_buffers 1 128k;
}

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.

location /video/ {
    sendfile       on;
    aio            on;
    directio       8m;
}

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

location /video/ {
    sendfile       on;
    aio            threads;
}

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:

aio threads=pool$disk;

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.

aio_write¶

Syntax: aio_write on | off;
Default: aio_write off;
Context: http, server, location
@Since: This directive appeared in version 1.9.13.

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.

alias¶

Syntax: alias path;
Default: —
Context: location
@Since: None

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

location /i/ {
    alias /data/w3/images/;
}

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:

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

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

location /images/ {
    alias /data/w3/images/;
}

it is better to use the root directive instead:

location /images/ {
    root /data/w3;
}

auth_delay¶

Syntax: auth_delay time;
Default: auth_delay 0s;
Context: http, server, location
@Since: This directive appeared in version 1.17.10.

Delays processing of unauthorized requests with 401 response code to prevent timing attacks when access is limited by password, by the result of subrequest, or by JWT.

chunked_transfer_encoding¶

Syntax: chunked_transfer_encoding on | off;
Default: chunked_transfer_encoding on;
Context: http, server, location
@Since: None

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.

client_body_buffer_size¶

Syntax: client_body_buffer_size size;
Default: client_body_buffer_size 8k|16k;
Context: http, server, location
@Since: None

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.

client_body_in_file_only¶

Syntax: client_body_in_file_only on | clean | off;
Default: client_body_in_file_only off;
Context: http, server, location
@Since: None

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.

client_body_in_single_buffer¶

Syntax: client_body_in_single_buffer on | off;
Default: client_body_in_single_buffer off;
Context: http, server, location
@Since: None

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.

client_body_temp_path¶

Syntax: client_body_temp_path path [level1 [level2 [level3]]];
Default: client_body_temp_path client_body_temp;
Context: http, server, location
@Since: None

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:

client_body_temp_path /spool/nginx/client_temp 1 2;

a path to a temporary file might look like this:

/spool/nginx/client_temp/7/45/00000123457

client_body_timeout¶

Syntax: client_body_timeout time;
Default: client_body_timeout 60s;
Context: http, server, location
@Since: None

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 request is terminated with the 408 (Request Time-out) error.

client_header_buffer_size¶

Syntax: client_header_buffer_size size;
Default: client_header_buffer_size 1k;
Context: http, server
@Since: None

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.

If the directive is specified on the server level, the value from the default server can be used. Details are provided in the “Virtual server selection” section.

client_header_timeout¶

Syntax: client_header_timeout time;
Default: client_header_timeout 60s;
Context: http, server
@Since: None

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

client_max_body_size¶

Syntax: client_max_body_size size;
Default: client_max_body_size 1m;
Context: http, server, location
@Since: None

Sets the maximum allowed size of the client request body. 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.

connection_pool_size¶

Syntax: connection_pool_size size;
Default: connection_pool_size 256|512;
Context: http, server
@Since: None

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.

default_type¶

Syntax: default_type mime-type;
Default: default_type text/plain;
Context: http, server, location
@Since: None

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

directio¶

Syntax: directio size | off;
Default: directio off;
Context: http, server, location
@Since: This directive appeared in version 0.7.7.

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:

directio 4m;

or when using aio on Linux.

directio_alignment¶

Syntax: directio_alignment size;
Default: directio_alignment 512;
Context: http, server, location
@Since: This directive appeared in version 0.8.11.

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.

disable_symlinks¶

Syntax: disable_symlinks off; disable_symlinks on | if_not_owner [from=part];
Default: disable_symlinks off;
Context: http, server, location
@Since: This directive appeared in version 1.1.15.

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:

disable_symlinks on from=$document_root;

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.

Note

The ngx_http_autoindex_module, ngx_http_random_index_module, and ngx_http_dav_module modules currently ignore this directive.

early_hints¶

Syntax: early_hints string ...;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.29.0.

Defines conditions under which the 103 (Early Hints) response will be passed to a client. If at least one value of the string parameters is not empty and is not equal to “0” then the response will be passed:

map $http_sec_fetch_mode $early_hints {
    navigate $http2$http3;
}

server {
    ...
    location / {
        early_hints $early_hints;
        proxy_pass http://example.com;
    }
}

error_page¶

Syntax: error_page code ... [=[response]] uri;
Default: —
Context: http, server, location, if in location
@Since: None

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

Example:

error_page 404             /404.html;
error_page 500 502 503 504 /50x.html;

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:

error_page 404 =200 /empty.gif;

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:

error_page 404 = /404.php;

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

location / {
    error_page 404 = @fallback;
}

location @fallback {
    proxy_pass http://backend;
}

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:

error_page 403      http://example.com/forbidden.html;
error_page 404 =301 http://example.com/notfound.html;

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

Note

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 configuration level if and only if there are no error_page directives defined on the current level.

etag¶

Syntax: etag on | off;
Default: etag on;
Context: http, server, location
@Since: This directive appeared in version 1.3.3.

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

http¶

Syntax: http { ... }
Default: —
Context: main
@Since: None

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

if_modified_since¶

Syntax: if_modified_since off | exact | before;
Default: if_modified_since exact;
Context: http, server, location
@Since: This directive appeared in version 0.7.24.

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

off: the response is always considered modified (0.7.34);
exact: exact match;
before: modification time of the response is less than or equal to the time in the “If-Modified-Since” request header field.

ignore_invalid_headers¶

Syntax: ignore_invalid_headers on | off;
Default: ignore_invalid_headers on;
Context: http, server
@Since: None

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, the value from the default server can be used. Details are provided in the "Virtual server selection" section.

internal¶

Syntax: internal;
Default: —
Context: location
@Since: None

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:

requests redirected by the error_page, index, internal_redirect, random_index, and try_files directives;
requests redirected by the “X-Accel-Redirect” response header field from an upstream server;
subrequests formed by the “include virtual” command of the ngx_http_ssi_module module, by the ngx_http_addition_module module directives, and by auth_request and mirror directives;
requests changed by the rewrite directive.

Example:

error_page 404 /404.html;

location = /404.html {
    internal;
}

There is a limit of 10 internal redirects per request to prevent request processing cycles that can occur in incorrect configurations. If this limit is reached, the error 500 (Internal Server Error) is returned. In such cases, the “rewrite or internal redirection cycle” message can be seen in the error log.

keepalive_disable¶

Syntax: keepalive_disable none | browser ...;
Default: keepalive_disable msie6;
Context: http, server, location
@Since: None

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.

keepalive_min_timeout¶

Syntax: keepalive_min_timeout timeout;
Default: keepalive_min_timeout 0;
Context: http, server, location
@Since: This directive appeared in version 1.27.4.

Sets a timeout during which a keep-alive client connection will not be closed on the server side for connection reuse or on graceful shutdown of worker processes.

keepalive_requests¶

Syntax: keepalive_requests number;
Default: keepalive_requests 1000;
Context: http, server, location
@Since: This directive appeared in version 0.8.0.

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.

Closing connections periodically is necessary to free per-connection memory allocations. Therefore, using too high maximum number of requests could result in excessive memory usage and not recommended.

Prior to version 1.19.10, the default value was 100.

keepalive_time¶

Syntax: keepalive_time time;
Default: keepalive_time 1h;
Context: http, server, location
@Since: This directive appeared in version 1.19.10.

Limits the maximum time during which requests can be processed through one keep-alive connection. After this time is reached, the connection is closed following the subsequent request processing.

keepalive_timeout¶

Syntax: keepalive_timeout timeout [header_timeout];
Default: keepalive_timeout 75s;
Context: http, server, location
@Since: None

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.

large_client_header_buffers¶

Syntax: large_client_header_buffers number size;
Default: large_client_header_buffers 4 8k;
Context: http, server
@Since: None

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.

If the directive is specified on the server level, the value from the default server can be used. Details are provided in the "Virtual server selection" section.

limit_except¶

Syntax: limit_except method ... { ... }
Default: —
Context: location
@Since: None

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:

limit_except GET {
    allow 192.168.1.0/32;
    deny  all;
}

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

limit_rate¶

Syntax: limit_rate rate;
Default: limit_rate 0;
Context: http, server, location, if in location
@Since: None

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.

Parameter value can contain variables (1.17.0). It may be useful in cases where rate should be limited depending on a certain condition:

map $slow $rate {
    1     4k;
    2     8k;
}

limit_rate $rate;

Rate limit can also be set in the $limit_rate variable, however, since version 1.17.0, this method is not recommended:

server {

    if ($slow) {
        set $limit_rate 4k;
    }

    ...
}

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.

limit_rate_after¶

Syntax: limit_rate_after size;
Default: limit_rate_after 0;
Context: http, server, location, if in location
@Since: This directive appeared in version 0.8.0.

Sets the initial amount after which the further transmission of a response to a client will be rate limited. Parameter value can contain variables (1.17.0).

Example:

location /flv/ {
    flv;
    limit_rate_after 500k;
    limit_rate       50k;
}

lingering_close¶

Syntax: lingering_close off | on | always;
Default: lingering_close on;
Context: http, server, location
@Since: This directive appeared in versions 1.1.0 and 1.0.6.

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.

To control closing HTTP/2 connections, the directive must be specified on the server level (1.19.1).

lingering_time¶

Syntax: lingering_time time;
Default: lingering_time 30s;
Context: http, server, location
@Since: None

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.

lingering_timeout¶

Syntax: lingering_timeout time;
Default: lingering_timeout 5s;
Context: http, server, location
@Since: None

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.

listen address¶

Syntax: listen address[:port] [default_server] [ssl] [http2 | quic] [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 | quic] [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 | quic] [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
@Since: None

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:

listen 127.0.0.1:8000;
listen 127.0.0.1;
listen 8000;
listen *:8000;
listen localhost:8000;

IPv6 addresses (0.7.36) are specified in square brackets:

listen [::]:8000;
listen [::1];

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

listen unix:/var/run/nginx.sock;

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 parameter is deprecated, the http2 directive should be used instead.

The quic parameter (1.25.0) configures the port to accept QUIC connections.

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, fastopen, backlog, rcvbuf, sndbuf, accept_filter, deferred, ipv6only, reuseport, 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 on Linux 3.9+ and DragonFly BSD, or SO_REUSEPORT_LB on FreeBSD 12+), allowing a kernel to distribute incoming connections between worker processes. This currently works only on Linux 3.9+, DragonFly BSD, and FreeBSD 12+ (1.15.1). >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, NetBSD, Dragonfly, FreeBSD, and macOS), 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:

listen 127.0.0.1 default_server accept_filter=dataready backlog=1024;

location¶

Syntax: location [ = | ~ | ~* | ^~ ] uri { ... } location @name { ... }
Default: —
Context: server, location
@Since: None

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.

Note

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:

location = / {
    [ configuration A ]
}

location / {
    [ configuration B ]
}

location /documents/ {
    [ configuration C ]
}

location ^~ /images/ {
    [ configuration D ]
}

location ~* \.(gif|jpg|jpeg)$ {
    [ configuration E ]
}

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:

location /user/ {
    proxy_pass http://user.example.com;
}

location = /user {
    proxy_pass http://login.example.com;
}

log_not_found¶

Syntax: log_not_found on | off;
Default: log_not_found on;
Context: http, server, location
@Since: None

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

log_subrequest¶

Syntax: log_subrequest on | off;
Default: log_subrequest off;
Context: http, server, location
@Since: None

Enables or disables logging of subrequests into access_log.

max_ranges¶

Syntax: max_ranges number;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.1.2.

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.

merge_slashes¶

Syntax: merge_slashes on | off;
Default: merge_slashes on;
Context: http, server
@Since: None

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:

location /scripts/ {
    ...
}

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, the value from the default server can be used. Details are provided in the "Virtual server selection" section.

msie_padding¶

Syntax: msie_padding on | off;
Default: msie_padding on;
Context: http, server, location
@Since: None

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

msie_refresh¶

Syntax: msie_refresh on | off;
Default: msie_refresh off;
Context: http, server, location
@Since: None

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

open_file_cache¶

Syntax: open_file_cache off; open_file_cache max=N [inactive=time];
Default: open_file_cache off;
Context: http, server, location
@Since: None

Configures a cache that can store:

open file descriptors, their sizes and modification times;
information on existence of directories;
file lookup errors, such as “file not found”, “no read permission”, and so on. >Caching of errors should be enabled separately by the open_file_cache_errors directive.

The directive has the following parameters:

max: sets the maximum number of elements in the cache; on cache overflow the least recently used (LRU) elements are removed;
inactive: defines a time after which an element is removed from the cache if it has not been accessed during this time; by default, it is 60 seconds;
off: disables the cache.

Example:

open_file_cache          max=1000 inactive=20s;
open_file_cache_valid    30s;
open_file_cache_min_uses 2;
open_file_cache_errors   on;

open_file_cache_errors¶

Syntax: open_file_cache_errors on | off;
Default: open_file_cache_errors off;
Context: http, server, location
@Since: None

Enables or disables caching of file lookup errors by open_file_cache.

open_file_cache_min_uses¶

Syntax: open_file_cache_min_uses number;
Default: open_file_cache_min_uses 1;
Context: http, server, location
@Since: None

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.

open_file_cache_valid¶

Syntax: open_file_cache_valid time;
Default: open_file_cache_valid 60s;
Context: http, server, location
@Since: None

Sets a time after which open_file_cache elements should be validated.

output_buffers¶

Syntax: output_buffers number size;
Default: output_buffers 2 32k;
Context: http, server, location
@Since: None

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.

port_in_redirect¶

Syntax: port_in_redirect on | off;
Default: port_in_redirect on;
Context: http, server, location
@Since: None

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.

postpone_output¶

Syntax: postpone_output size;
Default: postpone_output 1460;
Context: http, server, location
@Since: None

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.

read_ahead¶

Syntax: read_ahead size;
Default: read_ahead 0;
Context: http, server, location
@Since: None

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.

recursive_error_pages¶

Syntax: recursive_error_pages on | off;
Default: recursive_error_pages off;
Context: http, server, location
@Since: None

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

request_pool_size¶

Syntax: request_pool_size size;
Default: request_pool_size 4k;
Context: http, server
@Since: None

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

reset_timedout_connection¶

Syntax: reset_timedout_connection on | off;
Default: reset_timedout_connection off;
Context: http, server, location
@Since: None

Enables or disables resetting timed out connections and connections closed with the non-standard code 444 (1.15.2). 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.

resolver¶

Syntax: resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone];
Default: —
Context: http, server, location
@Since: None

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

resolver 127.0.0.1 [::1]:5353;

The address can be specified as a domain name or IP address, with 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 IPv4 or IPv6 addresses is not desired, the ipv4=off (1.23.1) or 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:

resolver 127.0.0.1 [::1]:5353 valid=30s;

Note

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.

The optional status_zone parameter (1.17.1) enables collection of DNS server statistics of requests and responses in the specified zone. The parameter is available as part of our commercial subscription.

resolver_timeout¶

Syntax: resolver_timeout time;
Default: resolver_timeout 30s;
Context: http, server, location
@Since: None

Sets a timeout for name resolution, for example:

resolver_timeout 5s;

root¶

Syntax: root path;
Default: root html;
Context: http, server, location, if in location
@Since: None

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

location /i/ {
    root /data/w3;
}

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.

satisfy¶

Syntax: satisfy all | any;
Default: satisfy all;
Context: http, server, location
@Since: None

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, ngx_http_auth_jwt_module (1.13.10), or ngx_http_auth_oidc_module (1.27.4) modules allow access.

Example:

location / {
    satisfy any;

    allow 192.168.1.0/32;
    deny  all;

    auth_basic           "closed site";
    auth_basic_user_file conf/htpasswd;
}

send_lowat¶

Syntax: send_lowat size;
Default: send_lowat 0;
Context: http, server, location
@Since: None

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.

Warning

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

send_timeout¶

Syntax: send_timeout time;
Default: send_timeout 60s;
Context: http, server, location
@Since: None

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.

sendfile¶

Syntax: sendfile on | off;
Default: sendfile off;
Context: http, server, location, if in location
@Since: None

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():

location /video/ {
    sendfile       on;
    tcp_nopush     on;
    aio            on;
}

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.

Note

Before version 1.7.11, pre-loading could be enabled with aio sendfile;.

sendfile_max_chunk¶

Syntax: sendfile_max_chunk size;
Default: sendfile_max_chunk 2m;
Context: http, server, location
@Since: None

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.

Prior to version 1.21.4, by default there was no limit.

server¶

Syntax: server { ... }
Default: —
Context: http
@Since: None

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.

server_name¶

Syntax: server_name name ...;
Default: server_name "";
Context: server
@Since: None

Sets names of a virtual server, for example:

server {
    server_name example.com www.example.com;
}

The first name becomes the primary server name.

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

server {
    server_name example.com *.example.com www.example.*;
}

Such names are called wildcard names.

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

server {
    server_name .example.com;
}

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

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

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

server {
    server_name ~^(www\.)?(.+)$;

    location / {
        root /sites/$2;
    }
}

server {
    server_name _;

    location / {
        root /sites/default;
    }
}

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

server {
    server_name ~^(www\.)?(?<domain>.+)$;

    location / {
        root /sites/$domain;
    }
}

server {
    server_name _;

    location / {
        root /sites/default;
    }
}

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):

server {
    server_name www.example.com "";
}

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:

the exact name
the longest wildcard name starting with an asterisk, e.g. "*.example.com"
the longest wildcard name ending with an asterisk, e.g. "mail.*"
the first matching regular expression (in order of appearance in the configuration file)

Detailed description of server names is provided in a separate Server names document.

server_name_in_redirect¶

Syntax: server_name_in_redirect on | off;
Default: server_name_in_redirect off;
Context: http, server, location
@Since: None

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.

server_names_hash_bucket_size¶

Syntax: server_names_hash_bucket_size size;
Default: server_names_hash_bucket_size 32|64|128;
Context: http
@Since: None

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.

server_names_hash_max_size¶

Syntax: server_names_hash_max_size size;
Default: server_names_hash_max_size 512;
Context: http
@Since: None

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

server_tokens [commercial]¶

Syntax: server_tokens on | off | build | string;
Default: server_tokens on;
Context: http, server, location
@Since: None

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

The build parameter (1.11.10) enables emitting a build name along with nginx version.

Additionally, as part of our commercial subscription, starting from version 1.9.13 the signature on error pages and the "Server" response header field value can be set explicitly using the string with variables. An empty string disables the emission of the "Server" field.

subrequest_output_buffer_size¶

Syntax: subrequest_output_buffer_size size;
Default: subrequest_output_buffer_size 4k|8k;
Context: http, server, location
@Since: This directive appeared in version 1.13.10.

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.

tcp_nodelay¶

Syntax: tcp_nodelay on | off;
Default: tcp_nodelay on;
Context: http, server, location
@Since: None

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.

tcp_nopush¶

Syntax: tcp_nopush on | off;
Default: tcp_nopush off;
Context: http, server, location
@Since: None

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

sending the response header and the beginning of a file in one packet, on Linux and FreeBSD 4.*;
sending a file in full packets.

try_files¶

Syntax: try_files file ... uri; try_files file ... =code;
Default: —
Context: server, location
@Since: None

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:

location /images/ {
    try_files $uri /images/default.gif;
}

location = /images/default.gif {
    expires 30s;
}

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:

location / {
    try_files $uri $uri/index.html $uri.html =404;
}

Example in proxying Mongrel:

location / {
    try_files /system/maintenance.html
              $uri $uri/index.html $uri.html
              @mongrel;
}

location @mongrel {
    proxy_pass http://mongrel;
}

Example for Drupal/FastCGI:

location / {
    try_files $uri $uri/ @drupal;
}

location ~ \.php$ {
    try_files $uri @drupal;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
    fastcgi_param SCRIPT_NAME     $fastcgi_script_name;
    fastcgi_param QUERY_STRING    $args;

    ... other fastcgi_param's
}

location @drupal {
    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to/index.php;
    fastcgi_param SCRIPT_NAME     /index.php;
    fastcgi_param QUERY_STRING    q=$uri&$args;

    ... other fastcgi_param's
}

In the following example:

location / {
    try_files $uri $uri/ @drupal;
}

the try_files directive is equivalent to

location / {
    error_page 404 = @drupal;
    log_not_found off;
}

And here:

location ~ \.php$ {
    try_files $uri @drupal;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;

    ...
}

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

Example for Wordpress and Joomla:

location / {
    try_files $uri $uri/ @wordpress;
}

location ~ \.php$ {
    try_files $uri @wordpress;

    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
    ... other fastcgi_param's
}

location @wordpress {
    fastcgi_pass ...;

    fastcgi_param SCRIPT_FILENAME /path/to/index.php;
    ... other fastcgi_param's
}

types¶

Syntax: types { ... }
Default: types { text/html html; image/gif gif; image/jpeg jpg; }
Context: http, server, location
@Since: None

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

types {
    application/octet-stream bin exe dll;
    application/octet-stream deb;
    application/octet-stream dmg;
}

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:

location /download/ {
    types        { }
    default_type application/octet-stream;
}

types_hash_bucket_size¶

Syntax: types_hash_bucket_size size;
Default: types_hash_bucket_size 64;
Context: http, server, location
@Since: None

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.

types_hash_max_size¶

Syntax: types_hash_max_size size;
Default: types_hash_max_size 1024;
Context: http, server, location
@Since: None

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

underscores_in_headers¶

Syntax: underscores_in_headers on | off;
Default: underscores_in_headers off;
Context: http, server
@Since: None

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, the value from the default server can be used. Details are provided in the "Virtual server selection" section.

variables_hash_bucket_size¶

Syntax: variables_hash_bucket_size size;
Default: variables_hash_bucket_size 64;
Context: http
@Since: None

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

variables_hash_max_size¶

Syntax: variables_hash_max_size size;
Default: variables_hash_max_size 1024;
Context: http
@Since: None

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.

ngx_http_access_module¶

allow¶

Syntax: allow address | CIDR | unix: | all;
Default: —
Context: http, server, location, limit_except
@Since: None

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.

deny¶

Syntax: deny address | CIDR | unix: | all;
Default: —
Context: http, server, location, limit_except
@Since: None

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.

ngx_http_addition_module¶

add_before_body¶

Syntax: add_before_body uri;
Default: —
Context: http, server, location
@Since: None

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.

add_after_body¶

Syntax: add_after_body uri;
Default: —
Context: http, server, location
@Since: None

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.

addition_types¶

Syntax: addition_types mime-type ...;
Default: addition_types text/html;
Context: http, server, location
@Since: This directive appeared in version 0.7.9.

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

ngx_http_api_module¶

api¶

Syntax: api [write=on|off];
Default: —
Context: location
@Since: None

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

[api] status_zone¶

Syntax: status_zone zone;
Default: —
Context: server, location, if in location
@Since: This directive appeared in version 1.13.12.

Enables collection of virtual http or stream server status information in the specified zone. Several servers may share the same zone.

ngx_http_auth_basic_module¶

auth_basic¶

Syntax: auth_basic string | off;
Default: auth_basic off;
Context: http, server, location, limit_except
@Since: None

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 cancels the effect of the auth_basic directive inherited from the previous configuration level.

auth_basic_user_file¶

Syntax: auth_basic_user_file file;
Default: —
Context: http, server, location, limit_except
@Since: None

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

ngx_http_auth_jwt_module¶

auth_jwt¶

Syntax: auth_jwt string [token=$variable] | off;
Default: auth_jwt off;
Context: http, server, location, limit_except
@Since: None

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

auth_jwt_claim_set¶

Syntax: auth_jwt_claim_set $variable name ...;
Default: —
Context: http
@Since: This directive appeared in version 1.11.10.

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.

auth_jwt_header_set¶

Syntax: auth_jwt_header_set $variable name ...;
Default: —
Context: http
@Since: This directive appeared in version 1.11.10.

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.

auth_jwt_key_cache¶

Syntax: auth_jwt_key_cache time;
Default: auth_jwt_key_cache 0;
Context: http, server, location
@Since: This directive appeared in version 1.21.4.

Enables or disables caching of keys obtained from a file or from a subrequest, and sets caching time for them. Caching of keys obtained from variables is not supported. By default, caching of keys is disabled.

auth_jwt_key_file¶

Syntax: auth_jwt_key_file file;
Default: —
Context: http, server, location, limit_except
@Since: None

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

auth_jwt_key_request¶

Syntax: auth_jwt_key_request uri;
Default: —
Context: http, server, location, limit_except
@Since: This directive appeared in version 1.15.6.

Allows retrieving a JSON Web Key Set file from a subrequest for validating JWT signature and sets the URI where the subrequest will be sent to. Parameter value can contain variables. To avoid validation overhead, it is recommended to cache the key file:

auth_jwt_leeway¶

Syntax: auth_jwt_leeway time;
Default: auth_jwt_leeway 0s;
Context: http, server, location
@Since: This directive appeared in version 1.13.10.

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

auth_jwt_type¶

Syntax: auth_jwt_type signed | encrypted | nested;
Default: auth_jwt_type signed;
Context: http, server, location, limit_except
@Since: This directive appeared in version 1.19.7.

Specifies which type of JSON Web Token to expect: JWS (signed), JWE (encrypted), or signed and then encrypted Nested JWT (nested) (1.21.0).

auth_jwt_require¶

Syntax: auth_jwt_require $value ... [error=401 | 403] ;
Default: —
Context: http, server, location, limit_except
@Since: This directive appeared in version 1.21.2.

Specifies additional checks for JWT validation. The value can contain text, variables, and their combination, and must start with a variable (1.21.7). The authentication will succeed only if all the values are not empty and are not equal to “0”.

ngx_http_auth_request_module¶

auth_request¶

Syntax: auth_request uri | off;
Default: auth_request off;
Context: http, server, location
@Since: None

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

auth_request_set¶

Syntax: auth_request_set $variable value;
Default: —
Context: http, server, location
@Since: None

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_*.

ngx_http_autoindex_module¶

autoindex¶

Syntax: autoindex on | off;
Default: autoindex off;
Context: http, server, location
@Since: None

Enables or disables the directory listing output.

autoindex_exact_size¶

Syntax: autoindex_exact_size on | off;
Default: autoindex_exact_size on;
Context: http, server, location
@Since: None

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

autoindex_format¶

Syntax: autoindex_format html | xml | json | jsonp;
Default: autoindex_format html;
Context: http, server, location
@Since: This directive appeared in version 1.7.9.

Sets the format of a directory listing.

autoindex_localtime¶

Syntax: autoindex_localtime on | off;
Default: autoindex_localtime off;
Context: http, server, location
@Since: None

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

ngx_http_browser_module¶

ancient_browser¶

Syntax: ancient_browser string ...;
Default: —
Context: http, server, location
@Since: None

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]”.

ancient_browser_value¶

Syntax: ancient_browser_value string;
Default: ancient_browser_value 1;
Context: http, server, location
@Since: None

Sets a value for the $ancient_browser variables.

modern_browser¶

Syntax: modern_browser browser version; modern_browser unlisted;
Default: —
Context: http, server, location
@Since: None

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.

modern_browser_value¶

Syntax: modern_browser_value string;
Default: modern_browser_value 1;
Context: http, server, location
@Since: None

Sets a value for the $modern_browser variables.

ngx_http_charset_module¶

charset¶

Syntax: charset charset | off;
Default: charset off;
Context: http, server, location, if in location
@Since: None

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.

charset_map¶

Syntax: charset_map charset1 charset2 { ... }
Default: —
Context: http
@Since: None

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

charset_types¶

Syntax: charset_types mime-type ...;
Default: charset_types text/html text/xml text/plain text/vnd.wap.wml application/javascript application/rss+xml;
Context: http, server, location
@Since: This directive appeared in version 0.7.9.

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

override_charset¶

Syntax: override_charset on | off;
Default: override_charset off;
Context: http, server, location, if in location
@Since: None

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.

source_charset¶

Syntax: source_charset charset;
Default: —
Context: http, server, location, if in location
@Since: None

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

ngx_http_dav_module¶

create_full_put_path¶

Syntax: create_full_put_path on | off;
Default: create_full_put_path off;
Context: http, server, location
@Since: None

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

dav_access¶

Syntax: dav_access users:permissions ...;
Default: dav_access user:rw;
Context: http, server, location
@Since: None

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

dav_methods¶

Syntax: dav_methods off | method ...;
Default: dav_methods off;
Context: http, server, location
@Since: None

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.

min_delete_depth¶

Syntax: min_delete_depth number;
Default: min_delete_depth 0;
Context: http, server, location
@Since: None

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

ngx_http_empty_gif_module¶

empty_gif¶

Syntax: empty_gif;
Default: —
Context: location
@Since: None

Turns on module processing in a surrounding location.

ngx_http_f4f_module¶

f4f¶

Syntax: f4f;
Default: —
Context: location
@Since: None

Turns on module processing in the surrounding location.

f4f_buffer_size¶

Syntax: f4f_buffer_size size;
Default: f4f_buffer_size 512k;
Context: http, server, location
@Since: None

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

ngx_http_fastcgi_module¶

fastcgi_bind¶

Syntax: fastcgi_bind address [transparent] | off;
Default: —
Context: http, server, location
@Since: This directive appeared in version 0.8.22.

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.

fastcgi_buffer_size¶

Syntax: fastcgi_buffer_size size;
Default: fastcgi_buffer_size 4k|8k;
Context: http, server, location
@Since: None

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.

fastcgi_buffering¶

Syntax: fastcgi_buffering on | off;
Default: fastcgi_buffering on;
Context: http, server, location
@Since: This directive appeared in version 1.5.6.

Enables or disables buffering of responses from the FastCGI server.

fastcgi_buffers¶

Syntax: fastcgi_buffers number size;
Default: fastcgi_buffers 8 4k|8k;
Context: http, server, location
@Since: None

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.

fastcgi_busy_buffers_size¶

Syntax: fastcgi_busy_buffers_size size;
Default: fastcgi_busy_buffers_size 8k|16k;
Context: http, server, location
@Since: None

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.

fastcgi_cache¶

Syntax: fastcgi_cache zone | off;
Default: fastcgi_cache off;
Context: http, server, location
@Since: None

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.

fastcgi_cache_background_update¶

Syntax: fastcgi_cache_background_update on | off;
Default: fastcgi_cache_background_update off;
Context: http, server, location
@Since: This directive appeared in version 1.11.10.

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

fastcgi_cache_bypass¶

Syntax: fastcgi_cache_bypass string ...;
Default: —
Context: http, server, location
@Since: None

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:

fastcgi_cache_key¶

Syntax: fastcgi_cache_key string;
Default: —
Context: http, server, location
@Since: None

Defines a key for caching, for example

fastcgi_cache_lock¶

Syntax: fastcgi_cache_lock on | off;
Default: fastcgi_cache_lock off;
Context: http, server, location
@Since: This directive appeared in version 1.1.12.

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

fastcgi_cache_lock_age¶

Syntax: fastcgi_cache_lock_age time;
Default: fastcgi_cache_lock_age 5s;
Context: http, server, location
@Since: This directive appeared in version 1.7.8.

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.

fastcgi_cache_lock_timeout¶

Syntax: fastcgi_cache_lock_timeout time;
Default: fastcgi_cache_lock_timeout 5s;
Context: http, server, location
@Since: This directive appeared in version 1.1.12.

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.

fastcgi_cache_max_range_offset¶

Syntax: fastcgi_cache_max_range_offset number;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.11.6.

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

fastcgi_cache_methods¶

Syntax: fastcgi_cache_methods GET | HEAD | POST ...;
Default: fastcgi_cache_methods GET HEAD;
Context: http, server, location
@Since: This directive appeared in version 0.7.59.

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

fastcgi_cache_min_uses¶

Syntax: fastcgi_cache_min_uses number;
Default: fastcgi_cache_min_uses 1;
Context: http, server, location
@Since: None

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

fastcgi_cache_path¶

Syntax: fastcgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [min_free=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
@Since: None

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

fastcgi_cache_purge¶

Syntax: fastcgi_cache_purge string ...;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.5.7.

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

fastcgi_cache_revalidate¶

Syntax: fastcgi_cache_revalidate on | off;
Default: fastcgi_cache_revalidate off;
Context: http, server, location
@Since: This directive appeared in version 1.5.7.

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

fastcgi_cache_use_stale¶

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
@Since: None

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.

fastcgi_cache_valid¶

Syntax: fastcgi_cache_valid [code ...] time;
Default: —
Context: http, server, location
@Since: None

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

fastcgi_catch_stderr¶

Syntax: fastcgi_catch_stderr string;
Default: —
Context: http, server, location
@Since: None

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:

fastcgi_connect_timeout¶

Syntax: fastcgi_connect_timeout time;
Default: fastcgi_connect_timeout 60s;
Context: http, server, location
@Since: None

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

fastcgi_force_ranges¶

Syntax: fastcgi_force_ranges on | off;
Default: fastcgi_force_ranges off;
Context: http, server, location
@Since: This directive appeared in version 1.7.7.

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

fastcgi_hide_header¶

Syntax: fastcgi_hide_header field;
Default: —
Context: http, server, location
@Since: None

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.

fastcgi_ignore_client_abort¶

Syntax: fastcgi_ignore_client_abort on | off;
Default: fastcgi_ignore_client_abort off;
Context: http, server, location
@Since: None

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

fastcgi_ignore_headers¶

Syntax: fastcgi_ignore_headers field ...;
Default: —
Context: http, server, location
@Since: None

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

fastcgi_index¶

Syntax: fastcgi_index name;
Default: —
Context: http, server, location
@Since: None

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

fastcgi_intercept_errors¶

Syntax: fastcgi_intercept_errors on | off;
Default: fastcgi_intercept_errors off;
Context: http, server, location
@Since: None

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.

fastcgi_keep_conn¶

Syntax: fastcgi_keep_conn on | off;
Default: fastcgi_keep_conn off;
Context: http, server, location
@Since: This directive appeared in version 1.1.4.

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.

fastcgi_limit_rate¶

Syntax: fastcgi_limit_rate rate;
Default: fastcgi_limit_rate 0;
Context: http, server, location
@Since: This directive appeared in version 1.7.7.

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. Parameter value can contain variables (1.27.0).

fastcgi_max_temp_file_size¶

Syntax: fastcgi_max_temp_file_size size;
Default: fastcgi_max_temp_file_size 1024m;
Context: http, server, location
@Since: None

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.

fastcgi_next_upstream¶

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
@Since: None

Specifies in which cases a request should be passed to the next server:

fastcgi_next_upstream_timeout¶

Syntax: fastcgi_next_upstream_timeout time;
Default: fastcgi_next_upstream_timeout 0;
Context: http, server, location
@Since: This directive appeared in version 1.7.5.

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

fastcgi_next_upstream_tries¶

Syntax: fastcgi_next_upstream_tries number;
Default: fastcgi_next_upstream_tries 0;
Context: http, server, location
@Since: This directive appeared in version 1.7.5.

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

fastcgi_no_cache¶

Syntax: fastcgi_no_cache string ...;
Default: —
Context: http, server, location
@Since: None

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:

fastcgi_param¶

Syntax: fastcgi_param parameter value [if_not_empty];
Default: —
Context: http, server, location
@Since: None

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 configuration level if and only if there are no fastcgi_param directives defined on the current level.

fastcgi_pass¶

Syntax: fastcgi_pass address;
Default: —
Context: location, if in location
@Since: None

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

fastcgi_pass_header¶

Syntax: fastcgi_pass_header field;
Default: —
Context: http, server, location
@Since: None

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

fastcgi_pass_request_body¶

Syntax: fastcgi_pass_request_body on | off;
Default: fastcgi_pass_request_body on;
Context: http, server, location
@Since: None

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

fastcgi_pass_request_headers¶

Syntax: fastcgi_pass_request_headers on | off;
Default: fastcgi_pass_request_headers on;
Context: http, server, location
@Since: None

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

fastcgi_read_timeout¶

Syntax: fastcgi_read_timeout time;
Default: fastcgi_read_timeout 60s;
Context: http, server, location
@Since: None

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.

fastcgi_request_buffering¶

Syntax: fastcgi_request_buffering on | off;
Default: fastcgi_request_buffering on;
Context: http, server, location
@Since: This directive appeared in version 1.7.11.

Enables or disables buffering of a client request body.

fastcgi_send_lowat¶

Syntax: fastcgi_send_lowat size;
Default: fastcgi_send_lowat 0;
Context: http, server, location
@Since: None

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.

fastcgi_send_timeout¶

Syntax: fastcgi_send_timeout time;
Default: fastcgi_send_timeout 60s;
Context: http, server, location
@Since: None

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.

fastcgi_socket_keepalive¶

Syntax: fastcgi_socket_keepalive on | off;
Default: fastcgi_socket_keepalive off;
Context: http, server, location
@Since: This directive appeared in version 1.15.6.

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

fastcgi_split_path_info¶

Syntax: fastcgi_split_path_info regex;
Default: —
Context: location
@Since: None

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

fastcgi_store¶

Syntax: fastcgi_store on | off | string;
Default: fastcgi_store off;
Context: http, server, location
@Since: None

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:

fastcgi_store_access¶

Syntax: fastcgi_store_access users:permissions ...;
Default: fastcgi_store_access user:rw;
Context: http, server, location
@Since: None

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

fastcgi_temp_file_write_size¶

Syntax: fastcgi_temp_file_write_size size;
Default: fastcgi_temp_file_write_size 8k|16k;
Context: http, server, location
@Since: None

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.

fastcgi_temp_path¶

Syntax: fastcgi_temp_path path [level1 [level2 [level3]]];
Default: fastcgi_temp_path fastcgi_temp;
Context: http, server, location
@Since: None

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

ngx_http_flv_module¶

flv¶

Syntax: flv;
Default: —
Context: location
@Since: None

Turns on module processing in a surrounding location.

ngx_http_geo_module¶

geo¶

Syntax: geo [$address] $variable { ... }
Default: —
Context: http
@Since: None

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:

ngx_http_geoip_module¶

geoip_country¶

Syntax: geoip_country file;
Default: —
Context: http
@Since: None

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

geoip_city¶

Syntax: geoip_city file;
Default: —
Context: http
@Since: None

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_org¶

Syntax: geoip_org file;
Default: —
Context: http
@Since: This directive appeared in version 1.0.3.

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

geoip_proxy¶

Syntax: geoip_proxy address | CIDR;
Default: —
Context: http
@Since: This directive appeared in versions 1.3.0 and 1.2.1.

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.

geoip_proxy_recursive¶

Syntax: geoip_proxy_recursive on | off;
Default: geoip_proxy_recursive off;
Context: http
@Since: This directive appeared in versions 1.3.0 and 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.

ngx_http_grpc_module¶

grpc_bind¶

Syntax: grpc_bind address [transparent ] | off;
Default: —
Context: http, server, location
@Since: None

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.

grpc_buffer_size¶

Syntax: grpc_buffer_size size;
Default: grpc_buffer_size 4k|8k;
Context: http, server, location
@Since: None

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.

grpc_connect_timeout¶

Syntax: grpc_connect_timeout time;
Default: grpc_connect_timeout 60s;
Context: http, server, location
@Since: None

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

grpc_hide_header¶

Syntax: grpc_hide_header field;
Default: —
Context: http, server, location
@Since: None

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.

grpc_ignore_headers¶

Syntax: grpc_ignore_headers field ...;
Default: —
Context: http, server, location
@Since: None

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

grpc_intercept_errors¶

Syntax: grpc_intercept_errors on | off;
Default: grpc_intercept_errors off;
Context: http, server, location
@Since: None

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.

grpc_next_upstream¶

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
@Since: None

Specifies in which cases a request should be passed to the next server:

grpc_next_upstream_timeout¶

Syntax: grpc_next_upstream_timeout time;
Default: grpc_next_upstream_timeout 0;
Context: http, server, location
@Since: None

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

grpc_next_upstream_tries¶

Syntax: grpc_next_upstream_tries number;
Default: grpc_next_upstream_tries 0;
Context: http, server, location
@Since: None

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

grpc_pass¶

Syntax: grpc_pass address;
Default: —
Context: location, if in location
@Since: None

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

grpc_pass_header¶

Syntax: grpc_pass_header field;
Default: —
Context: http, server, location
@Since: None

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

grpc_read_timeout¶

Syntax: grpc_read_timeout time;
Default: grpc_read_timeout 60s;
Context: http, server, location
@Since: None

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.

grpc_send_timeout¶

Syntax: grpc_send_timeout time;
Default: grpc_send_timeout 60s;
Context: http, server, location
@Since: None

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.

grpc_set_header¶

Syntax: grpc_set_header field value;
Default: grpc_set_header Content-Length $content_length;
Context: http, server, location
@Since: None

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 configuration level if and only if there are no grpc_set_header directives defined on the current level.

grpc_socket_keepalive¶

Syntax: grpc_socket_keepalive on | off;
Default: grpc_socket_keepalive off;
Context: http, server, location
@Since: This directive appeared in version 1.15.6.

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

grpc_ssl_certificate¶

Syntax: grpc_ssl_certificate file;
Default: —
Context: http, server, location
@Since: None

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

grpc_ssl_certificate_cache¶

Syntax: grpc_ssl_certificate_cache off; grpc_ssl_certificate_cache max=N [inactive=time] [valid=time];
Default: grpc_ssl_certificate_cache off;
Context: http, server, location
@Since: This directive appeared in version 1.27.4.

Defines a cache that stores SSL certificates and secret keys specified with variables.

grpc_ssl_certificate_key¶

Syntax: grpc_ssl_certificate_key file;
Default: —
Context: http, server, location
@Since: None

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

grpc_ssl_ciphers¶

Syntax: grpc_ssl_ciphers ciphers;
Default: grpc_ssl_ciphers DEFAULT;
Context: http, server, location
@Since: None

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

grpc_ssl_conf_command¶

Syntax: grpc_ssl_conf_command name value;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.19.4.

Sets arbitrary OpenSSL configuration commands when establishing a connection with the gRPC SSL server.

grpc_ssl_crl¶

Syntax: grpc_ssl_crl file;
Default: —
Context: http, server, location
@Since: None

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

grpc_ssl_key_log¶

Syntax: grpc_ssl_key_log path;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.27.2.

Enables logging of gRPC SSL server connection SSL keys and specifies the path to the key log file. Keys are logged in the SSLKEYLOGFILE format compatible with Wireshark.

grpc_ssl_name¶

Syntax: grpc_ssl_name name;
Default: grpc_ssl_name host from grpc_pass;
Context: http, server, location
@Since: None

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.

grpc_ssl_password_file¶

Syntax: grpc_ssl_password_file file;
Default: —
Context: http, server, location
@Since: None

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.

grpc_ssl_protocols¶

Syntax: grpc_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: grpc_ssl_protocols TLSv1.2 TLSv1.3;
Context: http, server, location
@Since: None

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

grpc_ssl_server_name¶

Syntax: grpc_ssl_server_name on | off;
Default: grpc_ssl_server_name off;
Context: http, server, location
@Since: None

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.

grpc_ssl_session_reuse¶

Syntax: grpc_ssl_session_reuse on | off;
Default: grpc_ssl_session_reuse on;
Context: http, server, location
@Since: None

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

grpc_ssl_trusted_certificate¶

Syntax: grpc_ssl_trusted_certificate file;
Default: —
Context: http, server, location
@Since: None

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

grpc_ssl_verify¶

Syntax: grpc_ssl_verify on | off;
Default: grpc_ssl_verify off;
Context: http, server, location
@Since: None

Enables or disables verification of the gRPC SSL server certificate.

grpc_ssl_verify_depth¶

Syntax: grpc_ssl_verify_depth number;
Default: grpc_ssl_verify_depth 1;
Context: http, server, location
@Since: None

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

ngx_http_gunzip_module¶

gunzip¶

Syntax: gunzip on | off;
Default: gunzip off;
Context: http, server, location
@Since: None

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.

gunzip_buffers¶

Syntax: gunzip_buffers number size;
Default: gunzip_buffers 32 4k|16 8k;
Context: http, server, location
@Since: None

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.

ngx_http_gzip_module¶

gzip¶

Syntax: gzip on | off;
Default: gzip off;
Context: http, server, location, if in location
@Since: None

Enables or disables gzipping of responses.

gzip_buffers¶

Syntax: gzip_buffers number size;
Default: gzip_buffers 32 4k|16 8k;
Context: http, server, location
@Since: None

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.

gzip_comp_level¶

Syntax: gzip_comp_level level;
Default: gzip_comp_level 1;
Context: http, server, location
@Since: None

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

gzip_disable¶

Syntax: gzip_disable regex ...;
Default: —
Context: http, server, location
@Since: This directive appeared in version 0.6.23.

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

gzip_http_version¶

Syntax: gzip_http_version 1.0 | 1.1;
Default: gzip_http_version 1.1;
Context: http, server, location
@Since: None

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

gzip_min_length¶

Syntax: gzip_min_length length;
Default: gzip_min_length 20;
Context: http, server, location
@Since: None

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

gzip_proxied¶

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
@Since: None

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:

gzip_types¶

Syntax: gzip_types mime-type ...;
Default: gzip_types text/html;
Context: http, server, location
@Since: None

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.

gzip_vary¶

Syntax: gzip_vary on | off;
Default: gzip_vary off;
Context: http, server, location
@Since: None

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

ngx_http_gzip_static_module¶

gzip_static¶

Syntax: gzip_static on | off | always;
Default: gzip_static off;
Context: http, server, location
@Since: None

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.

ngx_http_headers_module¶

add_header¶

Syntax: add_header name value [always];
Default: —
Context: http, server, location, if in location
@Since: None

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). Parameter value can contain variables.

add_trailer¶

Syntax: add_trailer name value [always];
Default: —
Context: http, server, location, if in location
@Since: This directive appeared in version 1.13.2.

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. Parameter value can contain variables.

expires¶

Syntax: expires [modified] time; expires epoch | max | off;
Default: expires off;
Context: http, server, location, if in location
@Since: None

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.

ngx_http_hls_module¶

hls¶

Syntax: hls;
Default: —
Context: location
@Since: None

Turns on HLS streaming in the surrounding location.

hls_buffers¶

Syntax: hls_buffers number size;
Default: hls_buffers 8 2m;
Context: http, server, location
@Since: None

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

hls_forward_args¶

Syntax: hls_forward_args on | off;
Default: hls_forward_args off;
Context: http, server, location
@Since: This directive appeared in version 1.5.12.

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.

hls_fragment¶

Syntax: hls_fragment time;
Default: hls_fragment 5s;
Context: http, server, location
@Since: None

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

hls_mp4_buffer_size¶

Syntax: hls_mp4_buffer_size size;
Default: hls_mp4_buffer_size 512k;
Context: http, server, location
@Since: None

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

hls_mp4_max_buffer_size¶

Syntax: hls_mp4_max_buffer_size size;
Default: hls_mp4_max_buffer_size 10m;
Context: http, server, location
@Since: None

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:

ngx_http_image_filter_module¶

image_filter¶

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
@Since: None

Sets the type of transformation to perform on images:

image_filter_buffer¶

Syntax: image_filter_buffer size;
Default: image_filter_buffer 1M;
Context: http, server, location
@Since: None

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

image_filter_interlace¶

Syntax: image_filter_interlace on | off;
Default: image_filter_interlace off;
Context: http, server, location
@Since: This directive appeared in version 1.3.15.

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

image_filter_jpeg_quality¶

Syntax: image_filter_jpeg_quality quality;
Default: image_filter_jpeg_quality 75;
Context: http, server, location
@Since: None

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.

image_filter_sharpen¶

Syntax: image_filter_sharpen percent;
Default: image_filter_sharpen 0;
Context: http, server, location
@Since: None

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

image_filter_transparency¶

Syntax: image_filter_transparency on|off;
Default: image_filter_transparency on;
Context: http, server, location
@Since: None

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.

image_filter_webp_quality¶

Syntax: image_filter_webp_quality quality;
Default: image_filter_webp_quality 80;
Context: http, server, location
@Since: This directive appeared in version 1.11.6.

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.

ngx_http_index_module¶

index¶

Syntax: index file ...;
Default: index index.html;
Context: http, server, location
@Since: None

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:

ngx_http_internal_redirect_module¶

internal_redirect¶

Syntax: internal_redirect uri;
Default: —
Context: server, location
@Since: None

Sets the URI for internal redirection of the request. It is also possible to use a named location instead of the URI. The uri value can contain variables. If the uri value is empty, then the redirect will not be made.

ngx_http_js_module¶

js_body_filter¶

Syntax: js_body_filter function | module.function [buffer_type=string | buffer];
Default: —
Context: location, if in location, limit_except
@Since: This directive appeared in version 0.5.2.

Sets an njs function as a response body filter. The filter function is called for each data chunk of a response body with the following arguments:

js_content¶

Syntax: js_content function | module.function;
Default: —
Context: location, if in location, limit_except
@Since: None

Sets an njs function as a location content handler. Since 0.4.0, a module function can be referenced.

js_context_reuse¶

Syntax: js_context_reuse number;
Default: js_context_reuse 128;
Context: http, server, location
@Since: This directive appeared in version 0.8.6.

Sets a maximum number of JS context to be reused for QuickJS engine. Each context is used for a single request. The finished context is put into a pool of reusable contexts. If the pool is full, the context is destroyed.

js_engine¶

Syntax: js_engine njs | qjs;
Default: js_engine njs;
Context: http, server, location
@Since: This directive appeared in version 0.8.6.

Sets a JavaScript engine to be used for njs scripts. The njs parameter sets the njs engine, also used by default. The qjs parameter sets the QuickJS engine.

js_fetch_buffer_size¶

Syntax: js_fetch_buffer_size size;
Default: js_fetch_buffer_size 16k;
Context: http, server, location
@Since: This directive appeared in version 0.7.4.

Sets the size of the buffer used for reading and writing with Fetch API.

js_fetch_ciphers¶

Syntax: js_fetch_ciphers ciphers;
Default: js_fetch_ciphers HIGH:!aNULL:!MD5;
Context: http, server, location
@Since: This directive appeared in version 0.7.0.

Specifies the enabled ciphers for HTTPS requests with Fetch API. The ciphers are specified in the format understood by the OpenSSL library.

js_fetch_max_response_buffer_size¶

Syntax: js_fetch_max_response_buffer_size size;
Default: js_fetch_max_response_buffer_size 1m;
Context: http, server, location
@Since: This directive appeared in version 0.7.4.

Sets the maximum size of the response received with Fetch API.

js_fetch_protocols¶

Syntax: js_fetch_protocols [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2;
Context: http, server, location
@Since: This directive appeared in version 0.7.0.

Enables the specified protocols for HTTPS requests with Fetch API.

js_fetch_timeout¶

Syntax: js_fetch_timeout time;
Default: js_fetch_timeout 60s;
Context: http, server, location
@Since: This directive appeared in version 0.7.4.

Defines a timeout for reading and writing for Fetch API. The timeout is set only between two successive read/write operations, not for the whole response. If no data is transmitted within this time, the connection is closed.

js_fetch_trusted_certificate¶

Syntax: js_fetch_trusted_certificate file;
Default: —
Context: http, server, location
@Since: This directive appeared in version 0.7.0.

Specifies a file with trusted CA certificates in the PEM format used to verify the HTTPS certificate with Fetch API.

js_fetch_verify¶

Syntax: js_fetch_verify on | off;
Default: js_fetch_verify on;
Context: http, server, location
@Since: This directive appeared in version 0.7.4.

Enables or disables verification of the HTTPS server certificate with Fetch API.

js_fetch_verify_depth¶

Syntax: js_fetch_verify_depth number;
Default: js_fetch_verify_depth 100;
Context: http, server, location
@Since: This directive appeared in version 0.7.0.

Sets the verification depth in the HTTPS server certificates chain with Fetch API.

js_header_filter¶

Syntax: js_header_filter function | module.function;
Default: —
Context: location, if in location, limit_except
@Since: This directive appeared in version 0.5.1.

Sets an njs function as a response header filter. The directive allows changing arbitrary header fields of a response header.

js_import¶

Syntax: js_import module.js | export_name from module.js;
Default: —
Context: http, server, location
@Since: This directive appeared in version 0.4.0.

Imports a module that implements location and variable handlers in njs. The export_name is used as a namespace to access module functions. If the export_name is not specified, the module name will be used as a namespace.

js_include¶

Syntax: js_include file;
Default: —
Context: http
@Since: None

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

js_path¶

Syntax: js_path path;
Default: —
Context: http, server, location
@Since: This directive appeared in version 0.3.0.

Sets an additional path for njs modules.

js_periodic¶

Syntax: js_periodic function | module.function [interval=time] [jitter=number] [worker_affinity=mask];
Default: —
Context: location
@Since: This directive appeared in version 0.8.1.

Specifies a content handler to run at regular interval. The handler receives a session object as its first argument, it also has access to global objects such as ngx.

js_preload_object¶

Syntax: js_preload_object name.json | name from file.json;
Default: —
Context: http, server, location
@Since: This directive appeared in version 0.7.8.

Preloads an immutable object at configure time. The name is used as a name of the global variable though which the object is available in njs code. If the name is not specified, the file name will be used instead.

js_set¶

Syntax: js_set $variable function | module.function [nocache];
Default: —
Context: http, server, location
@Since: None

Sets an njs function for the specified variable. Since 0.4.0, a module function can be referenced.

js_shared_dict_zone¶

Syntax: js_shared_dict_zone zone=name:size [timeout=time] [type=string|number] [evict] [state=file];
Default: —
Context: http
@Since: This directive appeared in version 0.8.0.

Sets the name and size of the shared memory zone that keeps the key-value dictionary shared between worker processes.

js_var¶

Syntax: js_var $variable [value];
Default: —
Context: http, server, location
@Since: This directive appeared in version 0.5.3.

Declares a writable variable. The value can contain text, variables, and their combination. The variable is not overwritten after a redirect unlike variables created with the set directive.

ngx_http_keyval_module¶

keyval¶

Syntax: keyval key $variable zone=name;
Default: —
Context: http
@Since: None

Creates a new $variable whose value is looked up by the key in the key-value database. Matching rules are defined by the type parameter of the keyval_zone directive. The database is stored in a shared memory zone specified by the zone parameter.

keyval_zone¶

Syntax: keyval_zone zone=name:size [state=file] [timeout=time] [type=string|ip|prefix] [sync];
Default: —
Context: http
@Since: None

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

ngx_http_limit_conn_module¶

limit_conn¶

Syntax: limit_conn zone number;
Default: —
Context: http, server, location
@Since: None

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

limit_conn_dry_run¶

Syntax: limit_conn_dry_run on | off;
Default: limit_conn_dry_run off;
Context: http, server, location
@Since: This directive appeared in version 1.17.6.

Enables the dry run mode. In this mode, the number of connections is not limited, however, in the shared memory zone, the number of excessive connections is accounted as usual.

limit_conn_log_level¶

Syntax: limit_conn_log_level info | notice | warn | error;
Default: limit_conn_log_level error;
Context: http, server, location
@Since: This directive appeared in version 0.8.18.

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

limit_conn_status¶

Syntax: limit_conn_status code;
Default: limit_conn_status 503;
Context: http, server, location
@Since: This directive appeared in version 1.3.15.

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

limit_conn_zone¶

Syntax: limit_conn_zone key zone=name:size;
Default: —
Context: http
@Since: None

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.

limit_zone¶

Syntax: limit_zone name $variable size;
Default: —
Context: http
@Since: None

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:

ngx_http_limit_req_module¶

limit_req¶

Syntax: limit_req zone=name [burst=number] [nodelay | delay=number];
Default: —
Context: http, server, location
@Since: None

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

limit_req_dry_run¶

Syntax: limit_req_dry_run on | off;
Default: limit_req_dry_run off;
Context: http, server, location
@Since: This directive appeared in version 1.17.1.

Enables the dry run mode. In this mode, requests processing rate is not limited, however, in the shared memory zone, the number of excessive requests is accounted as usual.

limit_req_log_level¶

Syntax: limit_req_log_level info | notice | warn | error;
Default: limit_req_log_level error;
Context: http, server, location
@Since: This directive appeared in version 0.8.18.

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.

limit_req_status¶

Syntax: limit_req_status code;
Default: limit_req_status 503;
Context: http, server, location
@Since: This directive appeared in version 1.3.15.

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

limit_req_zone¶

Syntax: limit_req_zone key zone=name:size rate=rate [sync];
Default: —
Context: http
@Since: None

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.

ngx_http_log_module¶

access_log¶

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
@Since: None

Sets the path, format, and configuration for a buffered log write. Several logs can be specified on the same configuration 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.

log_format¶

Syntax: log_format name [escape=default|json|none] string ...;
Default: log_format combined "...";
Context: http
@Since: None

Specifies log format.

open_log_file_cache¶

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
@Since: None

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

ngx_http_map_module¶

map¶

Syntax: map string $variable { ... }
Default: —
Context: http
@Since: None

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

map_hash_bucket_size¶

Syntax: map_hash_bucket_size size;
Default: map_hash_bucket_size 32|64|128;
Context: http
@Since: None

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.

map_hash_max_size¶

Syntax: map_hash_max_size size;
Default: map_hash_max_size 2048;
Context: http
@Since: None

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

ngx_http_memcached_module¶

memcached_bind¶

Syntax: memcached_bind address [transparent ] | off;
Default: —
Context: http, server, location
@Since: This directive appeared in version 0.8.22.

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.

memcached_buffer_size¶

Syntax: memcached_buffer_size size;
Default: memcached_buffer_size 4k|8k;
Context: http, server, location
@Since: None

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.

memcached_connect_timeout¶

Syntax: memcached_connect_timeout time;
Default: memcached_connect_timeout 60s;
Context: http, server, location
@Since: None

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

memcached_gzip_flag¶

Syntax: memcached_gzip_flag flag;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.3.6.

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.

memcached_next_upstream¶

Syntax: memcached_next_upstream error | timeout | invalid_response | not_found | off ...;
Default: memcached_next_upstream error timeout;
Context: http, server, location
@Since: None

Specifies in which cases a request should be passed to the next server:

memcached_next_upstream_timeout¶

Syntax: memcached_next_upstream_timeout time;
Default: memcached_next_upstream_timeout 0;
Context: http, server, location
@Since: This directive appeared in version 1.7.5.

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

memcached_next_upstream_tries¶

Syntax: memcached_next_upstream_tries number;
Default: memcached_next_upstream_tries 0;
Context: http, server, location
@Since: This directive appeared in version 1.7.5.

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

memcached_pass¶

Syntax: memcached_pass address;
Default: —
Context: location, if in location
@Since: None

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

memcached_read_timeout¶

Syntax: memcached_read_timeout time;
Default: memcached_read_timeout 60s;
Context: http, server, location
@Since: None

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.

memcached_send_timeout¶

Syntax: memcached_send_timeout time;
Default: memcached_send_timeout 60s;
Context: http, server, location
@Since: None

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.

memcached_socket_keepalive¶

Syntax: memcached_socket_keepalive on | off;
Default: memcached_socket_keepalive off;
Context: http, server, location
@Since: This directive appeared in version 1.15.6.

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

ngx_http_mirror_module¶

mirror¶

Syntax: mirror uri | off;
Default: mirror off;
Context: http, server, location
@Since: None

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

mirror_request_body¶

Syntax: mirror_request_body on | off;
Default: mirror_request_body on;
Context: http, server, location
@Since: None

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.

ngx_http_mp4_module¶

mp4¶

Syntax: mp4;
Default: —
Context: location
@Since: None

Turns on module processing in a surrounding location.

mp4_buffer_size¶

Syntax: mp4_buffer_size size;
Default: mp4_buffer_size 512K;
Context: http, server, location
@Since: None

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

mp4_max_buffer_size¶

Syntax: mp4_max_buffer_size size;
Default: mp4_max_buffer_size 10M;
Context: http, server, location
@Since: None

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:

mp4_limit_rate¶

Syntax: mp4_limit_rate on | off | factor;
Default: mp4_limit_rate off;
Context: http, server, location
@Since: None

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.

mp4_limit_rate_after¶

Syntax: mp4_limit_rate_after time;
Default: mp4_limit_rate_after 60s;
Context: http, server, location
@Since: None

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.

mp4_start_key_frame¶

Syntax: mp4_start_key_frame on | off;
Default: mp4_start_key_frame off;
Context: http, server, location
@Since: This directive appeared in version 1.21.4.

Forces output video to always start with a key video frame. If the start argument does not point to a key frame, initial frames are hidden using an mp4 edit list. Edit lists are supported by major players and browsers such as Chrome, Safari, QuickTime and ffmpeg, partially supported by Firefox.

ngx_http_oidc_module¶

oidc_provider¶

Syntax: oidc_provider name { ... }
Default: —
Context: http
@Since: None

Defines an OpenID Provider for use with the auth_oidc directive.

auth_oidc¶

Syntax: auth_oidc name | off;
Default: auth_oidc off;
Context: http, server, location
@Since: None

Enables end user authentication with the specified OpenID Provider.

issuer¶

Syntax: issuer URL;
Default: —
Context: oidc_provider
@Since: None

Sets the Issuer Identifier URL of the OpenID Provider; required directive. The URL must exactly match the value of “issuer” in the OpenID Provider metadata and requires the “https” scheme.

client_id¶

Syntax: client_id string;
Default: —
Context: oidc_provider
@Since: None

Specifies the client ID of the Relying Party; required directive.

client_secret¶

Syntax: client_secret string;
Default: —
Context: oidc_provider
@Since: None

Specifies a secret value used to authenticate the Relying Party with the OpenID Provider.

config_url¶

Syntax: config_url URL;
Default: config_url <issuer>/.well-known/openid-configuration;
Context: oidc_provider
@Since: None

Sets a custom URL to retrieve the OpenID Provider metadata.

cookie_name¶

Syntax: cookie_name name;
Default: cookie_name NGX_OIDC_SESSION;
Context: oidc_provider
@Since: None

Sets the name of a session cookie.

extra_auth_args¶

Syntax: extra_auth_args string;
Default: —
Context: oidc_provider
@Since: None

Sets additional query arguments for the authentication request URL.

redirect_uri¶

Syntax: redirect_uri uri;
Default: redirect_uri /oidc_callback;
Context: oidc_provider
@Since: None

Defines the Redirection URI path for post-authentication redirects expected by the module from the OpenID Provider. The uri must match the configuration on the Provider's side.

scope¶

Syntax: scope scope ...;
Default: scope openid;
Context: oidc_provider
@Since: None

Sets requested scopes. The openid scope is always required by OIDC.

session_store¶

Syntax: session_store name;
Default: —
Context: oidc_provider
@Since: None

Specifies a custom key-value database that stores session data. By default, an 8-megabyte key-value database named oidc_default_store_ is created automatically.

session_timeout¶

Syntax: session_timeout time;
Default: session_timeout 8h;
Context: oidc_provider
@Since: None

Sets a timeout after which the session is deleted, unless it was refreshed.

[oidc_provider] ssl_crl¶

Syntax: ssl_crl file;
Default: —
Context: oidc_provider
@Since: None

Specifies a file with revoked certificates (CRL) in the PEM format used to verify the certificates of the OpenID Provider endpoints.

[oidc_provider] ssl_trusted_certificate¶

Syntax: ssl_trusted_certificate file;
Default: ssl_trusted_certificate system CA bundle;
Context: oidc_provider
@Since: None

Specifies a file with trusted CA certificates in the PEM format used to verify the certificates of the OpenID Provider endpoints.

ngx_http_perl_module¶

perl¶

Syntax: perl module::function|'sub { ... }';
Default: —
Context: location, limit_except
@Since: None

Sets a Perl handler for the given location.

perl_modules¶

Syntax: perl_modules path;
Default: —
Context: http
@Since: None

Sets an additional path for Perl modules.

perl_require¶

Syntax: perl_require module;
Default: —
Context: http
@Since: None

Defines the name of a module that will be loaded during each reconfiguration. Several perl_require directives can be present.

perl_set¶

Syntax: perl_set $variable module::function|'sub { ... }';
Default: —
Context: http
@Since: None

Installs a Perl handler for the specified variable.

ngx_http_proxy_module¶

proxy_bind¶

Syntax: proxy_bind address [transparent] | off;
Default: —
Context: http, server, location
@Since: This directive appeared in version 0.8.22.

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

proxy_buffer_size¶

Syntax: proxy_buffer_size size;
Default: proxy_buffer_size 4k|8k;
Context: http, server, location
@Since: None

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.

proxy_buffering¶

Syntax: proxy_buffering on | off;
Default: proxy_buffering on;
Context: http, server, location
@Since: None

Enables or disables buffering of responses from the proxied server.

proxy_buffers¶

Syntax: proxy_buffers number size;
Default: proxy_buffers 8 4k|8k;
Context: http, server, location
@Since: None

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.

proxy_busy_buffers_size¶

Syntax: proxy_busy_buffers_size size;
Default: proxy_busy_buffers_size 8k|16k;
Context: http, server, location
@Since: None

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.

proxy_cache¶

Syntax: proxy_cache zone | off;
Default: proxy_cache off;
Context: http, server, location
@Since: None

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.

proxy_cache_background_update¶

Syntax: proxy_cache_background_update on | off;
Default: proxy_cache_background_update off;
Context: http, server, location
@Since: This directive appeared in version 1.11.10.

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

proxy_cache_bypass¶

Syntax: proxy_cache_bypass string ...;
Default: —
Context: http, server, location
@Since: None

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:

proxy_cache_convert_head¶

Syntax: proxy_cache_convert_head on | off;
Default: proxy_cache_convert_head on;
Context: http, server, location
@Since: This directive appeared in version 1.9.7.

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

proxy_cache_key¶

Syntax: proxy_cache_key string;
Default: proxy_cache_key $scheme$proxy_host$request_uri;
Context: http, server, location
@Since: None

Defines a key for caching, for example

proxy_cache_lock¶

Syntax: proxy_cache_lock on | off;
Default: proxy_cache_lock off;
Context: http, server, location
@Since: This directive appeared in version 1.1.12.

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

proxy_cache_lock_age¶

Syntax: proxy_cache_lock_age time;
Default: proxy_cache_lock_age 5s;
Context: http, server, location
@Since: This directive appeared in version 1.7.8.

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

proxy_cache_lock_timeout¶

Syntax: proxy_cache_lock_timeout time;
Default: proxy_cache_lock_timeout 5s;
Context: http, server, location
@Since: This directive appeared in version 1.1.12.

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

proxy_cache_max_range_offset¶

Syntax: proxy_cache_max_range_offset number;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.11.6.

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

proxy_cache_methods¶

Syntax: proxy_cache_methods GET | HEAD | POST ...;
Default: proxy_cache_methods GET HEAD;
Context: http, server, location
@Since: This directive appeared in version 0.7.59.

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

proxy_cache_min_uses¶

Syntax: proxy_cache_min_uses number;
Default: proxy_cache_min_uses 1;
Context: http, server, location
@Since: None

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

proxy_cache_path¶

Syntax: proxy_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [min_free=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
@Since: None

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

proxy_cache_purge¶

Syntax: proxy_cache_purge string ...;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.5.7.

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

proxy_cache_revalidate¶

Syntax: proxy_cache_revalidate on | off;
Default: proxy_cache_revalidate off;
Context: http, server, location
@Since: This directive appeared in version 1.5.7.

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

proxy_cache_use_stale¶

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
@Since: None

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.

proxy_cache_valid¶

Syntax: proxy_cache_valid [code ...] time;
Default: —
Context: http, server, location
@Since: None

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

proxy_connect_timeout¶

Syntax: proxy_connect_timeout time;
Default: proxy_connect_timeout 60s;
Context: http, server, location
@Since: None

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

proxy_cookie_domain¶

Syntax: proxy_cookie_domain off; proxy_cookie_domain domain replacement;
Default: proxy_cookie_domain off;
Context: http, server, location
@Since: This directive appeared in version 1.1.15.

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

proxy_cookie_flags¶

Syntax: proxy_cookie_flags off | cookie [flag ...];
Default: proxy_cookie_flags off;
Context: http, server, location
@Since: This directive appeared in version 1.19.3.

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

proxy_cookie_path¶

Syntax: proxy_cookie_path off; proxy_cookie_path path replacement;
Default: proxy_cookie_path off;
Context: http, server, location
@Since: This directive appeared in version 1.1.15.

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

proxy_force_ranges¶

Syntax: proxy_force_ranges on | off;
Default: proxy_force_ranges off;
Context: http, server, location
@Since: This directive appeared in version 1.7.7.

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

proxy_headers_hash_bucket_size¶

Syntax: proxy_headers_hash_bucket_size size;
Default: proxy_headers_hash_bucket_size 64;
Context: http, server, location
@Since: None

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.

proxy_headers_hash_max_size¶

Syntax: proxy_headers_hash_max_size size;
Default: proxy_headers_hash_max_size 512;
Context: http, server, location
@Since: None

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.

proxy_hide_header¶

Syntax: proxy_hide_header field;
Default: —
Context: http, server, location
@Since: None

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.

proxy_http_version¶

Syntax: proxy_http_version 1.0 | 1.1;
Default: proxy_http_version 1.0;
Context: http, server, location
@Since: This directive appeared in version 1.1.4.

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

proxy_ignore_client_abort¶

Syntax: proxy_ignore_client_abort on | off;
Default: proxy_ignore_client_abort off;
Context: http, server, location
@Since: None

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

proxy_ignore_headers¶

Syntax: proxy_ignore_headers field ...;
Default: —
Context: http, server, location
@Since: None

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

proxy_intercept_errors¶

Syntax: proxy_intercept_errors on | off;
Default: proxy_intercept_errors off;
Context: http, server, location
@Since: None

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.

proxy_limit_rate¶

Syntax: proxy_limit_rate rate;
Default: proxy_limit_rate 0;
Context: http, server, location
@Since: This directive appeared in version 1.7.7.

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

proxy_max_temp_file_size¶

Syntax: proxy_max_temp_file_size size;
Default: proxy_max_temp_file_size 1024m;
Context: http, server, location
@Since: None

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.

proxy_method¶

Syntax: proxy_method method;
Default: —
Context: http, server, location
@Since: None

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

proxy_next_upstream¶

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
@Since: None

Specifies in which cases a request should be passed to the next server:

proxy_next_upstream_timeout¶

Syntax: proxy_next_upstream_timeout time;
Default: proxy_next_upstream_timeout 0;
Context: http, server, location
@Since: This directive appeared in version 1.7.5.

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

proxy_next_upstream_tries¶

Syntax: proxy_next_upstream_tries number;
Default: proxy_next_upstream_tries 0;
Context: http, server, location
@Since: This directive appeared in version 1.7.5.

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

proxy_no_cache¶

Syntax: proxy_no_cache string ...;
Default: —
Context: http, server, location
@Since: None

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:

proxy_pass¶

Syntax: proxy_pass URL;
Default: —
Context: location, if in location, limit_except
@Since: None

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:

proxy_pass_header¶

Syntax: proxy_pass_header field;
Default: —
Context: http, server, location
@Since: None

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

proxy_pass_request_body¶

Syntax: proxy_pass_request_body on | off;
Default: proxy_pass_request_body on;
Context: http, server, location
@Since: None

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

proxy_pass_request_headers¶

Syntax: proxy_pass_request_headers on | off;
Default: proxy_pass_request_headers on;
Context: http, server, location
@Since: None

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

proxy_pass_trailers¶

Syntax: proxy_pass_trailers on | off;
Default: proxy_pass_trailers off;
Context: http, server, location
@Since: This directive appeared in version 1.27.2.

Permits passing trailer fields from a proxied server to a client.

proxy_read_timeout¶

Syntax: proxy_read_timeout time;
Default: proxy_read_timeout 60s;
Context: http, server, location
@Since: None

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.

proxy_redirect¶

Syntax: proxy_redirect default; proxy_redirect off; proxy_redirect redirect replacement;
Default: proxy_redirect default;
Context: http, server, location
@Since: None

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

proxy_request_buffering¶

Syntax: proxy_request_buffering on | off;
Default: proxy_request_buffering on;
Context: http, server, location
@Since: This directive appeared in version 1.7.11.

Enables or disables buffering of a client request body.

proxy_send_lowat¶

Syntax: proxy_send_lowat size;
Default: proxy_send_lowat 0;
Context: http, server, location
@Since: None

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.

proxy_send_timeout¶

Syntax: proxy_send_timeout time;
Default: proxy_send_timeout 60s;
Context: http, server, location
@Since: None

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.

proxy_set_body¶

Syntax: proxy_set_body value;
Default: —
Context: http, server, location
@Since: None

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

proxy_set_header¶

Syntax: proxy_set_header field value;
Default: proxy_set_header Host $proxy_host; proxy_set_header Connection close;
Context: http, server, location
@Since: None

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

proxy_socket_keepalive¶

Syntax: proxy_socket_keepalive on | off;
Default: proxy_socket_keepalive off;
Context: http, server, location
@Since: This directive appeared in version 1.15.6.

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

proxy_ssl_certificate¶

Syntax: proxy_ssl_certificate file;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.7.8.

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

proxy_ssl_certificate_cache¶

Syntax: proxy_ssl_certificate_cache off; proxy_ssl_certificate_cache max=N [inactive=time] [valid=time];
Default: proxy_ssl_certificate_cache off;
Context: http, server, location
@Since: This directive appeared in version 1.27.4.

Defines a cache that stores SSL certificates and secret keys specified with variables.

proxy_ssl_certificate_key¶

Syntax: proxy_ssl_certificate_key file;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.7.8.

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

proxy_ssl_ciphers¶

Syntax: proxy_ssl_ciphers ciphers;
Default: proxy_ssl_ciphers DEFAULT;
Context: http, server, location
@Since: This directive appeared in version 1.5.6.

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

proxy_ssl_conf_command¶

Syntax: proxy_ssl_conf_command name value;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.19.4.

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

proxy_ssl_crl¶

Syntax: proxy_ssl_crl file;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.7.0.

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

proxy_ssl_key_log¶

Syntax: proxy_ssl_key_log path;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.27.2.

Enables logging of proxied HTTPS server connection SSL keys and specifies the path to the key log file. Keys are logged in the SSLKEYLOGFILE format compatible with Wireshark.

proxy_ssl_name¶

Syntax: proxy_ssl_name name;
Default: proxy_ssl_name $proxy_host;
Context: http, server, location
@Since: This directive appeared in version 1.7.0.

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

proxy_ssl_password_file¶

Syntax: proxy_ssl_password_file file;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.7.8.

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

proxy_ssl_protocols¶

Syntax: proxy_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: proxy_ssl_protocols TLSv1.2 TLSv1.3;
Context: http, server, location
@Since: This directive appeared in version 1.5.6.

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

proxy_ssl_server_name¶

Syntax: proxy_ssl_server_name on | off;
Default: proxy_ssl_server_name off;
Context: http, server, location
@Since: This directive appeared in version 1.7.0.

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

proxy_ssl_session_reuse¶

Syntax: proxy_ssl_session_reuse on | off;
Default: proxy_ssl_session_reuse on;
Context: http, server, location
@Since: None

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

proxy_ssl_trusted_certificate¶

Syntax: proxy_ssl_trusted_certificate file;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.7.0.

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

proxy_ssl_verify¶

Syntax: proxy_ssl_verify on | off;
Default: proxy_ssl_verify off;
Context: http, server, location
@Since: This directive appeared in version 1.7.0.

Enables or disables verification of the proxied HTTPS server certificate.

proxy_ssl_verify_depth¶

Syntax: proxy_ssl_verify_depth number;
Default: proxy_ssl_verify_depth 1;
Context: http, server, location
@Since: This directive appeared in version 1.7.0.

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

proxy_store¶

Syntax: proxy_store on | off | string;
Default: proxy_store off;
Context: http, server, location
@Since: None

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:

proxy_store_access¶

Syntax: proxy_store_access users:permissions ...;
Default: proxy_store_access user:rw;
Context: http, server, location
@Since: None

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

proxy_temp_file_write_size¶

Syntax: proxy_temp_file_write_size size;
Default: proxy_temp_file_write_size 8k|16k;
Context: http, server, location
@Since: None

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.

proxy_temp_path¶

Syntax: proxy_temp_path path [level1 [level2 [level3]]];
Default: proxy_temp_path proxy_temp;
Context: http, server, location
@Since: None

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

ngx_http_proxy_protocol_vendor_module¶

ngx_http_random_index_module¶

random_index¶

Syntax: random_index on | off;
Default: random_index off;
Context: location
@Since: None

Enables or disables module processing in a surrounding location.

ngx_http_realip_module¶

set_real_ip_from¶

Syntax: set_real_ip_from address | CIDR | unix:;
Default: —
Context: http, server, location
@Since: None

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

real_ip_header¶

Syntax: real_ip_header field | X-Real-IP | X-Forwarded-For | proxy_protocol;
Default: real_ip_header X-Real-IP;
Context: http, server, location
@Since: None

Defines the request header field whose value will be used to replace the client address.

real_ip_recursive¶

Syntax: real_ip_recursive on | off;
Default: real_ip_recursive off;
Context: http, server, location
@Since: This directive appeared in versions 1.3.0 and 1.2.1.

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.

ngx_http_referer_module¶

referer_hash_bucket_size¶

Syntax: referer_hash_bucket_size size;
Default: referer_hash_bucket_size 64;
Context: server, location
@Since: This directive appeared in version 1.0.5.

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

referer_hash_max_size¶

Syntax: referer_hash_max_size size;
Default: referer_hash_max_size 2048;
Context: server, location
@Since: This directive appeared in version 1.0.5.

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

valid_referers¶

Syntax: valid_referers none | blocked | server_names | string ...;
Default: —
Context: server, location
@Since: None

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.

ngx_http_rewrite_module¶

break¶

Syntax: break;
Default: —
Context: server, location, if
@Since: None

Stops processing the current set of ngx_http_rewrite_module directives.

if¶

Syntax: if (condition) { ... }
Default: —
Context: server, location
@Since: None

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.

return¶

Syntax: return code [text]; return code URL; return URL;
Default: —
Context: server, location, if
@Since: None

Stops processing and returns the specified code to a client. The non-standard code 444 closes a connection without sending a response header.

rewrite¶

Syntax: rewrite regex replacement [flag];
Default: —
Context: server, location, if
@Since: None

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.

rewrite_log¶

Syntax: rewrite_log on | off;
Default: rewrite_log off;
Context: http, server, location, if
@Since: None

Enables or disables logging of ngx_http_rewrite_module module directives processing results into the error_log at the notice level.

set¶

Syntax: set $variable value;
Default: —
Context: server, location, if
@Since: None

Sets a value for the specified variable. The value can contain text, variables, and their combination.

uninitialized_variable_warn¶

Syntax: uninitialized_variable_warn on | off;
Default: uninitialized_variable_warn on;
Context: http, server, location, if
@Since: None

Controls whether warnings about uninitialized variables are logged.

ngx_http_scgi_module¶

scgi_bind¶

Syntax: scgi_bind address [transparent] | off;
Default: —
Context: http, server, location
@Since: None

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.

scgi_buffer_size¶

Syntax: scgi_buffer_size size;
Default: scgi_buffer_size 4k|8k;
Context: http, server, location
@Since: None

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.

scgi_buffering¶

Syntax: scgi_buffering on | off;
Default: scgi_buffering on;
Context: http, server, location
@Since: None

Enables or disables buffering of responses from the SCGI server.

scgi_buffers¶

Syntax: scgi_buffers number size;
Default: scgi_buffers 8 4k|8k;
Context: http, server, location
@Since: None

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.

scgi_busy_buffers_size¶

Syntax: scgi_busy_buffers_size size;
Default: scgi_busy_buffers_size 8k|16k;
Context: http, server, location
@Since: None

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.

scgi_cache¶

Syntax: scgi_cache zone | off;
Default: scgi_cache off;
Context: http, server, location
@Since: None

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.

scgi_cache_background_update¶

Syntax: scgi_cache_background_update on | off;
Default: scgi_cache_background_update off;
Context: http, server, location
@Since: This directive appeared in version 1.11.10.

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

scgi_cache_bypass¶

Syntax: scgi_cache_bypass string ...;
Default: —
Context: http, server, location
@Since: None

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:

scgi_cache_key¶

Syntax: scgi_cache_key string;
Default: —
Context: http, server, location
@Since: None

Defines a key for caching, for example

scgi_cache_lock¶

Syntax: scgi_cache_lock on | off;
Default: scgi_cache_lock off;
Context: http, server, location
@Since: This directive appeared in version 1.1.12.

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

scgi_cache_lock_age¶

Syntax: scgi_cache_lock_age time;
Default: scgi_cache_lock_age 5s;
Context: http, server, location
@Since: This directive appeared in version 1.7.8.

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.

scgi_cache_lock_timeout¶

Syntax: scgi_cache_lock_timeout time;
Default: scgi_cache_lock_timeout 5s;
Context: http, server, location
@Since: This directive appeared in version 1.1.12.

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.

scgi_cache_max_range_offset¶

Syntax: scgi_cache_max_range_offset number;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.11.6.

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

scgi_cache_methods¶

Syntax: scgi_cache_methods GET | HEAD | POST ...;
Default: scgi_cache_methods GET HEAD;
Context: http, server, location
@Since: None

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.

scgi_cache_min_uses¶

Syntax: scgi_cache_min_uses number;
Default: scgi_cache_min_uses 1;
Context: http, server, location
@Since: None

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

scgi_cache_path¶

Syntax: scgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [min_free=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
@Since: None

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

scgi_cache_purge¶

Syntax: scgi_cache_purge string ...;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.5.7.

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

scgi_cache_revalidate¶

Syntax: scgi_cache_revalidate on | off;
Default: scgi_cache_revalidate off;
Context: http, server, location
@Since: This directive appeared in version 1.5.7.

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

scgi_cache_use_stale¶

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
@Since: None

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.

scgi_cache_valid¶

Syntax: scgi_cache_valid [code ...] time;
Default: —
Context: http, server, location
@Since: None

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

scgi_connect_timeout¶

Syntax: scgi_connect_timeout time;
Default: scgi_connect_timeout 60s;
Context: http, server, location
@Since: None

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

scgi_force_ranges¶

Syntax: scgi_force_ranges on | off;
Default: scgi_force_ranges off;
Context: http, server, location
@Since: This directive appeared in version 1.7.7.

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

scgi_hide_header¶

Syntax: scgi_hide_header field;
Default: —
Context: http, server, location
@Since: None

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.

scgi_ignore_client_abort¶

Syntax: scgi_ignore_client_abort on | off;
Default: scgi_ignore_client_abort off;
Context: http, server, location
@Since: None

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

scgi_ignore_headers¶

Syntax: scgi_ignore_headers field ...;
Default: —
Context: http, server, location
@Since: None

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

scgi_intercept_errors¶

Syntax: scgi_intercept_errors on | off;
Default: scgi_intercept_errors off;
Context: http, server, location
@Since: None

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.

scgi_limit_rate¶

Syntax: scgi_limit_rate rate;
Default: scgi_limit_rate 0;
Context: http, server, location
@Since: This directive appeared in version 1.7.7.

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. Parameter value can contain variables (1.27.0).

scgi_max_temp_file_size¶

Syntax: scgi_max_temp_file_size size;
Default: scgi_max_temp_file_size 1024m;
Context: http, server, location
@Since: None

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.

scgi_next_upstream¶

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
@Since: None

Specifies in which cases a request should be passed to the next server:

scgi_next_upstream_timeout¶

Syntax: scgi_next_upstream_timeout time;
Default: scgi_next_upstream_timeout 0;
Context: http, server, location
@Since: This directive appeared in version 1.7.5.

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

scgi_next_upstream_tries¶

Syntax: scgi_next_upstream_tries number;
Default: scgi_next_upstream_tries 0;
Context: http, server, location
@Since: This directive appeared in version 1.7.5.

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

scgi_no_cache¶

Syntax: scgi_no_cache string ...;
Default: —
Context: http, server, location
@Since: None

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:

scgi_param¶

Syntax: scgi_param parameter value [if_not_empty];
Default: —
Context: http, server, location
@Since: None

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 configuration level if and only if there are no scgi_param directives defined on the current level.

scgi_pass¶

Syntax: scgi_pass address;
Default: —
Context: location, if in location
@Since: None

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

scgi_pass_header¶

Syntax: scgi_pass_header field;
Default: —
Context: http, server, location
@Since: None

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

scgi_pass_request_body¶

Syntax: scgi_pass_request_body on | off;
Default: scgi_pass_request_body on;
Context: http, server, location
@Since: None

Indicates whether the original request body is passed to the SCGI server. See also the scgi_pass_request_headers directive.

scgi_pass_request_headers¶

Syntax: scgi_pass_request_headers on | off;
Default: scgi_pass_request_headers on;
Context: http, server, location
@Since: None

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

scgi_read_timeout¶

Syntax: scgi_read_timeout time;
Default: scgi_read_timeout 60s;
Context: http, server, location
@Since: None

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.

scgi_request_buffering¶

Syntax: scgi_request_buffering on | off;
Default: scgi_request_buffering on;
Context: http, server, location
@Since: This directive appeared in version 1.7.11.

Enables or disables buffering of a client request body.

scgi_send_timeout¶

Syntax: scgi_send_timeout time;
Default: scgi_send_timeout 60s;
Context: http, server, location
@Since: None

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.

scgi_socket_keepalive¶

Syntax: scgi_socket_keepalive on | off;
Default: scgi_socket_keepalive off;
Context: http, server, location
@Since: This directive appeared in version 1.15.6.

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

scgi_store¶

Syntax: scgi_store on | off | string;
Default: scgi_store off;
Context: http, server, location
@Since: None

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:

scgi_store_access¶

Syntax: scgi_store_access users:permissions ...;
Default: scgi_store_access user:rw;
Context: http, server, location
@Since: None

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

scgi_temp_file_write_size¶

Syntax: scgi_temp_file_write_size size;
Default: scgi_temp_file_write_size 8k|16k;
Context: http, server, location
@Since: None

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.

scgi_temp_path¶

Syntax: scgi_temp_path path [level1 [level2 [level3]]];
Default: scgi_temp_path scgi_temp;
Context: http, server, location
@Since: None

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

ngx_http_secure_link_module¶

secure_link¶

Syntax: secure_link expression;
Default: —
Context: http, server, location
@Since: None

Defines a string with variables from which the checksum value and lifetime of a link will be extracted.

secure_link_md5¶

Syntax: secure_link_md5 expression;
Default: —
Context: http, server, location
@Since: None

Defines an expression for which the MD5 hash value will be computed and compared with the value passed in a request.

secure_link_secret¶

Syntax: secure_link_secret word;
Default: —
Context: location
@Since: None

Defines a secret word used to check authenticity of requested links.

ngx_http_session_log_module¶

session_log¶

Syntax: session_log name | off;
Default: session_log off;
Context: http, server, location
@Since: None

Enables the use of the specified session log. The special value off cancels the effect of the session_log directives inherited from the previous configuration level.

session_log_format¶

Syntax: session_log_format name string ...;
Default: session_log_format combined "...";
Context: http
@Since: None

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.

session_log_zone¶

Syntax: session_log_zone path zone=name:size [format=format] [timeout=time] [id=id] [md5=md5] ;
Default: —
Context: http
@Since: None

Sets the path to a log file and configures the shared memory zone that is used to store currently active sessions.

ngx_http_slice_module¶

slice¶

Syntax: slice size;
Default: slice 0;
Context: http, server, location
@Since: None

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.

ngx_http_split_clients_module¶

split_clients¶

Syntax: split_clients string $variable { ... }
Default: —
Context: http
@Since: None

Creates a variable for A/B testing, for example:

ngx_http_ssi_module¶

ssi¶

Syntax: ssi on | off;
Default: ssi off;
Context: http, server, location, if in location
@Since: None

Enables or disables processing of SSI commands in responses.

ssi_last_modified¶

Syntax: ssi_last_modified on | off;
Default: ssi_last_modified off;
Context: http, server, location
@Since: This directive appeared in version 1.5.1.

Allows preserving the “Last-Modified” header field from the original response during SSI processing to facilitate response caching.

ssi_min_file_chunk¶

Syntax: ssi_min_file_chunk size;
Default: ssi_min_file_chunk 1k;
Context: http, server, location
@Since: None

Sets the minimum size for parts of a response stored on disk, starting from which it makes sense to send them using sendfile.

ssi_silent_errors¶

Syntax: ssi_silent_errors on | off;
Default: ssi_silent_errors off;
Context: http, server, location
@Since: None

If enabled, suppresses the output of the “[an error occurred while processing the directive]” string if an error occurred during SSI processing.

ssi_types¶

Syntax: ssi_types mime-type ...;
Default: ssi_types text/html;
Context: http, server, location
@Since: None

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

ssi_value_length¶

Syntax: ssi_value_length length;
Default: ssi_value_length 256;
Context: http, server, location
@Since: None

Sets the maximum length of parameter values in SSI commands.

ngx_http_ssl_module¶

ssl¶

Syntax: ssl on | off;
Default: ssl off;
Context: http, server
@Since: None

This directive was made obsolete in version 1.15.0 and was removed in version 1.25.1. The ssl parameter of the listen directive should be used instead.

ssl_buffer_size¶

Syntax: ssl_buffer_size size;
Default: ssl_buffer_size 16k;
Context: http, server
@Since: This directive appeared in version 1.5.9.

Sets the size of the buffer used for sending data.

ssl_certificate¶

Syntax: ssl_certificate file;
Default: —
Context: http, server
@Since: None

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.

ssl_certificate_cache¶

Syntax: ssl_certificate_cache off; ssl_certificate_cache max=N [inactive=time] [valid=time];
Default: ssl_certificate_cache off;
Context: http, server
@Since: This directive appeared in version 1.27.4.

Defines a cache that stores SSL certificates and secret keys specified with variables.

ssl_certificate_key¶

Syntax: ssl_certificate_key file;
Default: —
Context: http, server
@Since: None

Specifies a file with the secret key in the PEM format for the given virtual server.

ssl_ciphers¶

Syntax: ssl_ciphers ciphers;
Default: ssl_ciphers HIGH:!aNULL:!MD5;
Context: http, server
@Since: None

Specifies the enabled ciphers. The ciphers are specified in the format understood by the OpenSSL library, for example:

ssl_client_certificate¶

Syntax: ssl_client_certificate file;
Default: —
Context: http, server
@Since: None

Specifies a file with trusted CA certificates in the PEM format used to verify client certificates and OCSP responses if ssl_stapling is enabled.

ssl_conf_command¶

Syntax: ssl_conf_command name value;
Default: —
Context: http, server
@Since: This directive appeared in version 1.19.4.

Sets arbitrary OpenSSL configuration commands.

ssl_crl¶

Syntax: ssl_crl file;
Default: —
Context: http, server
@Since: This directive appeared in version 0.8.7.

Specifies a file with revoked certificates (CRL) in the PEM format used to verify client certificates.

ssl_dhparam¶

Syntax: ssl_dhparam file;
Default: —
Context: http, server
@Since: This directive appeared in version 0.7.2.

Specifies a file with DH parameters for DHE ciphers.

ssl_early_data¶

Syntax: ssl_early_data on | off;
Default: ssl_early_data off;
Context: http, server
@Since: This directive appeared in version 1.15.3.

Enables or disables TLS 1.3 early data.

ssl_ecdh_curve¶

Syntax: ssl_ecdh_curve curve;
Default: ssl_ecdh_curve auto;
Context: http, server
@Since: This directive appeared in versions 1.1.0 and 1.0.6.

Specifies a curve for ECDHE ciphers.

ssl_key_log¶

Syntax: ssl_key_log path;
Default: —
Context: http, server
@Since: This directive appeared in version 1.27.2.

Enables logging of client connection SSL keys and specifies the path to the key log file. Keys are logged in the SSLKEYLOGFILE format compatible with Wireshark.

ssl_ocsp¶

Syntax: ssl_ocsp on | off | leaf;
Default: ssl_ocsp off;
Context: http, server
@Since: This directive appeared in version 1.19.0.

Enables OCSP validation of the client certificate chain. The leaf parameter enables validation of the client certificate only.

ssl_ocsp_cache¶

Syntax: ssl_ocsp_cache off | [shared:name:size];
Default: ssl_ocsp_cache off;
Context: http, server
@Since: This directive appeared in version 1.19.0.

Sets name and size of the cache that stores client certificates status for OCSP validation. The cache is shared between all worker processes. A cache with the same name can be used in several virtual servers.

ssl_ocsp_responder¶

Syntax: ssl_ocsp_responder url;
Default: —
Context: http, server
@Since: This directive appeared in version 1.19.0.

Overrides the URL of the OCSP responder specified in the “Authority Information Access” certificate extension for validation of client certificates.

ssl_password_file¶

Syntax: ssl_password_file file;
Default: —
Context: http, server
@Since: This directive appeared in version 1.7.3.

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.

ssl_prefer_server_ciphers¶

Syntax: ssl_prefer_server_ciphers on | off;
Default: ssl_prefer_server_ciphers off;
Context: http, server
@Since: None

Specifies that server ciphers should be preferred over client ciphers when the SSLv3 and TLS protocols are used.

ssl_protocols¶

Syntax: ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: ssl_protocols TLSv1.2 TLSv1.3;
Context: http, server
@Since: None

Enables the specified protocols.

ssl_reject_handshake¶

Syntax: ssl_reject_handshake on | off;
Default: ssl_reject_handshake off;
Context: http, server
@Since: This directive appeared in version 1.19.4.

If enabled, SSL handshakes in the server block will be rejected.

ssl_session_cache¶

Syntax: ssl_session_cache off | none | [builtin[:size]] [shared:name:size];
Default: ssl_session_cache none;
Context: http, server
@Since: None

Sets the types and sizes of caches that store session parameters. A cache can be of any of the following types:

ssl_session_ticket_key¶

Syntax: ssl_session_ticket_key file;
Default: —
Context: http, server
@Since: This directive appeared in version 1.5.7.

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.

ssl_session_tickets¶

Syntax: ssl_session_tickets on | off;
Default: ssl_session_tickets on;
Context: http, server
@Since: This directive appeared in version 1.5.9.

Enables or disables session resumption through TLS session tickets.

ssl_session_timeout¶

Syntax: ssl_session_timeout time;
Default: ssl_session_timeout 5m;
Context: http, server
@Since: None

Specifies a time during which a client may reuse the session parameters.

ssl_stapling¶

Syntax: ssl_stapling on | off;
Default: ssl_stapling off;
Context: http, server
@Since: This directive appeared in version 1.3.7.

Enables or disables stapling of OCSP responses by the server. Example:

ssl_stapling_file¶

Syntax: ssl_stapling_file file;
Default: —
Context: http, server
@Since: This directive appeared in version 1.3.7.

When set, the stapled OCSP response will be taken from the specified file instead of querying the OCSP responder specified in the server certificate.

ssl_stapling_responder¶

Syntax: ssl_stapling_responder url;
Default: —
Context: http, server
@Since: This directive appeared in version 1.3.7.

Overrides the URL of the OCSP responder specified in the “Authority Information Access” certificate extension.

ssl_stapling_verify¶

Syntax: ssl_stapling_verify on | off;
Default: ssl_stapling_verify off;
Context: http, server
@Since: This directive appeared in version 1.3.7.

Enables or disables verification of OCSP responses by the server.

ssl_trusted_certificate¶

Syntax: ssl_trusted_certificate file;
Default: —
Context: http, server
@Since: This directive appeared in version 1.3.7.

Specifies a file with trusted CA certificates in the PEM format used to verify client certificates and OCSP responses if ssl_stapling is enabled.

ssl_verify_client¶

Syntax: ssl_verify_client on | off | optional | optional_no_ca;
Default: ssl_verify_client off;
Context: http, server
@Since: None

Enables verification of client certificates. The verification result is stored in the $ssl_client_verify variable.

ssl_verify_depth¶

Syntax: ssl_verify_depth number;
Default: ssl_verify_depth 1;
Context: http, server
@Since: None

Sets the verification depth in the client certificates chain.

ngx_http_status_module¶

status¶

Syntax: status;
Default: —
Context: location
@Since: None

The status information will be accessible from the surrounding location. Access to this location should be limited.

status_format¶

Syntax: status_format json; status_format jsonp [callback];
Default: status_format json;
Context: http, server, location
@Since: None

By default, status information is output in the JSON format.

[status] status_zone¶

Syntax: status_zone zone;
Default: —
Context: server
@Since: None

Enables collection of virtual http or stream (1.7.11) server status information in the specified zone. Several servers may share the same zone.

ngx_http_stub_status_module¶

stub_status¶

Syntax: stub_status;
Default: —
Context: server, location
@Since: None

The basic status information will be accessible from the surrounding location.

ngx_http_sub_module¶

sub_filter¶

Syntax: sub_filter string replacement;
Default: —
Context: http, server, location
@Since: None

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 the same configuration level (1.9.4). These directives are inherited from the previous configuration level if and only if there are no sub_filter directives defined on the current level.

sub_filter_last_modified¶

Syntax: sub_filter_last_modified on | off;
Default: sub_filter_last_modified off;
Context: http, server, location
@Since: This directive appeared in version 1.5.1.

Allows preserving the “Last-Modified” header field from the original response during replacement to facilitate response caching.

sub_filter_once¶

Syntax: sub_filter_once on | off;
Default: sub_filter_once on;
Context: http, server, location
@Since: None

Indicates whether to look for each string to replace once or repeatedly.

sub_filter_types¶

Syntax: sub_filter_types mime-type ...;
Default: sub_filter_types text/html;
Context: http, server, location
@Since: None

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

ngx_http_upstream_module¶

upstream¶

Syntax: upstream name { ... }
Default: —
Context: http
@Since: None

Defines a group of servers. Servers can listen on different ports. In addition, servers listening on TCP and UNIX-domain sockets can be mixed.

[upstream] server¶

Syntax: server address [parameters];
Default: —
Context: upstream
@Since: None

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.

zone¶

Syntax: zone name [size];
Default: —
Context: upstream
@Since: This directive appeared in version 1.9.0.

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.

state¶

Syntax: state file;
Default: —
Context: upstream
@Since: This directive appeared in version 1.9.7.

Specifies a file that keeps the state of the dynamically configurable group.

hash key¶

Syntax: hash key [consistent];
Default: —
Context: upstream
@Since: This directive appeared in version 1.7.2.

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.

ip_hash¶

Syntax: ip_hash;
Default: —
Context: upstream
@Since: None

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.

keepalive¶

Syntax: keepalive connections;
Default: —
Context: upstream
@Since: This directive appeared in version 1.1.4.

Activates the cache for connections to upstream servers.

[upstream] keepalive_requests¶

Syntax: keepalive_requests number;
Default: keepalive_requests 1000;
Context: upstream
@Since: This directive appeared in version 1.15.3.

Sets the maximum number of requests that can be served through one keepalive connection. After the maximum number of requests is made, the connection is closed.

[upstream] keepalive_time¶

Syntax: keepalive_time time;
Default: keepalive_time 1h;
Context: upstream
@Since: This directive appeared in version 1.19.10.

Limits the maximum time during which requests can be processed through one keepalive connection. After this time is reached, the connection is closed following the subsequent request processing.

[upstream] keepalive_timeout¶

Syntax: keepalive_timeout timeout;
Default: keepalive_timeout 60s;
Context: upstream
@Since: This directive appeared in version 1.15.3.

Sets a timeout during which an idle keepalive connection to an upstream server will stay open.

ntlm¶

Syntax: ntlm;
Default: —
Context: upstream
@Since: This directive appeared in version 1.9.2.

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.

least_conn¶

Syntax: least_conn;
Default: —
Context: upstream
@Since: This directive appeared in versions 1.3.1 and 1.2.2.

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.

least_time¶

Syntax: least_time header | last_byte [inflight];
Default: —
Context: upstream
@Since: This directive appeared in version 1.7.10.

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.

queue¶

Syntax: queue number [timeout=time];
Default: —
Context: upstream
@Since: This directive appeared in version 1.5.12.

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.

random¶

Syntax: random [two [method]];
Default: —
Context: upstream
@Since: This directive appeared in version 1.15.1.

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.

[upstream] resolver¶

Syntax: resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone];
Default: —
Context: upstream
@Since: This directive appeared in version 1.27.3.

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

[upstream] resolver_timeout¶

Syntax: resolver_timeout time;
Default: resolver_timeout 30s;
Context: upstream
@Since: This directive appeared in version 1.27.3.

Sets a timeout for name resolution, for example:

sticky¶

Syntax: sticky cookie name [expires=time] [domain=domain] [httponly] [samesite=strict|lax|none|$variable] [secure] [path=path]; sticky route \(variable ...; sticky learn create=$variable lookup=\)variable zone=name:size [timeout=time] [header] [sync];
Default: —
Context: upstream
@Since: This directive appeared in version 1.5.7.

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:

sticky_cookie_insert¶

Syntax: sticky_cookie_insert name [expires=time] [domain=domain] [path=path];
Default: —
Context: upstream
@Since: None

This directive is obsolete since version 1.5.7. An equivalent sticky directive with a new syntax should be used instead:

ngx_http_upstream_conf_module¶

upstream_conf¶

Syntax: upstream_conf;
Default: —
Context: location
@Since: None

Turns on the HTTP interface of upstream configuration in the surrounding location. Access to this location should be limited.

ngx_http_upstream_hc_module¶

health_check¶

Syntax: health_check [parameters];
Default: —
Context: location
@Since: None

Enables periodic health checks of the servers in a group referenced in the surrounding location.

match¶

Syntax: match name { ... }
Default: —
Context: http
@Since: None

Defines the named test set used to verify responses to health check requests.

ngx_http_userid_module¶

userid¶

Syntax: userid on | v1 | log | off;
Default: userid off;
Context: http, server, location
@Since: None

Enables or disables setting cookies and logging the received cookies:

userid_domain¶

Syntax: userid_domain name | none;
Default: userid_domain none;
Context: http, server, location
@Since: None

Defines a domain for which the cookie is set. The none parameter disables setting of a domain for the cookie.

userid_expires¶

Syntax: userid_expires time | max | off;
Default: userid_expires off;
Context: http, server, location
@Since: None

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.

userid_flags¶

Syntax: userid_flags off | flag ...;
Default: userid_flags off;
Context: http, server, location
@Since: This directive appeared in version 1.19.3.

If the parameter is not off, defines one or more additional flags for the cookie: secure, httponly, samesite=strict, samesite=lax, samesite=none.

userid_mark¶

Syntax: userid_mark letter | digit | = | off;
Default: userid_mark off;
Context: http, server, location
@Since: None

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.

userid_name¶

Syntax: userid_name name;
Default: userid_name uid;
Context: http, server, location
@Since: None

Sets the cookie name.

userid_p3p¶

Syntax: userid_p3p string | none;
Default: userid_p3p none;
Context: http, server, location
@Since: None

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.

userid_path¶

Syntax: userid_path path;
Default: userid_path /;
Context: http, server, location
@Since: None

Defines a path for which the cookie is set.

userid_service¶

Syntax: userid_service number;
Default: userid_service IP address of the server;
Context: http, server, location
@Since: None

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.

ngx_http_uwsgi_module¶

uwsgi_bind¶

Syntax: uwsgi_bind address [transparent] | off;
Default: —
Context: http, server, location
@Since: None

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.

uwsgi_buffer_size¶

Syntax: uwsgi_buffer_size size;
Default: uwsgi_buffer_size 4k|8k;
Context: http, server, location
@Since: None

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.

uwsgi_buffering¶

Syntax: uwsgi_buffering on | off;
Default: uwsgi_buffering on;
Context: http, server, location
@Since: None

Enables or disables buffering of responses from the uwsgi server.

uwsgi_buffers¶

Syntax: uwsgi_buffers number size;
Default: uwsgi_buffers 8 4k|8k;
Context: http, server, location
@Since: None

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.

uwsgi_busy_buffers_size¶

Syntax: uwsgi_busy_buffers_size size;
Default: uwsgi_busy_buffers_size 8k|16k;
Context: http, server, location
@Since: None

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.

uwsgi_cache¶

Syntax: uwsgi_cache zone | off;
Default: uwsgi_cache off;
Context: http, server, location
@Since: None

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.

uwsgi_cache_background_update¶

Syntax: uwsgi_cache_background_update on | off;
Default: uwsgi_cache_background_update off;
Context: http, server, location
@Since: This directive appeared in version 1.11.10.

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

uwsgi_cache_bypass¶

Syntax: uwsgi_cache_bypass string ...;
Default: —
Context: http, server, location
@Since: None

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:

uwsgi_cache_key¶

Syntax: uwsgi_cache_key string;
Default: —
Context: http, server, location
@Since: None

Defines a key for caching, for example

uwsgi_cache_lock¶

Syntax: uwsgi_cache_lock on | off;
Default: uwsgi_cache_lock off;
Context: http, server, location
@Since: This directive appeared in version 1.1.12.

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

uwsgi_cache_lock_age¶

Syntax: uwsgi_cache_lock_age time;
Default: uwsgi_cache_lock_age 5s;
Context: http, server, location
@Since: This directive appeared in version 1.7.8.

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.

uwsgi_cache_lock_timeout¶

Syntax: uwsgi_cache_lock_timeout time;
Default: uwsgi_cache_lock_timeout 5s;
Context: http, server, location
@Since: This directive appeared in version 1.1.12.

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.

uwsgi_cache_max_range_offset¶

Syntax: uwsgi_cache_max_range_offset number;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.11.6.

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

uwsgi_cache_methods¶

Syntax: uwsgi_cache_methods GET | HEAD | POST ...;
Default: uwsgi_cache_methods GET HEAD;
Context: http, server, location
@Since: None

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.

uwsgi_cache_min_uses¶

Syntax: uwsgi_cache_min_uses number;
Default: uwsgi_cache_min_uses 1;
Context: http, server, location
@Since: None

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

uwsgi_cache_path¶

Syntax: uwsgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [min_free=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
@Since: None

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

uwsgi_cache_purge¶

Syntax: uwsgi_cache_purge string ...;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.5.7.

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

uwsgi_cache_revalidate¶

Syntax: uwsgi_cache_revalidate on | off;
Default: uwsgi_cache_revalidate off;
Context: http, server, location
@Since: This directive appeared in version 1.5.7.

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

uwsgi_cache_use_stale¶

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
@Since: None

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.

uwsgi_cache_valid¶

Syntax: uwsgi_cache_valid [code ...] time;
Default: —
Context: http, server, location
@Since: None

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

uwsgi_connect_timeout¶

Syntax: uwsgi_connect_timeout time;
Default: uwsgi_connect_timeout 60s;
Context: http, server, location
@Since: None

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

uwsgi_force_ranges¶

Syntax: uwsgi_force_ranges on | off;
Default: uwsgi_force_ranges off;
Context: http, server, location
@Since: This directive appeared in version 1.7.7.

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

uwsgi_hide_header¶

Syntax: uwsgi_hide_header field;
Default: —
Context: http, server, location
@Since: None

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.

uwsgi_ignore_client_abort¶

Syntax: uwsgi_ignore_client_abort on | off;
Default: uwsgi_ignore_client_abort off;
Context: http, server, location
@Since: None

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

uwsgi_ignore_headers¶

Syntax: uwsgi_ignore_headers field ...;
Default: —
Context: http, server, location
@Since: None

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

uwsgi_intercept_errors¶

Syntax: uwsgi_intercept_errors on | off;
Default: uwsgi_intercept_errors off;
Context: http, server, location
@Since: None

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.

uwsgi_limit_rate¶

Syntax: uwsgi_limit_rate rate;
Default: uwsgi_limit_rate 0;
Context: http, server, location
@Since: This directive appeared in version 1.7.7.

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. Parameter value can contain variables (1.27.0).

uwsgi_max_temp_file_size¶

Syntax: uwsgi_max_temp_file_size size;
Default: uwsgi_max_temp_file_size 1024m;
Context: http, server, location
@Since: None

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.

uwsgi_modifier1¶

Syntax: uwsgi_modifier1 number;
Default: uwsgi_modifier1 0;
Context: http, server, location
@Since: None

Sets the value of the modifier1 field in the uwsgi packet header.

uwsgi_modifier2¶

Syntax: uwsgi_modifier2 number;
Default: uwsgi_modifier2 0;
Context: http, server, location
@Since: None

Sets the value of the modifier2 field in the uwsgi packet header.

uwsgi_next_upstream¶

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
@Since: None

Specifies in which cases a request should be passed to the next server:

uwsgi_next_upstream_timeout¶

Syntax: uwsgi_next_upstream_timeout time;
Default: uwsgi_next_upstream_timeout 0;
Context: http, server, location
@Since: This directive appeared in version 1.7.5.

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

uwsgi_next_upstream_tries¶

Syntax: uwsgi_next_upstream_tries number;
Default: uwsgi_next_upstream_tries 0;
Context: http, server, location
@Since: This directive appeared in version 1.7.5.

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

uwsgi_no_cache¶

Syntax: uwsgi_no_cache string ...;
Default: —
Context: http, server, location
@Since: None

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:

uwsgi_param parameter¶

Syntax: uwsgi_param parameter value [if_not_empty];
Default: —
Context: http, server, location
@Since: None

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 configuration level if and only if there are no uwsgi_param directives defined on the current level.

uwsgi_pass¶

Syntax: uwsgi_pass [protocol://]address;
Default: —
Context: location, if in location
@Since: None

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:

uwsgi_pass_header¶

Syntax: uwsgi_pass_header field;
Default: —
Context: http, server, location
@Since: None

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

uwsgi_pass_request_body¶

Syntax: uwsgi_pass_request_body on | off;
Default: uwsgi_pass_request_body on;
Context: http, server, location
@Since: None

Indicates whether the original request body is passed to the uwsgi server. See also the uwsgi_pass_request_headers directive.

uwsgi_pass_request_headers¶

Syntax: uwsgi_pass_request_headers on | off;
Default: uwsgi_pass_request_headers on;
Context: http, server, location
@Since: None

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

uwsgi_read_timeout¶

Syntax: uwsgi_read_timeout time;
Default: uwsgi_read_timeout 60s;
Context: http, server, location
@Since: None

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.

uwsgi_request_buffering¶

Syntax: uwsgi_request_buffering on | off;
Default: uwsgi_request_buffering on;
Context: http, server, location
@Since: This directive appeared in version 1.7.11.

Enables or disables buffering of a client request body.

uwsgi_send_timeout¶

Syntax: uwsgi_send_timeout time;
Default: uwsgi_send_timeout 60s;
Context: http, server, location
@Since: None

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.

uwsgi_socket_keepalive¶

Syntax: uwsgi_socket_keepalive on | off;
Default: uwsgi_socket_keepalive off;
Context: http, server, location
@Since: This directive appeared in version 1.15.6.

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

uwsgi_ssl_certificate¶

Syntax: uwsgi_ssl_certificate file;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.7.8.

Specifies a file with the certificate in the PEM format used for authentication to a secured uwsgi server.

uwsgi_ssl_certificate_cache¶

Syntax: uwsgi_ssl_certificate_cache off; uwsgi_ssl_certificate_cache max=N [inactive=time] [valid=time];
Default: uwsgi_ssl_certificate_cache off;
Context: http, server, location
@Since: This directive appeared in version 1.27.4.

Defines a cache that stores SSL certificates and secret keys specified with variables.

uwsgi_ssl_certificate_key¶

Syntax: uwsgi_ssl_certificate_key file;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.7.8.

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

uwsgi_ssl_ciphers¶

Syntax: uwsgi_ssl_ciphers ciphers;
Default: uwsgi_ssl_ciphers DEFAULT;
Context: http, server, location
@Since: This directive appeared in version 1.5.8.

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

uwsgi_ssl_conf_command¶

Syntax: uwsgi_ssl_conf_command name value;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.19.4.

Sets arbitrary OpenSSL configuration commands when establishing a connection with the secured uwsgi server.

uwsgi_ssl_crl¶

Syntax: uwsgi_ssl_crl file;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.7.0.

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

uwsgi_ssl_key_log¶

Syntax: uwsgi_ssl_key_log path;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.27.2.

Enables logging of secured uwsgi server connection SSL keys and specifies the path to the key log file. Keys are logged in the SSLKEYLOGFILE format compatible with Wireshark.

uwsgi_ssl_name¶

Syntax: uwsgi_ssl_name name;
Default: uwsgi_ssl_name host from uwsgi_pass;
Context: http, server, location
@Since: This directive appeared in version 1.7.0.

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.

uwsgi_ssl_password_file¶

Syntax: uwsgi_ssl_password_file file;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.7.8.

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

uwsgi_ssl_protocols¶

Syntax: uwsgi_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: uwsgi_ssl_protocols TLSv1.2 TLSv1.3;
Context: http, server, location
@Since: This directive appeared in version 1.5.8.

Enables the specified protocols for requests to a secured uwsgi server.

uwsgi_ssl_server_name¶

Syntax: uwsgi_ssl_server_name on | off;
Default: uwsgi_ssl_server_name off;
Context: http, server, location
@Since: This directive appeared in version 1.7.0.

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

uwsgi_ssl_session_reuse¶

Syntax: uwsgi_ssl_session_reuse on | off;
Default: uwsgi_ssl_session_reuse on;
Context: http, server, location
@Since: This directive appeared in version 1.5.8.

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

uwsgi_ssl_trusted_certificate¶

Syntax: uwsgi_ssl_trusted_certificate file;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.7.0.

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

uwsgi_ssl_verify¶

Syntax: uwsgi_ssl_verify on | off;
Default: uwsgi_ssl_verify off;
Context: http, server, location
@Since: This directive appeared in version 1.7.0.

Enables or disables verification of the secured uwsgi server certificate.

uwsgi_ssl_verify_depth¶

Syntax: uwsgi_ssl_verify_depth number;
Default: uwsgi_ssl_verify_depth 1;
Context: http, server, location
@Since: This directive appeared in version 1.7.0.

Sets the verification depth in the secured uwsgi server certificates chain.

uwsgi_store¶

Syntax: uwsgi_store on | off | string;
Default: uwsgi_store off;
Context: http, server, location
@Since: None

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:

uwsgi_store_access¶

Syntax: uwsgi_store_access users:permissions ...;
Default: uwsgi_store_access user:rw;
Context: http, server, location
@Since: None

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

uwsgi_temp_file_write_size¶

Syntax: uwsgi_temp_file_write_size size;
Default: uwsgi_temp_file_write_size 8k|16k;
Context: http, server, location
@Since: None

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.

uwsgi_temp_path¶

Syntax: uwsgi_temp_path path [level1 [level2 [level3]]];
Default: uwsgi_temp_path uwsgi_temp;
Context: http, server, location
@Since: None

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

ngx_http_v2_module¶

http2¶

Syntax: http2 on | off;
Default: http2 off;
Context: http, server
@Since: This directive appeared in version 1.25.1.

Enables the HTTP/2 protocol.

http2_body_preread_size¶

Syntax: http2_body_preread_size size;
Default: http2_body_preread_size 64k;
Context: http, server
@Since: This directive appeared in version 1.11.0.

Sets the size of the buffer per each request in which the request body may be saved before it is started to be processed.

http2_chunk_size¶

Syntax: http2_chunk_size size;
Default: http2_chunk_size 8k;
Context: http, server, location
@Since: None

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.

http2_idle_timeout¶

Syntax: http2_idle_timeout time;
Default: http2_idle_timeout 3m;
Context: http, server
@Since: None

None

http2_max_concurrent_pushes¶

Syntax: http2_max_concurrent_pushes number;
Default: http2_max_concurrent_pushes 10;
Context: http, server
@Since: This directive appeared in version 1.13.9.

None

http2_max_concurrent_streams¶

Syntax: http2_max_concurrent_streams number;
Default: http2_max_concurrent_streams 128;
Context: http, server
@Since: None

Sets the maximum number of concurrent HTTP/2 streams in a connection.

http2_max_field_size¶

Syntax: http2_max_field_size size;
Default: http2_max_field_size 4k;
Context: http, server
@Since: None

None

http2_max_header_size¶

Syntax: http2_max_header_size size;
Default: http2_max_header_size 16k;
Context: http, server
@Since: None

None

http2_max_requests¶

Syntax: http2_max_requests number;
Default: http2_max_requests 1000;
Context: http, server
@Since: This directive appeared in version 1.11.6.

None

http2_push¶

Syntax: http2_push uri | off;
Default: http2_push off;
Context: http, server, location
@Since: This directive appeared in version 1.13.9.

None

http2_push_preload¶

Syntax: http2_push_preload on | off;
Default: http2_push_preload off;
Context: http, server, location
@Since: This directive appeared in version 1.13.9.

None

http2_recv_buffer_size¶

Syntax: http2_recv_buffer_size size;
Default: http2_recv_buffer_size 256k;
Context: http
@Since: None

Sets the size of the per worker input buffer.

http2_recv_timeout¶

Syntax: http2_recv_timeout time;
Default: http2_recv_timeout 30s;
Context: http, server
@Since: None

None

ngx_http_v3_module¶

http3¶

Syntax: http3 on | off;
Default: http3 on;
Context: http, server
@Since: None

Enables HTTP/3 protocol negotiation.

http3_hq¶

Syntax: http3_hq on | off;
Default: http3_hq off;
Context: http, server
@Since: None

Enables HTTP/0.9 protocol negotiation used in QUIC interoperability tests.

http3_max_concurrent_streams¶

Syntax: http3_max_concurrent_streams number;
Default: http3_max_concurrent_streams 128;
Context: http, server
@Since: None

Sets the maximum number of concurrent HTTP/3 request streams in a connection.

http3_stream_buffer_size¶

Syntax: http3_stream_buffer_size size;
Default: http3_stream_buffer_size 64k;
Context: http, server
@Since: None

Sets the size of the buffer used for reading and writing of the QUIC streams.

quic_active_connection_id_limit¶

Syntax: quic_active_connection_id_limit number;
Default: quic_active_connection_id_limit 2;
Context: http, server
@Since: None

Sets the QUIC active_connection_id_limit transport parameter value. This is the maximum number of client connection IDs which can be stored on the server.

quic_bpf¶

Syntax: quic_bpf on | off;
Default: quic_bpf off;
Context: main
@Since: None

Enables routing of QUIC packets using eBPF. When enabled, this allows supporting QUIC connection migration.

quic_gso¶

Syntax: quic_gso on | off;
Default: quic_gso off;
Context: http, server
@Since: None

Enables sending in optimized batch mode using segmentation offloading.

quic_host_key¶

Syntax: quic_host_key file;
Default: —
Context: http, server
@Since: None

Sets a file with the secret key used to encrypt stateless reset and address validation tokens. By default, a random key is generated on each reload. Tokens generated with old keys are not accepted.

quic_retry¶

Syntax: quic_retry on | off;
Default: quic_retry off;
Context: http, server
@Since: None

Enables the QUIC Address Validation feature. This includes sending a new token in a Retry packet or a NEW_TOKEN frame and validating a token received in the Initial packet.

ngx_http_xslt_module¶

xml_entities¶

Syntax: xml_entities path;
Default: —
Context: http, server, location
@Since: None

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:

xslt_last_modified¶

Syntax: xslt_last_modified on | off;
Default: xslt_last_modified off;
Context: http, server, location
@Since: This directive appeared in version 1.5.1.

Allows preserving the “Last-Modified” header field from the original response during XSLT transformations to facilitate response caching.

xslt_param parameter¶

Syntax: xslt_param parameter value;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.1.18.

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.

xslt_string_param parameter¶

Syntax: xslt_string_param parameter value;
Default: —
Context: http, server, location
@Since: This directive appeared in version 1.1.18.

Defines the string parameters for XSLT stylesheets. XPath expressions in the value are not interpreted. The value can contain variables.

xslt_stylesheet¶

Syntax: xslt_stylesheet stylesheet [parameter=value ...];
Default: —
Context: location
@Since: None

Defines the XSLT stylesheet and its optional parameters. A stylesheet is compiled at the configuration stage.

xslt_types¶

Syntax: xslt_types mime-type ...;
Default: xslt_types text/xml;
Context: http, server, location
@Since: None

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

ngx_mail_core_module¶

listen¶

Syntax: listen address:port [ssl] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [bind] [ipv6only=on|off] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
Default: —
Context: server
@Since: None

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:

mail¶

Syntax: mail { ... }
Default: —
Context: main
@Since: None

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

max_errors¶

Syntax: max_errors number;
Default: max_errors 5;
Context: mail, server
@Since: This directive appeared in version 1.21.0.

Sets the number of protocol errors after which the connection is closed.

protocol¶

Syntax: protocol imap | pop3 | smtp;
Default: —
Context: server
@Since: None

Sets the protocol for a proxied server. Supported protocols are IMAP, POP3, and SMTP.

[mail] resolver¶

Syntax: resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone]; resolver off;
Default: resolver off;
Context: mail, server
@Since: None

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:

[mail] resolver_timeout¶

Syntax: resolver_timeout time;
Default: resolver_timeout 30s;
Context: mail, server
@Since: None

Sets a timeout for DNS operations, for example:

[mail] server¶

Syntax: server { ... }
Default: —
Context: mail
@Since: None

Sets the configuration for a server.

[mail] server_name¶

Syntax: server_name name;
Default: server_name hostname;
Context: mail, server
@Since: None

Sets the server name that is used:

[mail] timeout¶

Syntax: timeout time;
Default: timeout 60s;
Context: mail, server
@Since: None

Sets the timeout that is used before proxying to the backend starts.

ngx_mail_auth_http_module¶

auth_http¶

Syntax: auth_http URL;
Default: —
Context: mail, server
@Since: None

Sets the URL of the HTTP authentication server. The protocol is described below.

auth_http_header¶

Syntax: auth_http_header header value;
Default: —
Context: mail, server
@Since: None

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:

auth_http_pass_client_cert¶

Syntax: auth_http_pass_client_cert on | off;
Default: auth_http_pass_client_cert off;
Context: mail, server
@Since: This directive appeared in version 1.7.11.

Appends the “Auth-SSL-Cert” header with the client certificate in the PEM format (urlencoded) to requests sent to the authentication server.

auth_http_timeout¶

Syntax: auth_http_timeout time;
Default: auth_http_timeout 60s;
Context: mail, server
@Since: None

Sets the timeout for communication with the authentication server.

ngx_mail_proxy_module¶

proxy_buffer¶

Syntax: proxy_buffer size;
Default: proxy_buffer 4k|8k;
Context: mail, server
@Since: None

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.

proxy_pass_error_message¶

Syntax: proxy_pass_error_message on | off;
Default: proxy_pass_error_message off;
Context: mail, server
@Since: None

Indicates whether to pass the error message obtained during the authentication on the backend to the client.

proxy_protocol¶

Syntax: proxy_protocol on | off;
Default: proxy_protocol off;
Context: mail, server
@Since: This directive appeared in version 1.19.8.

Enables the PROXY protocol for connections to a backend.

proxy_smtp_auth¶

Syntax: proxy_smtp_auth on | off;
Default: proxy_smtp_auth off;
Context: mail, server
@Since: This directive appeared in version 1.19.4.

Enables or disables user authentication on the SMTP backend using the AUTH command.

proxy_timeout¶

Syntax: proxy_timeout timeout;
Default: proxy_timeout 24h;
Context: mail, server
@Since: None

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.

xclient¶

Syntax: xclient on | off;
Default: xclient on;
Context: mail, server
@Since: None

Enables or disables the passing of the XCLIENT command with client parameters when connecting to the SMTP backend.

ngx_mail_realip_module¶

[mail] set_real_ip_from¶

Syntax: set_real_ip_from address | CIDR | unix:;
Default: —
Context: mail, server
@Since: None

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.

ngx_mail_ssl_module¶

[mail] ssl¶

Syntax: ssl on | off;
Default: ssl off;
Context: mail, server
@Since: None

This directive was made obsolete in version 1.15.0 and was removed in version 1.25.1. The ssl parameter of the listen directive should be used instead.

[mail] ssl_certificate¶

Syntax: ssl_certificate file;
Default: —
Context: mail, server
@Since: None

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.

[mail] ssl_certificate_key¶

Syntax: ssl_certificate_key file;
Default: —
Context: mail, server
@Since: None

Specifies a file with the secret key in the PEM format for the given server.

[mail] ssl_ciphers¶

Syntax: ssl_ciphers ciphers;
Default: ssl_ciphers HIGH:!aNULL:!MD5;
Context: mail, server
@Since: None

Specifies the enabled ciphers. The ciphers are specified in the format understood by the OpenSSL library, for example:

[mail] ssl_client_certificate¶

Syntax: ssl_client_certificate file;
Default: —
Context: mail, server
@Since: This directive appeared in version 1.7.11.

Specifies a file with trusted CA certificates in the PEM format used to verify client certificates.

[mail] ssl_conf_command¶

Syntax: ssl_conf_command name value;
Default: —
Context: mail, server
@Since: This directive appeared in version 1.19.4.

Sets arbitrary OpenSSL configuration commands.

[mail] ssl_crl¶

Syntax: ssl_crl file;
Default: —
Context: mail, server
@Since: This directive appeared in version 1.7.11.

Specifies a file with revoked certificates (CRL) in the PEM format used to verify client certificates.

[mail] ssl_dhparam¶

Syntax: ssl_dhparam file;
Default: —
Context: mail, server
@Since: This directive appeared in version 0.7.2.

Specifies a file with DH parameters for DHE ciphers.

[mail] ssl_ecdh_curve¶

Syntax: ssl_ecdh_curve curve;
Default: ssl_ecdh_curve auto;
Context: mail, server
@Since: This directive appeared in versions 1.1.0 and 1.0.6.

Specifies a curve for ECDHE ciphers.

[mail] ssl_password_file¶

Syntax: ssl_password_file file;
Default: —
Context: mail, server
@Since: This directive appeared in version 1.7.3.

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.

[mail] ssl_prefer_server_ciphers¶

Syntax: ssl_prefer_server_ciphers on | off;
Default: ssl_prefer_server_ciphers off;
Context: mail, server
@Since: None

Specifies that server ciphers should be preferred over client ciphers when the SSLv3 and TLS protocols are used.

[mail] ssl_protocols¶

Syntax: ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: ssl_protocols TLSv1.2 TLSv1.3;
Context: mail, server
@Since: None

Enables the specified protocols.

[mail] ssl_session_cache¶

Syntax: ssl_session_cache off | none | [builtin[:size]] [shared:name:size];
Default: ssl_session_cache none;
Context: mail, server
@Since: None

Sets the types and sizes of caches that store session parameters. A cache can be of any of the following types:

[mail] ssl_session_ticket_key¶

Syntax: ssl_session_ticket_key file;
Default: —
Context: mail, server
@Since: This directive appeared in version 1.5.7.

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.

[mail] ssl_session_tickets¶

Syntax: ssl_session_tickets on | off;
Default: ssl_session_tickets on;
Context: mail, server
@Since: This directive appeared in version 1.5.9.

Enables or disables session resumption through TLS session tickets.

[mail] ssl_session_timeout¶

Syntax: ssl_session_timeout time;
Default: ssl_session_timeout 5m;
Context: mail, server
@Since: None

Specifies a time during which a client may reuse the session parameters.

[mail] ssl_trusted_certificate¶

Syntax: ssl_trusted_certificate file;
Default: —
Context: mail, server
@Since: This directive appeared in version 1.7.11.

Specifies a file with trusted CA certificates in the PEM format used to verify client certificates.

[mail] ssl_verify_client¶

Syntax: ssl_verify_client on | off | optional | optional_no_ca;
Default: ssl_verify_client off;
Context: mail, server
@Since: This directive appeared in version 1.7.11.

Enables verification of client certificates. The verification result is passed in the “Auth-SSL-Verify” header of the authentication request.

[mail] ssl_verify_depth¶

Syntax: ssl_verify_depth number;
Default: ssl_verify_depth 1;
Context: mail, server
@Since: This directive appeared in version 1.7.11.

Sets the verification depth in the client certificates chain.

[mail] starttls¶

Syntax: starttls on | off | only;
Default: starttls off;
Context: mail, server
@Since: None

None

ngx_mail_imap_module¶

[mail] imap_auth¶

Syntax: imap_auth method ...;
Default: imap_auth plain;
Context: mail, server
@Since: None

Sets permitted methods of authentication for IMAP clients. Supported methods are:

[mail] imap_capabilities¶

Syntax: imap_capabilities extension ...;
Default: imap_capabilities IMAP4 IMAP4rev1 UIDPLUS;
Context: mail, server
@Since: None

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.

[mail] imap_client_buffer¶

Syntax: imap_client_buffer size;
Default: imap_client_buffer 4k|8k;
Context: mail, server
@Since: None

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.

ngx_mail_pop3_module¶

pop3_auth¶

Syntax: pop3_auth method ...;
Default: pop3_auth plain;
Context: mail, server
@Since: None

Sets permitted methods of authentication for POP3 clients. Supported methods are:

pop3_capabilities¶

Syntax: pop3_capabilities extension ...;
Default: pop3_capabilities TOP USER UIDL;
Context: mail, server
@Since: None

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.

ngx_mail_smtp_module¶

smtp_auth¶

Syntax: smtp_auth method ...;
Default: smtp_auth plain login;
Context: mail, server
@Since: None

Sets permitted methods of SASL authentication for SMTP clients. Supported methods are:

smtp_capabilities¶

Syntax: smtp_capabilities extension ...;
Default: —
Context: mail, server
@Since: None

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.

smtp_client_buffer¶

Syntax: smtp_client_buffer size;
Default: smtp_client_buffer 4k|8k;
Context: mail, server
@Since: None

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.

smtp_greeting_delay¶

Syntax: smtp_greeting_delay time;
Default: smtp_greeting_delay 0;
Context: mail, server
@Since: None

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.

ngx_stream_core_module¶

[stream] listen¶

Syntax: listen address:port [default_server] [ssl] [udp] [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]];
Default: —
Context: server
@Since: None

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:

preread_buffer_size¶

Syntax: preread_buffer_size size;
Default: preread_buffer_size 16k;
Context: stream, server
@Since: This directive appeared in version 1.11.5.

Specifies a size of the preread buffer.

preread_timeout¶

Syntax: preread_timeout timeout;
Default: preread_timeout 30s;
Context: stream, server
@Since: This directive appeared in version 1.11.5.

Specifies a timeout of the preread phase.

proxy_protocol_timeout¶

Syntax: proxy_protocol_timeout timeout;
Default: proxy_protocol_timeout 30s;
Context: stream, server
@Since: This directive appeared in version 1.11.4.

Specifies a timeout for reading the PROXY protocol header to complete. If no entire header is transmitted within this time, the connection is closed.

[stream] resolver¶

Syntax: resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone];
Default: —
Context: stream, server
@Since: This directive appeared in version 1.11.3.

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

[stream] resolver_timeout¶

Syntax: resolver_timeout time;
Default: resolver_timeout 30s;
Context: stream, server
@Since: This directive appeared in version 1.11.3.

Sets a timeout for name resolution, for example:

[stream] server¶

Syntax: server { ... }
Default: —
Context: stream
@Since: None

Sets the configuration for a virtual server. There is no clear separation between IP-based (based on the IP address) and name-based (based on the TLS Server Name Indication extension (SNI, RFC 6066)) (1.25.5) 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.

[stream] server_name¶

Syntax: server_name name ...;
Default: server_name "";
Context: server
@Since: This directive appeared in version 1.25.5.

Sets names of a virtual server, for example:

[stream] server_names_hash_bucket_size¶

Syntax: server_names_hash_bucket_size size;
Default: server_names_hash_bucket_size 32|64|128;
Context: stream
@Since: This directive appeared in version 1.25.5.

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.

[stream] server_names_hash_max_size¶

Syntax: server_names_hash_max_size size;
Default: server_names_hash_max_size 512;
Context: stream
@Since: This directive appeared in version 1.25.5.

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

stream¶

Syntax: stream { ... }
Default: —
Context: main
@Since: None

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

[stream] tcp_nodelay¶

Syntax: tcp_nodelay on | off;
Default: tcp_nodelay on;
Context: stream, server
@Since: This directive appeared in version 1.9.4.

Enables or disables the use of the TCP_NODELAY option. The option is enabled for both client and proxied server connections.

[stream] variables_hash_bucket_size¶

Syntax: variables_hash_bucket_size size;
Default: variables_hash_bucket_size 64;
Context: stream
@Since: This directive appeared in version 1.11.2.

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

[stream] variables_hash_max_size¶

Syntax: variables_hash_max_size size;
Default: variables_hash_max_size 1024;
Context: stream
@Since: This directive appeared in version 1.11.2.

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

ngx_stream_access_module¶

[stream] allow¶

Syntax: allow address | CIDR | unix: | all;
Default: —
Context: stream, server
@Since: None

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

[stream] deny¶

Syntax: deny address | CIDR | unix: | all;
Default: —
Context: stream, server
@Since: None

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

ngx_stream_geo_module¶

[stream] geo¶

Syntax: geo [$address] $variable { ... }
Default: —
Context: stream
@Since: None

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:

ngx_stream_geoip_module¶

[stream] geoip_country¶

Syntax: geoip_country file;
Default: —
Context: stream
@Since: None

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

[stream] geoip_city¶

Syntax: geoip_city file;
Default: —
Context: stream
@Since: None

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:

[stream] geoip_org¶

Syntax: geoip_org file;
Default: —
Context: stream
@Since: None

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

ngx_stream_js_module¶

js_access¶

Syntax: js_access function | module.function;
Default: —
Context: stream, server
@Since: None

Sets an njs function which will be called at the access phase. Since 0.4.0, a module function can be referenced.

[stream] js_context_reuse¶

Syntax: js_context_reuse number;
Default: js_context_reuse 128;
Context: stream, server
@Since: This directive appeared in version 0.8.6.

Sets a maximum number of JS context to be reused for QuickJS engine. Each context is used for a single stream session. The finished context is put into a pool of reusable contexts. If the pool is full, the context is destroyed.

[stream] js_engine¶

Syntax: js_engine njs | qjs;
Default: js_engine njs;
Context: stream, server
@Since: This directive appeared in version 0.8.6.

Sets a JavaScript engine to be used for njs scripts. The njs parameter sets the njs engine, also used by default. The qjs parameter sets the QuickJS engine.

[stream] js_fetch_buffer_size¶

Syntax: js_fetch_buffer_size size;
Default: js_fetch_buffer_size 16k;
Context: stream, server
@Since: This directive appeared in version 0.7.4.

Sets the size of the buffer used for reading and writing with Fetch API.

[stream] js_fetch_ciphers¶

Syntax: js_fetch_ciphers ciphers;
Default: js_fetch_ciphers HIGH:!aNULL:!MD5;
Context: stream, server
@Since: This directive appeared in version 0.7.0.

Specifies the enabled ciphers for HTTPS connections with Fetch API. The ciphers are specified in the format understood by the OpenSSL library.

[stream] js_fetch_max_response_buffer_size¶

Syntax: js_fetch_max_response_buffer_size size;
Default: js_fetch_max_response_buffer_size 1m;
Context: stream, server
@Since: This directive appeared in version 0.7.4.

Sets the maximum size of the response received with Fetch API.

[stream] js_fetch_protocols¶

Syntax: js_fetch_protocols [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2;
Context: stream, server
@Since: This directive appeared in version 0.7.0.

Enables the specified protocols for HTTPS connections with Fetch API.

[stream] js_fetch_timeout¶

Syntax: js_fetch_timeout time;
Default: js_fetch_timeout 60s;
Context: stream, server
@Since: This directive appeared in version 0.7.4.

Defines a timeout for reading and writing for Fetch API. The timeout is set only between two successive read/write operations, not for the whole response. If no data is transmitted within this time, the connection is closed.

[stream] js_fetch_trusted_certificate¶

Syntax: js_fetch_trusted_certificate file;
Default: —
Context: stream, server
@Since: This directive appeared in version 0.7.0.

Specifies a file with trusted CA certificates in the PEM format used to verify the HTTPS certificate with Fetch API.

[stream] js_fetch_verify¶

Syntax: js_fetch_verify on | off;
Default: js_fetch_verify on;
Context: stream, server
@Since: This directive appeared in version 0.7.4.

Enables or disables verification of the HTTPS server certificate with Fetch API.

[stream] js_fetch_verify_depth¶

Syntax: js_fetch_verify_depth number;
Default: js_fetch_verify_depth 100;
Context: stream, server
@Since: This directive appeared in version 0.7.0.

Sets the verification depth in the HTTPS server certificates chain with Fetch API.

[stream] js_filter¶

Syntax: js_filter function | module.function;
Default: —
Context: stream, server
@Since: None

Sets a data filter. Since 0.4.0, a module function can be referenced. The filter function is called once at the moment when the stream session reaches the content phase.

[stream] js_import¶

Syntax: js_import module.js | export_name from module.js;
Default: —
Context: stream, server
@Since: This directive appeared in version 0.4.0.

Imports a module that implements location and variable handlers in njs. The export_name is used as a namespace to access module functions. If the export_name is not specified, the module name will be used as a namespace.

[stream] js_include¶

Syntax: js_include file;
Default: —
Context: stream
@Since: None

Specifies a file that implements server and variable handlers in njs:

[stream] js_path¶

Syntax: js_path path;
Default: —
Context: stream, server
@Since: This directive appeared in version 0.3.0.

Sets an additional path for njs modules.

[stream] js_periodic¶

Syntax: js_periodic function | module.function [interval=time] [jitter=number] [worker_affinity=mask];
Default: —
Context: server
@Since: This directive appeared in version 0.8.1.

Specifies a content handler to run at regular interval. The handler receives a session object as its first argument, it also has access to global objects such as ngx.

[stream] js_preload_object¶

Syntax: js_preload_object name.json | name from file.json;
Default: —
Context: stream, server
@Since: This directive appeared in version 0.7.8.

Preloads an immutable object at configure time. The name is used as a name of the global variable though which the object is available in njs code. If the name is not specified, the file name will be used instead.

[stream] js_preread¶

Syntax: js_preread function | module.function;
Default: —
Context: stream, server
@Since: None

Sets an njs function which will be called at the preread phase. Since 0.4.0, a module function can be referenced.

[stream] js_set¶

Syntax: js_set $variable function | module.function [nocache];
Default: —
Context: stream, server
@Since: None

Sets an njs function for the specified variable. Since 0.4.0, a module function can be referenced.

[stream] js_shared_dict_zone¶

Syntax: js_shared_dict_zone zone=name:size [timeout=time] [type=string|number] [evict] [state=file];
Default: —
Context: stream
@Since: This directive appeared in version 0.8.0.

Sets the name and size of the shared memory zone that keeps the key-value dictionary shared between worker processes.

[stream] js_var¶

Syntax: js_var $variable [value];
Default: —
Context: stream, server
@Since: This directive appeared in version 0.5.3.

Declares a writable variable. The value can contain text, variables, and their combination.

ngx_stream_keyval_module¶

[stream] keyval¶

Syntax: keyval key $variable zone=name;
Default: —
Context: stream
@Since: None

Creates a new $variable whose value is looked up by the key in the key-value database. Matching rules are defined by the type parameter of the keyval_zone directive. The database is stored in a shared memory zone specified by the zone parameter.

[stream] keyval_zone¶

Syntax: keyval_zone zone=name:size [state=file] [timeout=time] [type=string|ip|prefix] [sync];
Default: —
Context: stream
@Since: None

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

ngx_stream_limit_conn_module¶

[stream] limit_conn¶

Syntax: limit_conn zone number;
Default: —
Context: stream, server
@Since: None

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

[stream] limit_conn_dry_run¶

Syntax: limit_conn_dry_run on | off;
Default: limit_conn_dry_run off;
Context: stream, server
@Since: This directive appeared in version 1.17.6.

Enables the dry run mode. In this mode, the number of connections is not limited, however, in the shared memory zone, the number of excessive connections is accounted as usual.

[stream] limit_conn_log_level¶

Syntax: limit_conn_log_level info | notice | warn | error;
Default: limit_conn_log_level error;
Context: stream, server
@Since: None

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

[stream] limit_conn_zone¶

Syntax: limit_conn_zone key zone=name:size;
Default: —
Context: stream
@Since: None

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:

ngx_stream_log_module¶

[stream] access_log¶

Syntax: access_log path format [buffer=size] [gzip[=level]] [flush=time] [if=condition]; access_log off;
Default: access_log off;
Context: stream, server
@Since: None

Sets the path, format, and configuration for a buffered log write. Several logs can be specified on the same configuration 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.

[stream] log_format¶

Syntax: log_format name [escape=default|json|none] string ...;
Default: —
Context: stream
@Since: None

Specifies the log format, for example:

[stream] open_log_file_cache¶

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
@Since: None

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

ngx_stream_map_module¶

[stream] map¶

Syntax: map string $variable { ... }
Default: —
Context: stream
@Since: None

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

[stream] map_hash_bucket_size¶

Syntax: map_hash_bucket_size size;
Default: map_hash_bucket_size 32|64|128;
Context: stream
@Since: None

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.

[stream] map_hash_max_size¶

Syntax: map_hash_max_size size;
Default: map_hash_max_size 2048;
Context: stream
@Since: None

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

ngx_stream_mqtt_preread_module¶

mqtt_preread¶

Syntax: mqtt_preread on | off;
Default: mqtt_preread off;
Context: stream, server
@Since: None

Enables extracting information from the MQTT CONNECT message at the preread phase.

ngx_stream_mqtt_filter_module¶

mqtt¶

Syntax: mqtt on | off;
Default: mqtt off;
Context: stream, server
@Since: None

Enables the MQTT protocol for the given virtual server.

mqtt_buffers¶

Syntax: mqtt_buffers number size;
Default: mqtt_buffers 100 1k;
Context: stream, server
@Since: This directive appeared in version 1.25.1.

Sets the number and size of the buffers used for handling MQTT messages, for a single connection.

mqtt_rewrite_buffer_size¶

Syntax: mqtt_rewrite_buffer_size size;
Default: mqtt_rewrite_buffer_size 4k|8k;
Context: server
@Since: None

None

mqtt_set_connect¶

Syntax: mqtt_set_connect field value;
Default: —
Context: server
@Since: None

Sets the message field to the given value for CONNECT message. The following fields are supported: clientid, username, and password. The value can contain text, variables, and their combination.

ngx_stream_pass_module¶

pass¶

Syntax: pass address;
Default: —
Context: server
@Since: None

Sets server address to pass client connection to. The address can be specified as an IP address and a port:

ngx_stream_proxy_module¶

[stream] proxy_bind¶

Syntax: proxy_bind address [transparent] | off;
Default: —
Context: stream, server
@Since: This directive appeared in version 1.9.2.

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.

[stream] proxy_buffer_size¶

Syntax: proxy_buffer_size size;
Default: proxy_buffer_size 16k;
Context: stream, server
@Since: This directive appeared in version 1.9.4.

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.

[stream] proxy_connect_timeout¶

Syntax: proxy_connect_timeout time;
Default: proxy_connect_timeout 60s;
Context: stream, server
@Since: None

Defines a timeout for establishing a connection with a proxied server.

[stream] proxy_download_rate¶

Syntax: proxy_download_rate rate;
Default: proxy_download_rate 0;
Context: stream, server
@Since: This directive appeared in version 1.9.3.

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.

[stream] proxy_half_close¶

Syntax: proxy_half_close on | off;
Default: proxy_half_close off;
Context: stream, server
@Since: This directive appeared in version 1.21.4.

Enables or disables closing each direction of a TCP connection independently (“TCP half-close”). If enabled, proxying over TCP will be kept until both sides close the connection.

[stream] proxy_next_upstream¶

Syntax: proxy_next_upstream on | off;
Default: proxy_next_upstream on;
Context: stream, server
@Since: None

When a connection to the proxied server cannot be established, determines whether a client connection will be passed to the next server.

[stream] proxy_next_upstream_timeout¶

Syntax: proxy_next_upstream_timeout time;
Default: proxy_next_upstream_timeout 0;
Context: stream, server
@Since: None

Limits the time allowed to pass a connection to the next server. The 0 value turns off this limitation.

[stream] proxy_next_upstream_tries¶

Syntax: proxy_next_upstream_tries number;
Default: proxy_next_upstream_tries 0;
Context: stream, server
@Since: None

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

[stream] proxy_pass¶

Syntax: proxy_pass address;
Default: —
Context: server
@Since: None

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

[stream] proxy_protocol¶

Syntax: proxy_protocol on | off;
Default: proxy_protocol off;
Context: stream, server
@Since: This directive appeared in version 1.9.2.

Enables the PROXY protocol for connections to a proxied server.

[stream] proxy_requests¶

Syntax: proxy_requests number;
Default: proxy_requests 0;
Context: stream, server
@Since: This directive appeared in version 1.15.7.

Sets the number of client datagrams at which binding between a client and existing UDP stream session is dropped. After receiving the specified number of datagrams, next datagram from the same client starts a new session. The session terminates when all client datagrams are transmitted to a proxied server and the expected number of responses is received, or when it reaches a timeout.

[stream] proxy_responses¶

Syntax: proxy_responses number;
Default: —
Context: stream, server
@Since: This directive appeared in version 1.9.13.

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.

[stream] proxy_session_drop¶

Syntax: proxy_session_drop on | off;
Default: proxy_session_drop off;
Context: stream, server
@Since: This directive appeared in version 1.15.8.

Enables terminating all sessions to a proxied server after it was removed from the group or marked as permanently unavailable. This can occur because of re-resolve or with the API DELETE command. A server can be marked as permanently unavailable if it is considered unhealthy or with the API PATCH command. Each session is terminated when the next read or write event is processed for the client or proxied server.

[stream] proxy_socket_keepalive¶

Syntax: proxy_socket_keepalive on | off;
Default: proxy_socket_keepalive off;
Context: stream, server
@Since: This directive appeared in version 1.15.6.

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

[stream] proxy_ssl¶

Syntax: proxy_ssl on | off;
Default: proxy_ssl off;
Context: stream, server
@Since: None

Enables the SSL/TLS protocol for connections to a proxied server.

[stream] proxy_ssl_certificate¶

Syntax: proxy_ssl_certificate file;
Default: —
Context: stream, server
@Since: None

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

[stream] proxy_ssl_certificate_cache¶

Syntax: proxy_ssl_certificate_cache off; proxy_ssl_certificate_cache max=N [inactive=time] [valid=time];
Default: proxy_ssl_certificate_cache off;
Context: stream, server
@Since: This directive appeared in version 1.27.4.

Defines a cache that stores SSL certificates and secret keys specified with variables.

[stream] proxy_ssl_certificate_key¶

Syntax: proxy_ssl_certificate_key file;
Default: —
Context: stream, server
@Since: None

The value store:scheme:id can be specified instead of the file (1.29.0), which is used to load a secret key with a specified id and OpenSSL provider registered URI scheme, such as pkcs11.

[stream] proxy_ssl_ciphers¶

Syntax: proxy_ssl_ciphers ciphers;
Default: proxy_ssl_ciphers DEFAULT;
Context: stream, server
@Since: None

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

[stream] proxy_ssl_conf_command¶

Syntax: proxy_ssl_conf_command name value;
Default: —
Context: stream, server
@Since: This directive appeared in version 1.19.4.

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

[stream] proxy_ssl_crl¶

Syntax: proxy_ssl_crl file;
Default: —
Context: stream, server
@Since: None

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

[stream] proxy_ssl_key_log¶

Syntax: proxy_ssl_key_log path;
Default: —
Context: stream, server
@Since: This directive appeared in version 1.27.2.

Enables logging of proxied server connection SSL keys and specifies the path to the key log file. Keys are logged in the SSLKEYLOGFILE format compatible with Wireshark.

[stream] proxy_ssl_name¶

Syntax: proxy_ssl_name name;
Default: proxy_ssl_name host from proxy_pass;
Context: stream, server
@Since: None

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

[stream] proxy_ssl_password_file¶

Syntax: proxy_ssl_password_file file;
Default: —
Context: stream, server
@Since: None

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.

[stream] proxy_ssl_protocols¶

Syntax: proxy_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: proxy_ssl_protocols TLSv1.2 TLSv1.3;
Context: stream, server
@Since: None

Enables the specified protocols for connections to a proxied server.

[stream] proxy_ssl_server_name¶

Syntax: proxy_ssl_server_name on | off;
Default: proxy_ssl_server_name off;
Context: stream, server
@Since: None

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.

[stream] proxy_ssl_session_reuse¶

Syntax: proxy_ssl_session_reuse on | off;
Default: proxy_ssl_session_reuse on;
Context: stream, server
@Since: None

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

[stream] proxy_ssl_trusted_certificate¶

Syntax: proxy_ssl_trusted_certificate file;
Default: —
Context: stream, server
@Since: None

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

[stream] proxy_ssl_verify¶

Syntax: proxy_ssl_verify on | off;
Default: proxy_ssl_verify off;
Context: stream, server
@Since: None

Enables or disables verification of the proxied server certificate.

[stream] proxy_ssl_verify_depth¶

Syntax: proxy_ssl_verify_depth number;
Default: proxy_ssl_verify_depth 1;
Context: stream, server
@Since: None

Sets the verification depth in the proxied server certificates chain.

[stream] proxy_timeout¶

Syntax: proxy_timeout timeout;
Default: proxy_timeout 10m;
Context: stream, server
@Since: None

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.

[stream] proxy_upload_rate¶

Syntax: proxy_upload_rate rate;
Default: proxy_upload_rate 0;
Context: stream, server
@Since: This directive appeared in version 1.9.3.

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.

ngx_stream_proxy_protocol_vendor_module¶

None

ngx_stream_realip_module¶

[stream] set_real_ip_from¶

Syntax: set_real_ip_from address | CIDR | unix:;
Default: —
Context: stream, server
@Since: None

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.

ngx_stream_return_module¶

[stream] return value¶

Syntax: return value;
Default: —
Context: server
@Since: None

Specifies a value to send to the client. The value can contain text, variables, and their combination.

ngx_stream_set_module¶

[stream] set¶

Syntax: set $variable value;
Default: —
Context: server
@Since: None

Sets a value for the specified variable. The value can contain text, variables, and their combination.

ngx_stream_split_clients_module¶

[stream] split_clients¶

Syntax: split_clients string $variable { ... }
Default: —
Context: stream
@Since: None

Creates a variable for A/B testing, for example:

ngx_stream_ssl_module¶

[stream] ssl_alpn¶

Syntax: ssl_alpn protocol ...;
Default: —
Context: stream, server
@Since: This directive appeared in version 1.21.4.

Specifies the list of supported ALPN protocols. One of the protocols must be negotiated if the client uses ALPN:

[stream] ssl_certificate¶

Syntax: ssl_certificate file;
Default: —
Context: stream, server
@Since: None

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.

[stream] ssl_certificate_cache¶

Syntax: ssl_certificate_cache off; ssl_certificate_cache max=N [inactive=time] [valid=time];
Default: ssl_certificate_cache off;
Context: stream, server
@Since: This directive appeared in version 1.27.4.

Defines a cache that stores SSL certificates and secret keys specified with variables.

[stream] ssl_certificate_key¶

Syntax: ssl_certificate_key file;
Default: —
Context: stream, server
@Since: None

Specifies a file with the secret key in the PEM format for the given virtual server.

[stream] ssl_ciphers¶

Syntax: ssl_ciphers ciphers;
Default: ssl_ciphers HIGH:!aNULL:!MD5;
Context: stream, server
@Since: None

Specifies the enabled ciphers. The ciphers are specified in the format understood by the OpenSSL library, for example:

[stream] ssl_client_certificate¶

Syntax: ssl_client_certificate file;
Default: —
Context: stream, server
@Since: This directive appeared in version 1.11.8.

Specifies a file with trusted CA certificates in the PEM format used to verify client certificates and OCSP responses if ssl_stapling is enabled.

[stream] ssl_conf_command¶

Syntax: ssl_conf_command name value;
Default: —
Context: stream, server
@Since: This directive appeared in version 1.19.4.

Sets arbitrary OpenSSL configuration commands.

[stream] ssl_crl¶

Syntax: ssl_crl file;
Default: —
Context: stream, server
@Since: This directive appeared in version 1.11.8.

Specifies a file with revoked certificates (CRL) in the PEM format used to verify client certificates.

[stream] ssl_dhparam¶

Syntax: ssl_dhparam file;
Default: —
Context: stream, server
@Since: None

Specifies a file with DH parameters for DHE ciphers.

[stream] ssl_ecdh_curve¶

Syntax: ssl_ecdh_curve curve;
Default: ssl_ecdh_curve auto;
Context: stream, server
@Since: None

Specifies a curve for ECDHE ciphers.

[stream] ssl_handshake_timeout¶

Syntax: ssl_handshake_timeout time;
Default: ssl_handshake_timeout 60s;
Context: stream, server
@Since: None

Specifies a timeout for the SSL handshake to complete.

[stream] ssl_key_log¶

Syntax: ssl_key_log path;
Default: —
Context: stream, server
@Since: This directive appeared in version 1.27.2.

Enables logging of client connection SSL keys and specifies the path to the key log file. Keys are logged in the SSLKEYLOGFILE format compatible with Wireshark.

[stream] ssl_ocsp¶

Syntax: ssl_ocsp on | off | leaf;
Default: ssl_ocsp off;
Context: stream, server
@Since: This directive appeared in version 1.27.2.

Enables OCSP validation of the client certificate chain. The leaf parameter enables validation of the client certificate only.

[stream] ssl_ocsp_cache¶

Syntax: ssl_ocsp_cache off | [shared:name:size];
Default: ssl_ocsp_cache off;
Context: stream, server
@Since: This directive appeared in version 1.27.2.

Sets name and size of the cache that stores client certificates status for OCSP validation. The cache is shared between all worker processes. A cache with the same name can be used in several virtual servers.

[stream] ssl_ocsp_responder¶

Syntax: ssl_ocsp_responder url;
Default: —
Context: stream, server
@Since: This directive appeared in version 1.27.2.

Overrides the URL of the OCSP responder specified in the “Authority Information Access” certificate extension for validation of client certificates.

[stream] ssl_password_file¶

Syntax: ssl_password_file file;
Default: —
Context: stream, server
@Since: None

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.

[stream] ssl_prefer_server_ciphers¶

Syntax: ssl_prefer_server_ciphers on | off;
Default: ssl_prefer_server_ciphers off;
Context: stream, server
@Since: None

Specifies that server ciphers should be preferred over client ciphers when the SSLv3 and TLS protocols are used.

[stream] ssl_protocols¶

Syntax: ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: ssl_protocols TLSv1.2 TLSv1.3;
Context: stream, server
@Since: None

Enables the specified protocols.

[stream] ssl_reject_handshake¶

Syntax: ssl_reject_handshake on | off;
Default: ssl_reject_handshake off;
Context: stream, server
@Since: This directive appeared in version 1.25.5.

If enabled, SSL handshakes in the server block will be rejected.

[stream] ssl_session_cache¶

Syntax: ssl_session_cache off | none | [builtin[:size]] [shared:name:size];
Default: ssl_session_cache none;
Context: stream, server
@Since: None

Sets the types and sizes of caches that store session parameters. A cache can be of any of the following types:

[stream] ssl_session_ticket_key¶

Syntax: ssl_session_ticket_key file;
Default: —
Context: stream, server
@Since: None

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.

[stream] ssl_session_tickets¶

Syntax: ssl_session_tickets on | off;
Default: ssl_session_tickets on;
Context: stream, server
@Since: None

Enables or disables session resumption through TLS session tickets.

[stream] ssl_session_timeout¶

Syntax: ssl_session_timeout time;
Default: ssl_session_timeout 5m;
Context: stream, server
@Since: None

Specifies a time during which a client may reuse the session parameters.

[stream] ssl_stapling¶

Syntax: ssl_stapling on | off;
Default: ssl_stapling off;
Context: stream, server
@Since: This directive appeared in version 1.27.2.

Enables or disables stapling of OCSP responses by the server. Example:

[stream] ssl_stapling_file¶

Syntax: ssl_stapling_file file;
Default: —
Context: stream, server
@Since: This directive appeared in version 1.27.2.

When set, the stapled OCSP response will be taken from the specified file instead of querying the OCSP responder specified in the server certificate.

[stream] ssl_stapling_responder¶

Syntax: ssl_stapling_responder url;
Default: —
Context: stream, server
@Since: This directive appeared in version 1.27.2.

Overrides the URL of the OCSP responder specified in the “Authority Information Access” certificate extension.

[stream] ssl_stapling_verify¶

Syntax: ssl_stapling_verify on | off;
Default: ssl_stapling_verify off;
Context: stream, server
@Since: This directive appeared in version 1.27.2.

Enables or disables verification of OCSP responses by the server.

[stream] ssl_trusted_certificate¶

Syntax: ssl_trusted_certificate file;
Default: —
Context: stream, server
@Since: This directive appeared in version 1.11.8.

Specifies a file with trusted CA certificates in the PEM format used to verify client certificates and OCSP responses if ssl_stapling is enabled.

[stream] ssl_verify_client¶

Syntax: ssl_verify_client on | off | optional | optional_no_ca;
Default: ssl_verify_client off;
Context: stream, server
@Since: This directive appeared in version 1.11.8.

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.

[stream] ssl_verify_depth¶

Syntax: ssl_verify_depth number;
Default: ssl_verify_depth 1;
Context: stream, server
@Since: This directive appeared in version 1.11.8.

Sets the verification depth in the client certificates chain.

ngx_stream_ssl_preread_module¶

[stream] ssl_preread¶

Syntax: ssl_preread on | off;
Default: ssl_preread off;
Context: stream, server
@Since: None

Enables extracting information from the ClientHello message at the preread phase.

ngx_stream_upstream_module¶

[upstream] upstream¶

Syntax: upstream name { ... }
Default: —
Context: stream
@Since: None

Defines a group of servers. Servers can listen on different ports. In addition, servers listening on TCP and UNIX-domain sockets can be mixed.

[upstream] server address¶

Syntax: server address [parameters];
Default: —
Context: upstream
@Since: None

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.

[upstream] zone¶

Syntax: zone name [size];
Default: —
Context: upstream
@Since: None

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.

[upstream] state¶

Syntax: state file;
Default: —
Context: upstream
@Since: This directive appeared in version 1.9.7.

Specifies a file that keeps the state of the dynamically configurable group.

[upstream] hash¶

Syntax: hash key [consistent];
Default: —
Context: upstream
@Since: None

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 (1.11.2). Usage example:

[upstream] least_conn¶

Syntax: least_conn;
Default: —
Context: upstream
@Since: None

Specifies that a 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.

[upstream] least_time¶

Syntax: least_time connect | first_byte | last_byte [inflight];
Default: —
Context: upstream
@Since: None

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.

[upstream] random¶

Syntax: random [two [method]];
Default: —
Context: upstream
@Since: This directive appeared in version 1.15.1.

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.

[upstream] resolver address¶

Syntax: resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone];
Default: —
Context: upstream
@Since: This directive appeared in version 1.27.3.

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

[upstream] resolver_timeout time¶

Syntax: resolver_timeout time;
Default: resolver_timeout 30s;
Context: upstream
@Since: This directive appeared in version 1.27.3.

Sets a timeout for name resolution, for example:

ngx_stream_upstream_hc_module¶

[upstream] health_check¶

Syntax: health_check [parameters];
Default: —
Context: server
@Since: None

Enables periodic health checks of the servers in a group.

[upstream] health_check_timeout¶

Syntax: health_check_timeout timeout;
Default: health_check_timeout 5s;
Context: stream, server
@Since: None

Overrides the proxy_timeout value for health checks.

[upstream] match¶

Syntax: match name { ... }
Default: —
Context: stream
@Since: None

Defines the named test set used to verify server responses to health checks.

ngx_stream_zone_sync_module¶

zone_sync¶

Syntax: zone_sync;
Default: —
Context: server
@Since: None

Enables the synchronization of shared memory zones between cluster nodes. Cluster nodes are defined using zone_sync_server directives.

zone_sync_buffers¶

Syntax: zone_sync_buffers number size;
Default: zone_sync_buffers 8 4k|8k;
Context: stream, server
@Since: None

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.

zone_sync_connect_retry_interval¶

Syntax: zone_sync_connect_retry_interval time;
Default: zone_sync_connect_retry_interval 1s;
Context: stream, server
@Since: None

Defines an interval between connection attempts to another cluster node.

zone_sync_connect_timeout¶

Syntax: zone_sync_connect_timeout time;
Default: zone_sync_connect_timeout 5s;
Context: stream, server
@Since: None

Defines a timeout for establishing a connection with another cluster node.

zone_sync_interval¶

Syntax: zone_sync_interval time;
Default: zone_sync_interval 1s;
Context: stream, server
@Since: None

Defines an interval for polling updates in a shared memory zone.

zone_sync_recv_buffer_size¶

Syntax: zone_sync_recv_buffer_size size;
Default: zone_sync_recv_buffer_size 4k|8k;
Context: stream, server
@Since: None

Sets size of a per-connection receive buffer used to parse incoming stream of synchronization messages. The buffer size must be equal or greater than one of the zone_sync_buffers. By default, the buffer size is equal to zone_sync_buffers size multiplied by number.

zone_sync_server¶

Syntax: zone_sync_server address [resolve];
Default: —
Context: server
@Since: None

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.

zone_sync_ssl¶

Syntax: zone_sync_ssl on | off;
Default: zone_sync_ssl off;
Context: stream, server
@Since: None

Enables the SSL/TLS protocol for connections to another cluster server.

zone_sync_ssl_certificate¶

Syntax: zone_sync_ssl_certificate file;
Default: —
Context: stream, server
@Since: None

Specifies a file with the certificate in the PEM format used for authentication to another cluster server.

zone_sync_ssl_certificate_key¶

Syntax: zone_sync_ssl_certificate_key file;
Default: —
Context: stream, server
@Since: None

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

zone_sync_ssl_ciphers¶

Syntax: zone_sync_ssl_ciphers ciphers;
Default: zone_sync_ssl_ciphers DEFAULT;
Context: stream, server
@Since: None

Specifies the enabled ciphers for connections to another cluster server. The ciphers are specified in the format understood by the OpenSSL library.

zone_sync_ssl_conf_command¶

Syntax: zone_sync_ssl_conf_command name value;
Default: —
Context: stream, server
@Since: This directive appeared in version 1.19.4.

Sets arbitrary OpenSSL configuration commands when establishing a connection with another cluster server.

zone_sync_ssl_crl¶

Syntax: zone_sync_ssl_crl file;
Default: —
Context: stream, server
@Since: None

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

zone_sync_ssl_name¶

Syntax: zone_sync_ssl_name name;
Default: zone_sync_ssl_name host from zone_sync_server;
Context: stream, server
@Since: This directive appeared in version 1.15.7.

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

zone_sync_ssl_password_file¶

Syntax: zone_sync_ssl_password_file file;
Default: —
Context: stream, server
@Since: None

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.

zone_sync_ssl_protocols¶

Syntax: zone_sync_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3];
Default: zone_sync_ssl_protocols TLSv1.2 TLSv1.3;
Context: stream, server
@Since: None

Enables the specified protocols for connections to another cluster server.

zone_sync_ssl_server_name¶

Syntax: zone_sync_ssl_server_name on | off;
Default: zone_sync_ssl_server_name off;
Context: stream, server
@Since: This directive appeared in version 1.15.7.

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

zone_sync_ssl_trusted_certificate¶

Syntax: zone_sync_ssl_trusted_certificate file;
Default: —
Context: stream, server
@Since: None

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

zone_sync_ssl_verify¶

Syntax: zone_sync_ssl_verify on | off;
Default: zone_sync_ssl_verify off;
Context: stream, server
@Since: None

Enables or disables verification of another cluster server certificate.

zone_sync_ssl_verify_depth¶

Syntax: zone_sync_ssl_verify_depth number;
Default: zone_sync_ssl_verify_depth 1;
Context: stream, server
@Since: None

Sets the verification depth in another cluster server certificates chain.

zone_sync_timeout¶

Syntax: zone_sync_timeout timeout;
Default: zone_sync_timeout 5s;
Context: stream, server
@Since: None

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.

ngx_google_perftools_module¶

google_perftools_profiles¶

Syntax: google_perftools_profiles file;
Default: —
Context: main
@Since: None

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.

ngx_mgmt_module¶

mgmt¶

Syntax: mgmt { ... }
Default: —
Context: main
@Since: None

Provides the configuration file context in which usage reporting and license management directives are specified.

enforce_initial_report¶

Syntax: enforce_initial_report on | off;
Default: enforce_initial_report on;
Context: mgmt
@Since: This directive appeared in version 1.27.2.

Enables or disables the 180-day grace period for sending the initial usage report.

license_token¶

Syntax: license_token file;
Default: license_token license.jwt;
Context: mgmt
@Since: This directive appeared in version 1.27.2.

Specifies a JWT license file. By default, the license.jwt file is expected to be at /etc/nginx/ for Linux or at /usr/local/etc/nginx/ for FreeBSD.

proxy¶

Syntax: proxy host:port;
Default: —
Context: mgmt
@Since: This directive appeared in version 1.27.4.

Sets the HTTP CONNECT proxy used for sending the usage report.

proxy_username¶

Syntax: proxy_username string;
Default: —
Context: mgmt
@Since: This directive appeared in version 1.27.4.

Sets the user name used for authentication on the proxy.

proxy_password¶

Syntax: proxy_password string;
Default: —
Context: mgmt
@Since: This directive appeared in version 1.27.4.

Sets the password used for authentication on the proxy.

[mgmt] resolver¶

Syntax: resolver address ... [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone];
Default: —
Context: mgmt
@Since: None

Configures name servers used to resolve usage reporting endpoint name. By default, the system resolver is used.

[mgmt] ssl_crl¶

Syntax: ssl_crl file;
Default: —
Context: mgmt
@Since: None

Specifies a file with revoked certificates (CRL) in the PEM format used to verify the certificate of the usage reporting endpoint.

[mgmt] ssl_trusted_certificate¶

Syntax: ssl_trusted_certificate file;
Default: ssl_trusted_certificate system CA bundle;
Context: mgmt
@Since: None

Specifies a file with trusted CA certificates in the PEM format used to verify the certificate of the usage reporting endpoint.

[mgmt] ssl_verify¶

Syntax: ssl_verify on | off;
Default: ssl_verify on;
Context: mgmt
@Since: None

Enables or disables verification of the usage reporting endpoint certificate.

[mgmt] state_path¶

Syntax: state_path path;
Default: —
Context: mgmt
@Since: This directive appeared in version 1.27.2.

Defines a directory for storing state files (nginx-mgmt-*) created by the ngx_mgmt_module module. The default directory for Linux is /var/lib/nginx/state, for FreeBSD is /var/db/nginx/state.

[mgmt] usage_report¶

Syntax: usage_report [endpoint=address] [interval=time];
Default: usage_report endpoint=product.connect.nginx.com interval=1h;
Context: mgmt
@Since: None

Sets the address and port of the usage reporting endpoint. The interval parameter sets an interval between two consecutive reports.

ngx_otel_module¶

otel_exporter¶

Syntax: otel_exporter { ... }
Default: —
Context: http
@Since: None

Specifies OTel data export parameters:

otel_service_name¶

Syntax: otel_service_name name;
Default: otel_service_name unknown_service:nginx;
Context: http
@Since: None

Sets the “service.name” attribute of the OTel resource.

otel_resource_attr¶

Syntax: otel_resource_attr name value;
Default: —
Context: http
@Since: This directive appeared in version 0.1.2.

Sets a custom OTel resource attribute.

otel_trace¶

Syntax: otel_trace on | off | $variable;
Default: otel_trace off;
Context: http, server, location
@Since: None

Enables or disables OpenTelemetry tracing. The directive can also be enabled by specifying a variable:

otel_trace_context¶

Syntax: otel_trace_context extract | inject | propagate | ignore;
Default: otel_trace_context ignore;
Context: http, server, location
@Since: None

Specifies how to propagate traceparent/tracestate headers:

otel_span_name¶

Syntax: otel_span_name name;
Default: —
Context: http, server, location
@Since: None

Defines the name of the OTel span. By default, it is a name of the location for a request. The name can contain variables.

otel_span_attr¶

Syntax: otel_span_attr name value;
Default: —
Context: http, server, location
@Since: None

Adds a custom OTel span attribute. The value can contain variables.