.\" $OpenBSD: nginx.conf.5,v 1.8 2014/01/27 12:43:58 jmc Exp $ .\" .\" Copyright (C) 2002-2012 Igor Sysoev .\" Copyright (C) 2011-2013 Nginx, Inc. .\" Copyright (C) 2013 Florian Obser .\" Copyright (C) 2013 Ingo Schwarze .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd $Mdocdate: January 27 2014 $ .Dt NGINX.CONF 5 .Os .Sh NAME .Nm nginx.conf .Nd nginx daemon configuration file .Sh DESCRIPTION .Xr nginx 8 .Pq pronounced Dq engine x is an HTTP and reverse proxy server, as well as a mail proxy server. It is known for its high performance, stability, rich feature set, simple configuration, and low resource consumption. .Pp The configuration file consists of a list of configuration directives: .Bd -ragged -offset indent .Ar list .Li ::= .Op Ar directive .Op Ar opt-ws .Op Ar list .Ed .Pp Lists may be empty, they may contain leading and trailing whitespace and comments, and they may contain whitespace and comments between directives. Such whitespace is semantically insignificant. .Pp The syntax of a configuration directive is: .Bd -ragged -offset indent .Ar directive .Li ::= .Ar keyword .Ar ws .Ar arguments .Op Ar ws .Qq Li \&; .Li \&| .Ar context .Ed .Pp In this case, whitespace is required to separate the keyword from the arguments. A context may not be followed by a semicolon, but after every other directive, a semicolon is required, even at the end of a list. .Pp As a special cases of a configuration directive, the syntax of a configuration context is: .Bd -ragged -offset indent .Ar context .Li ::= .Ar keyword .Op Ar ws .Qq Li \&{ .Op Ar list .Qq Li \&} .Ed .Pp Contexts may be nested, and they freely intermix with other directives on each nesting level. .Pp The syntax of whitespace is: .Bd -ragged -offset indent .Ar ws .Li ::= .Ar ws-char .Op Ar opt-ws .Ed .Bd -ragged -offset indent .Ar ws-char .Li ::= .Aq space .Li \&| .Aq tab .Li \&| .Aq newline .Ed .Bd -ragged -offset indent .Ar opt-ws .Li ::= .Pq Ar comment | ws-char .Op Ar opt-ws .Ed .Bd -ragged -offset indent .Ar comment .Li ::= .Qq # .Op Ao non-newline character Ac ... .Aq newline .Ed .Pp Comments start with a hash character and extend to the end of the line. They can start at the beginning of a line, after the semicolon or closing brace at the end of a directive, or after any whitespace character, even in the middle of a directive. .Pp In the following, all keywords are listed, and their arguments are explained. .Ss Core functionality .Bl -tag -width Ds .It Ic accept_mutex Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic events .El .Pp If .Ic 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. The use of .Cm rtsig connection processing method requires .Ic accept_mutex to be enabled. .It Ic accept_mutex_delay Ar time .Bl -tag -width Ds -compact .It default: 500ms .It context: Ic events .El .Pp If .Ic 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. .It Ic daemon Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: main .El .Pp Determines whether nginx should become a daemon. Mainly used during development. .It Ic debug_connection Ar address | Ar CIDR | Cm unix: .Bl -tag -width Ds -compact .It default: .It context: Ic events .El .Pp Enables debugging log for selected client connections. Other connections will use logging level set by the .Ic 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 .Cm unix: parameter. .Bd -literal -offset indent 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:; ... } .Ed .Pp For this directive to work, nginx needs to be built with .Fl -with-debug . .It Ic debug_points Cm abort | Cm stop .Bl -tag -width Ds -compact .It default: .It context: main .El .Pp This directive is used for debugging. When internal error is detected, e.g. the leak of sockets on restart of working processes, enabling .Ic debug_points leads to a core file creation .Pq Cm abort or to stopping of a process .Pq Cm stop for further analysis using a system debugger. .It Ic error_log Ar file | Cm stderr | Cm syslog Ns : Ns Cm server Ns = Ns Ar address Oo , Ar parameter Ns = Ns Ar value Oc Oo Cm debug | Cm info | Cm notice | Cm warn | Cm error | Cm crit | Cm alert | Cm emerg Oc .Bl -tag -width Ds -compact .It default: Pa logs/error.log Cm error .It context: main , Ic http , Ic server , Ic location .El .Pp Configures logging. Several logs can be specified on the same level (1.5.2). The first parameter defines a file that will store the log. The special value .Cm stderr selects the standard error file. Logging to syslog can be configured by specifying the .Cm syslog: prefix. The second parameter determines the level of logging. 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 .Cm error will cause .Cm error , .Cm crit , .Cm alert , and .Cm emerg messages to be logged. If this parameter is omitted then .Cm error is used. For .Cm debug logging to work, nginx needs to be built with .Fl -with-debug . The following parameters configure logging to syslog: .Bl -tag -width Ds .It Cm server Ns = Ns Ar address Defines an address of a syslog server. An address can be specified as a domain name or IP address, and an optional port, or as a UNIX-domain socket path specified after the .Cm unix: prefix. If port is not specified, the port 514 is used. If a domain name resolves to several IP addresses, the first resolved address is used. .It Cm facility Ns = Ns Ar string Sets facility of syslog messages, as defined in RFC 3164. Facility can be one of .Cm kern , .Cm user , .Cm mail , .Cm daemon , .Cm auth , .Cm intern , .Cm lpr , .Cm news , .Cm uucp , .Cm clock , .Cm authpriv , .Cm ftp , .Cm ntp , .Cm audit , .Cm alert , .Cm cron , .Cm local0 No .. Cm local7 . Default is .Cm local7 . .It Cm tag Ns = Ns Ar string Sets tag of syslog messages. Default is .Qq nginx . .El .Pp Example syslog configuration: .Bd -literal -offset indent error_log syslog:server=192.168.1.1 debug; error_log syslog:server=unix:/var/log/nginx.sock; error_log syslog:server=[2001:db8::1]:12345,facility=local7,tag=nginx error; .Ed .It Ic env Ar variable Ns Oo = Ns Ar value Oc .Bl -tag -width Ds -compact .It default: Ev TZ .It context: main .El .Pp By default, nginx removes all environment variables inherited from its parent process except the .Ev TZ variable. This directive allows preserving some of the inherited variables, changing their values, or creating new environment variables. These variables are then: .Bl -bullet .It inherited during a live upgrade of an executable file; .It used by the .Sx Module ngx_http_perl_module module; .It 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. .El .Pp The .Ev TZ variable is always inherited and available to the .Sx Module ngx_http_perl_module module, unless it is configured explicitly. Usage example: .Bd -literal -offset indent env MALLOC_OPTIONS; env PERL5LIB=/data/site/modules; env OPENSSL_ALLOW_PROXY_CERTS=1; .Ed .Pp The .Ev NGINX environment variable is used internally by nginx and should not be set directly by the user. .It Ic events Brq No ... .Bl -tag -width Ds -compact .It default: .It context: main .El .Pp Provides the configuration file context in which the directives that affect connection processing are specified. .It Ic include Ar file | Ar mask .Bl -tag -width Ds -compact .It default: .It context: any .El .Pp Includes another .Ar file , or files matching the specified .Ar mask , into configuration. Included files should consist of syntactically correct directives and blocks. Usage example: .Bd -literal -offset indent include mime.types; include vhosts/*.conf; .Ed .It Ic lock_file Ar file .Bl -tag -width Ds -compact .It default: Pa logs/nginx.lock .It context: main .El .Pp nginx uses the locking mechanism to implement .Ic 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. .It Ic master_process Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: main .El .Pp Determines whether worker processes are started. This directive is intended for nginx developers. .It Ic multi_accept Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic events .El .Pp If .Ic 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 .Cm kqueue connection processing method is used, because it reports the number of new connections waiting to be accepted. The use of .Cm rtsig connection processing method automatically enables .Ic multi_accept . .It Ic pcre_jit Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: main .El .Pp 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 .Fl -enable-jit configuration parameter. When the PCRE library is built with nginx .Pq Fl -with-pcre Ns = Ns , the JIT support is enabled via the .Fl -with-pcre-jit configuration parameter. .It Ic pid Ar file .Bl -tag -width Ds -compact .It default: Pa nginx.pid .It context: main .El .Pp Defines a .Ar file that will store the process ID of the main process. .It Ic ssl_engine Ar device .Bl -tag -width Ds -compact .It default: .It context: main .El .Pp Defines the name of the hardware SSL accelerator. .It Ic timer_resolution Ar interval .Bl -tag -width Ds -compact .It default: .It context: main .El .Pp Reduces timer resolution in worker processes, thus reducing the number of .Fn gettimeofday system calls made. By default, .Fn gettimeofday is called each time a kernel event is received. With reduced resolution, .Fn gettimeofday is only called once per specified .Ar interval . Example: .Bd -literal -offset indent timer_resolution 100ms; .Ed .Pp Internal implementation of the interval depends on the method used: .Bl -bullet .It the .Dv EVFILT_TIMER filter if .Cm kqueue is used; .It .Fn timer_create if .Cm eventport is used; .It .Fn setitimer otherwise. .El .It Ic use Ar method .Bl -tag -width Ds -compact .It default: .It context: Ic events .El .Pp Specifies the connection processing .Ar method to use. There is normally no need to specify it explicitly, because nginx will by default use the most efficient method. .It Ic user Ar user Oo Ar group Oc .Bl -tag -width Ds -compact .It default: nobody nobody .It context: main .El .Pp Defines .Ar user and .Ar group credentials used by worker processes. If .Ar group is omitted, a group whose name equals that of .Ar user is used. .It Ic worker_aio_requests Ar number .Bl -tag -width Ds -compact .It default: 32 .It context: Ic events .El .Pp When using .Ic aio with the .Cm epoll connection processing method, sets the maximum .Ar number of outstanding asynchronous I/O operations for a single worker process. .It Ic worker_connections Ar number .Bl -tag -width Ds -compact .It default: 512 .It context: Ic events .El .Pp 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 .Ic worker_rlimit_nofile . .It Ic worker_cpu_affinity Ar cpumask No ... .Bl -tag -width Ds -compact .It default: .It context: main .El .Pp 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, .Bd -literal -offset indent worker_processes 4; worker_cpu_affinity 0001 0010 0100 1000; .Ed .Pp binds each worker process to a separate CPU, while .Bd -literal -offset indent worker_processes 2; worker_cpu_affinity 0101 1010; .Ed .Pp 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 directive is only available on FreeBSD and Linux. .It Ic worker_priority Ar number .Bl -tag -width Ds -compact .It default: 0 .It context: main .El .Pp Defines the scheduling priority for worker processes like it is done by the .Ic nice command: a negative .Ar number means higher priority. Allowed range normally varies from -20 to 20. Example: .Bd -literal -offset indent worker_priority -10; .Ed .It Ic worker_processes Ar number | Cm auto .Bl -tag -width Ds -compact .It default: 1 .It context: main .El .Pp 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 .Cm auto will try to autodetect it). The .Cm auto parameter is supported starting from versions 1.3.8 and 1.2.5. .It Ic worker_rlimit_core Ar size .Bl -tag -width Ds -compact .It default: .It context: main .El .Pp Changes the limit on the largest size of a core file .Pq Dv RLIMIT_CORE for worker processes. Used to increase the limit without restarting the main process. .It Ic worker_rlimit_nofile Ar number .Bl -tag -width Ds -compact .It default: .It context: main .El .Pp Changes the limit on the maximum number of open files .Pq Dv RLIMIT_NOFILE for worker processes. Used to increase the limit without restarting the main process. .It Ic worker_rlimit_sigpending Ar number .Bl -tag -width Ds -compact .It default: .It context: main .El .Pp On systems that support .Cm rtsig connection processing method, changes the limit on the number of signals that may be queued .Pq Dv RLIMIT_SIGPENDING for worker processes. Used to increase the limit without restarting the main process. .It Ic working_directory Ar directory .Bl -tag -width Ds -compact .It default: .It context: main .El .Pp 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. .El .Ss Module ngx_http_core_module .Bl -tag -width Ds .It Ic aio Cm on | Cm off | Cm sendfile .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables the use of asynchronous file I/O (AIO) on FreeBSD and Linux. On FreeBSD, AIO can be used starting from FreeBSD 4.3. AIO can either be linked statically into a kernel: .Bd -literal -offset indent options VFS_AIO .Ed .Pp or loaded dynamically as a kernel loadable module: .Bd -literal -offset indent kldload aio .Ed .Pp In FreeBSD versions 5 and 6, enabling AIO statically, or dynamically when booting the kernel, will cause the entire networking subsystem to use the Giant lock, which can impact overall performance negatively. This limitation has been removed in FreeBSD 6.4-STABLE in 2009, and in FreeBSD 7. However, starting from FreeBSD 5.3 it is possible to enable AIO without the penalty of running the networking subsystem under a Giant lock-for this to work, the AIO module needs to be loaded after the kernel has booted. In this case, the following message will appear in .Pa /var/log/messages .Bd -literal -offset indent WARNING: Network stack Giant-free, but aio requires Giant. Consider adding 'options NET_WITH_GIANT' or setting debug.mpsafenet=0 .Ed .Pp and can safely be ignored. The requirement to use the Giant lock with AIO is related to the fact that FreeBSD supports asynchronous calls .Fn aio_read and .Fn aio_write when working with sockets. However, since nginx uses AIO only for disk I/O, no problems should arise. For AIO to work, .Ic sendfile needs to be disabled: .Bd -literal -offset indent location /video/ { sendfile off; aio on; output_buffers 1 64k; } .Ed .Pp In addition, starting from FreeBSD 5.2.1 and nginx 0.8.12, AIO can also be used to pre-load data for .Fn sendfile : .Bd -literal -offset indent location /video/ { sendfile on; tcp_nopush on; aio sendfile; } .Ed .Pp In this configuration, .Fn sendfile is called with the .Dv 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 .Ic read_ahead directive. On Linux, AIO can be used starting from kernel version 2.6.22. Also, it is necessary to enable .Ic directio , or otherwise reading will be blocking: .Bd -literal -offset indent location /video/ { aio on; directio 512; output_buffers 1 128k; } .Ed .Pp On Linux, .Ic 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. There is no need to turn off .Ic sendfile explicitly, as it is turned off automatically when .Ic directio is used. .It Ic alias Ar path .Bl -tag -width Ds -compact .It default: .It context: Ic location .El .Pp Defines a replacement for the specified location. For example, with the following configuration .Bd -literal -offset indent location /i/ { alias /data/w3/images/; } .Ed .Pp on request of .Pa /i/top.gif , the file .Pa /data/w3/images/top.gif will be sent. The .Ar path value can contain variables, except .Va $document_root and .Va $realpath_root . If .Ic alias is used inside a location defined with a regular expression then such regular expression should contain captures and .Ic alias should refer to these captures (0.7.40), for example: .Bd -literal -offset indent location ~ ^/users/(.+\\.(?:gif |jpe?g |png))$ { alias /data/w3/images/$1; } .Ed .Pp When location matches the last part of the directive's value: .Bd -literal -offset indent location /images/ { alias /data/w3/images/; } .Ed .Pp it is better to use the .Ic root directive instead: .Bd -literal -offset indent location /images/ { root /data/w3; } .Ed .It Ic chunked_transfer_encoding Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp 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. .It Ic client_body_buffer_size Ar size .Bl -tag -width Ds -compact .It default: 8k | 16k .It context: Ic http , Ic server , Ic location .El .Pp 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 .Ic client_body_temp_path 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. .It Ic client_body_in_file_only Cm on | Cm clean | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Determines whether nginx should save the entire client request body into a file. This directive can be used during debugging, or when using the .Va $request_body_file variable, or the methods .Ic $r->request_body_file method of the module .Sx Module ngx_http_perl_module . When set to the value .Cm on , temporary files are not removed after request processing. The value .Cm clean will cause the temporary files left after request processing to be removed. .It Ic client_body_in_single_buffer Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Determines whether nginx should save the entire client request body in a single buffer. The directive is recommended when using the .Va $request_body variable, to save the number of copy operations involved. .It Ic client_body_temp_path Ar path Oo Ar level1 Oo Ar level2 Oo Ar level3 Oc Oc Oc .Bl -tag -width Ds -compact .It default: client_body_temp .It context: Ic http , Ic server , Ic location .El .Pp 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 .Bd -literal -offset indent client_body_temp_path /spool/nginx/client_temp 1 2; .Ed .Pp a path to a temporary file might look like this: .Pa /spool/nginx/client_temp/7/45/00000123457 .It Ic client_body_timeout Ar time .Bl -tag -width Ds -compact .It default: 60s .It context: Ic http , Ic server , Ic location .El .Pp Defines a timeout for reading client request body. The timeout is set only for a period between two successive read operations, not for the transmission of the whole request body. If a client does not transmit anything within this time, the 408 (Request Time-out) error is returned to the client. .It Ic client_header_buffer_size Ar size .Bl -tag -width Ds -compact .It default: 1k .It context: Ic http , Ic server .El .Pp 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 .Ic large_client_header_buffers directive, are allocated. .It Ic client_header_timeout Ar time .Bl -tag -width Ds -compact .It default: 60s .It context: Ic http , Ic server .El .Pp Defines a timeout for reading client request header. If a client does not transmit the entire header within this time, the 408 (Request Time-out) error is returned to the client. .It Ic client_max_body_size Ar size .Bl -tag -width Ds -compact .It default: 1m .It context: Ic http , Ic server , Ic location .El .Pp Sets the maximum allowed size of the client request body, specified in the Content-Length request header field. If the size in a request exceeds the configured value, the 413 (Request Entity Too Large) error is returned to the client. Please be aware that browsers cannot correctly display this error. Setting .Ar size to 0 disables checking of client request body size. .It Ic connection_pool_size Ar size .Bl -tag -width Ds -compact .It default: 256 .It context: Ic http , Ic server .El .Pp Allows accurate tuning of per-connection memory allocations. This directive has minimal impact on performance and should not generally be used. .It Ic default_type Ar mime-type .Bl -tag -width Ds -compact .It default: text/plain .It context: Ic http , Ic server , Ic location .El .Pp Defines the default MIME type of a response. Mapping of file name extensions to MIME types can be set with the .Ic types directive. .It Ic directio Ar size | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables the use of the .Dv O_DIRECT flag (FreeBSD, Linux), the .Dv F_NOCACHE flag (Mac OS X), or the .Fn directio function (Solaris), when reading files that are larger than or equal to the specified .Ar size . The directive automatically disables (0.7.15) the use of .Ic sendfile for a given request. It can be useful for serving large files: .Bd -literal -offset indent directio 4m; .Ed .Pp or when using .Ic aio on Linux. .It Ic directio_alignment Ar size .Bl -tag -width Ds -compact .It default: 512 .It context: Ic http , Ic server , Ic location .El .Pp Sets the alignment for .Ic directio . In most cases, a 512-byte alignment is enough. However, when using XFS under Linux, it needs to be increased to 4K. .It Ic disable_symlinks Cm off .It Ic disable_symlinks Cm on | Cm if_not_owner Oo Cm from Ns = Ns Ar part Oc .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Determines how symbolic links should be treated when opening files: .Bl -tag -width Ds .It Cm off Symbolic links in the pathname are allowed and not checked. This is the default behavior. .It Cm on If any component of the pathname is a symbolic link, access to a file is denied. .It Cm 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. .It Cm from Ns = Ns Ar part When checking symbolic links (parameters .Cm on and .Cm 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 .Cm from Ns = Ns Ar 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. .El .Pp Example: .Bd -literal -offset indent disable_symlinks on from=$document_root; .Ed .Pp This directive is only available on systems that have the .Fn openat and .Fn fstatat interfaces. Such systems include modern versions of FreeBSD, Linux, and Solaris. Parameters .Cm on and .Cm if_not_owner add a processing overhead. On systems that do not support opening of directories only for search, to use these parameters it is required that worker processes have read permissions for all directories being checked. The .Sx Module ngx_http_autoindex_module , .Sx Module ngx_http_random_index_module , and .Sx Module ngx_http_dav_module modules currently ignore this directive. .It Ic error_page Ar code No ... Oo = Ns Oo Ar response Oc Oc Ar uri .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location , Ic if in location .El .Pp Defines the URI that will be shown for the specified errors. .Ic error_page directives are inherited from the previous level only if there are no .Ic error_page directives defined on the current level. A .Ar uri value can contain variables. Example: .Bd -literal -offset indent error_page 404 /404.html; error_page 500 502 503 504 /50x.html; .Ed .Pp Furthermore, it is possible to change the response code to another using the .Ar =response syntax, for example: .Bd -literal -offset indent error_page 404 =200 /empty.gif; .Ed .Pp If an error response is processed by a proxied server or a FastCGI 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: .Bd -literal -offset indent error_page 404 = /404.php; .Ed .Pp It is also possible to use redirects for error processing: .Bd -literal -offset indent error_page 403 http://example.com/forbidden.html; error_page 404 =301 http://example.com/notfound.html; .Ed .Pp 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, and 307). If there is no need to change URI during internal redirection it is possible to pass error processing into a named location: .Bd -literal -offset indent location / { error_page 404 = @fallback; } location @fallback { proxy_pass http://backend; } .Ed .Pp If .Ar uri processing leads to an error, the status code of the last occurred error is returned to the client. .It Ic etag Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables automatic generation of the ETag response header field for static resources. .It Ic http Brq No ... .Bl -tag -width Ds -compact .It default: .It context: main .El .Pp Provides the configuration file context in which the HTTP server directives are specified. .It Ic if_modified_since Cm off | Cm exact | Cm before .Bl -tag -width Ds -compact .It default: Cm exact .It context: Ic http , Ic server , Ic location .El .Pp Specifies how to compare modification time of a response with the time in the If-Modified-Since request header field: .Bl -tag -width Ds .It Cm off the If-Modified-Since request header field is ignored (0.7.34); .It Cm exact exact match; .It Cm before modification time of a response is less than or equal to the time in the If-Modified-Since request header field. .El .It Ic ignore_invalid_headers Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server .El .Pp 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 .Ic underscores_in_headers directive). A directive can be specified on the .Ic server level in the default server. In this case, its value will cover all virtual servers listening on the same address and port. .It Ic internal .Bl -tag -width Ds -compact .It default: .It context: Ic location .El .Pp 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: .Bl -bullet .It requests redirected by the .Ic error_page , .Ic index , .Ic random_index , and .Ic try_files directives; .It requests redirected by the X-Accel-Redirect response header field from an upstream server; .It subrequests formed by the .Ic include virtual command of the .Sx Module ngx_http_ssi_module module and by the .Sx Module ngx_http_addition_module module directives; .It requests changed by the .Ic rewrite directive. .El .Pp Example: .Bd -literal -offset indent error_page 404 /404.html; location /404.html { internal; } .Ed .Pp 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. .It Ic keepalive_disable Cm none | Ar browser No ... .Bl -tag -width Ds -compact .It default: Cm msie6 .It context: Ic http , Ic server , Ic location .El .Pp Disables keep-alive connections with misbehaving browsers. The .Ar browser parameters specify which browsers will be affected. The value .Cm msie6 disables keep-alive connections with old versions of MSIE, once a POST request is received. The value .Cm safari disables keep-alive connections with Safari and Safari-like browsers on Mac OS X and Mac OS X-like operating systems. The value .Cm none enables keep-alive connections with all browsers. Prior to version 1.1.18, the value .Cm safari matched all Safari and Safari-like browsers on all operating systems, and keep-alive connections with them were disabled by default. .It Ic keepalive_requests Ar number .Bl -tag -width Ds -compact .It default: 100 .It context: Ic http , Ic server , Ic location .El .Pp 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. .It Ic keepalive_timeout Ar timeout Oo Ar header_timeout Oc .Bl -tag -width Ds -compact .It default: 75s .It context: Ic http , Ic server , Ic location .El .Pp 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. .It Ic large_client_header_buffers Ar number Ar size .Bl -tag -width Ds -compact .It default: 4 8k .It context: Ic http , Ic server .El .Pp Sets the maximum .Ar number and .Ar 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. .It Ic limit_except Ar method No ... Brq No ... .Bl -tag -width Ds -compact .It default: .It context: Ic location .El .Pp Limits allowed HTTP methods inside a location. The .Ar method parameter can be one of the following: .Cm GET , .Cm HEAD , .Cm POST , .Cm PUT , .Cm DELETE , .Cm MKCOL , .Cm COPY , .Cm MOVE , .Cm OPTIONS , .Cm PROPFIND , .Cm PROPPATCH , .Cm LOCK , .Cm UNLOCK , or .Cm PATCH. Allowing the .Cm GET method makes the .Cm HEAD method also allowed. Access to other methods can be limited using the .Sx Module ngx_http_access_module and .Sx Module ngx_http_auth_basic_module modules directives: .Bd -literal -offset indent limit_except GET { allow 192.168.1.0/32; deny all; } .Ed .Pp Please note that this will limit access to all methods except .Cm GET and .Cm HEAD . .It Ic limit_rate Ar rate .Bl -tag -width Ds -compact .It default: 0 .It context: Ic http , Ic server , Ic location , Ic if in location .El .Pp Limits the rate of response transmission to a client. The .Ar rate is specified in bytes per second. The zero value disables rate limiting. The limit is set per a request, and so if a client simultaneously opens two connections, the overall rate will be twice as much as the specified limit. Rate limit can also be set in the .Va $limit_rate variable. It may be useful in cases where rate should be limited depending on a certain condition: .Bd -literal -offset indent server { if ($slow) { set $limit_rate 4k; } ... } .Ed .Pp 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 .Ic proxy_ignore_headers and .Ic fastcgi_ignore_headers directives. .It Ic limit_rate_after Ar size .Bl -tag -width Ds -compact .It default: 0 .It context: Ic http , Ic server , Ic location , Ic if in location .El .Pp Sets the initial amount after which the further transmission of a response to a client will be rate limited. Example: .Bd -literal -offset indent location /flv/ { flv; limit_rate_after 500k; limit_rate 50k; } .Ed .It Ic lingering_close Cm off | Cm on | Cm always .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp Controls how nginx closes client connections. The default value .Cm on instructs nginx to .Ic lingering_timeout wait for and .Ic lingering_time 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 .Cm always will cause nginx to unconditionally wait for and process additional client data. The value .Cm 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. .It Ic lingering_time Ar time .Bl -tag -width Ds -compact .It default: 30s .It context: Ic http , Ic server , Ic location .El .Pp When .Ic 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. .It Ic lingering_timeout Ar time .Bl -tag -width Ds -compact .It default: 5s .It context: Ic http , Ic server , Ic location .El .Pp When .Ic 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 .Ic lingering_time directive. .It Ic listen Ar address Ns Oo : Ns Ar port Oc Oo Cm default_server Oc \ Oo Cm ssl Oc Oo Cm spdy Oc Oo Cm setfib Ns = Ns Ar number Oc \ Oo Cm backlog Ns = Ns Ar number Oc Oo Cm rcvbuf Ns = Ns Ar size Oc \ Oo Cm sndbuf Ns = Ns Ar size Oc \ Oo Cm accept_filter Ns = Ns Ar filter Oc \ Oo Cm deferred Oc Oo Cm bind Oc \ Oo Cm ipv6only Ns = Ns Cm on | Cm off Oc \ Oo Cm so_keepalive Ns = Ns Cm on | Cm off | \ Oo Ar keepidle Ns Oc : Ns Oo Ar keepintvl Oc : Ns Oo Ar keepcnt Oc Oc .It Ic listen Ar port Oo Cm default_server Oc Oo Cm ssl Oc \ Oo Cm spdy Oc Oo Cm setfib Ns = Ns Ar number Oc \ Oo Cm backlog Ns = Ns Ar number Oc Oo Cm rcvbuf Ns = Ns Ar size Oc \ Oo Cm sndbuf Ns = Ns Ar size Oc \ Oo Cm accept_filter Ns = Ns Ar filter Oc \ Oo Cm deferred Oc Oo Cm bind Oc \ Oo Cm ipv6only Ns = Ns Cm on | Cm off Oc \ Oo Cm so_keepalive Ns = Ns Cm on | Cm off | \ Oo Ar keepidle Oc : Ns Oo Ar keepintvl Oc : Ns Oo Ar keepcnt Oc Oc .It Ic listen Cm unix : Ns Ar path Oo Cm default_server Oc \ Oo Cm ssl Oc Oo Cm spdy Oc Oo Cm backlog Ns = Ns Ar number Oc \ Oo Cm rcvbuf Ns = Ns Ar size Oc \ Oo Cm sndbuf Ns = Ns Ar size Oc \ Oo Cm accept_filter Ns = Ns Ar filter Oc \ Oo Cm deferred Oc Oo Cm bind Oc \ Oo Cm so_keepalive Ns = Ns Cm on | Cm off | \ Oo Ar keepidle Oc : Ns Oo Ar keepintvl Oc : Ns Oo Ar keepcnt Oc Oc .Pp .Bl -tag -width Ds -compact .It default: *:80 | *:8000 .It context: Ic server .El .Pp Sets the .Ar address and .Ar port for IP, or the .Ar path for a UNIX-domain socket on which the server will accept requests. Both .Ar address and .Ar port , or only .Ar address or only .Ar port can be specified. An .Ar address may also be a hostname, for example: .Bd -literal -offset indent listen 127.0.0.1:8000; listen 127.0.0.1; listen 8000; listen *:8000; listen localhost:8000; .Ed .Pp IPv6 addresses (0.7.36) are specified in square brackets: .Bd -literal -offset indent listen [::]:8000; listen [::1]; .Ed .Pp UNIX-domain sockets (0.8.21) are specified with the .Cm unix: prefix: .Bd -literal -offset indent listen unix:/var/run/nginx.sock; .Ed .Pp If only .Ar address is given, the port 80 is used. If the directive is not present then either .Ic *:80 is used if nginx runs with the superuser privileges, or .Ic *:8000 otherwise. The .Cm default_server parameter, if present, will cause the server to become the default server for the specified .Ar address Ns : Ns Ar port pair. If none of the directives have the .Cm default_server parameter then the first server with the .Ar address Ns : Ns Ar port pair will be the default server for this pair. In versions prior to 0.8.21 this parameter is named simply .Cm default . The .Ar 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 .Cm spdy parameter (1.3.15) allows accepting SPDY connections on this port. Normally, for this to work the .Ar ssl parameter should be specified as well, but nginx can also be configured to accept SPDY connections without SSL. A .Ic listen directive can have several additional parameters specific to socket-related system calls. These parameters can be specified in any .Ic listen directive, but only once for a given .Ar address Ns : Ns Ar port pair. In versions prior to 0.8.21, they could only be specified in the .Ic listen directive together with the .Cm default parameter. .Bl -tag -width Ds .It Cm setfib Ns = Ns Ar number this parameter (0.8.44) sets the associated routing table, FIB (the .Dv SO_SETFIB option) for the listening socket. This currently works only on FreeBSD. .It Cm backlog Ns = Ns Ar number sets the .Cm backlog parameter in the .Fn listen call that limits the maximum length for the queue of pending connections. By default, .Cm backlog is set to -1 on FreeBSD and Mac OS X, and to 511 on other platforms. .It Cm rcvbuf Ns = Ns Ar size sets the receive buffer size (the .Dv SO_RCVBUF option) for the listening socket. .It Cm sndbuf Ns = Ns Ar size sets the send buffer size (the .Dv SO_SNDBUF option) for the listening socket. .It Cm accept_filter Ns = Ns Ar filter sets the name of accept filter (the .Dv SO_ACCEPTFILTER option) for the listening socket that filters incoming connections before passing them to .Fn accept . This works only on FreeBSD and NetBSD_5.0+. Possible values are .Cm dataready and .Cm httpready . .It Cm deferred instructs to use a deferred .Fn accept (the .Dv TCP_DEFER_ACCEPT socket option) on Linux. .It Cm bind instructs to make a separate .Fn bind call for a given .Ar address Ns : Ns Ar port pair. This is useful because if there are several .Ic listen directives with the same port but different addresses, and one of the .Ic listen directives listens on all addresses for the given port .Pq * Ns : Ns Ar port , nginx will .Fn bind only to .Qq * Ns : Ns Ar port . It should be noted that the .Fn getsockname system call will be made in this case to determine the address that accepted the connection. If the .Cm backlog , .Cm rcvbuf , .Cm sndbuf , .Cm accept_filter , .Cm deferred , or .Cm so_keepalive parameters are used then for a given .Ar address Ns : Ar port pair a separate .Fn bind call will always be made. .It Cm ipv6only Ns = Ns Cm on | Cm off this parameter (0.7.42) determines (via the .Dv IPV6_V6ONLY socket option) whether an IPv6 socket listening on a wildcard address .Op :: 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. .It Cm so_keepalive Ns = Ns Cm on | Cm off | \ Oo Ar keepidle Oc : Ns Oo Ar keepintvl Oc : Ns Oo Ar keepcnt Oc 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 .Cm on , the .Dv SO_KEEPALIVE option is turned on for the socket. If it is set to the value .Cm off , the .Dv 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 .Dv TCP_KEEPIDLE , .Dv TCP_KEEPINTVL , and .Dv TCP_KEEPCNT socket options. On such systems (currently, Linux_2.4+, NetBSD_5+, and FreeBSD_9.0-STABLE), they can be configured using the .Ar keepidle , .Ar keepintvl , and .Ar 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, .Bd -literal -offset indent so_keepalive=30m::10 .Ed .Pp will set the idle timeout .Pq Dv TCP_KEEPIDLE to 30 minutes, leave the probe interval .Pq Dv TCP_KEEPINTVL at its system default, and set the probes count .Pq Dv TCP_KEEPCNT to 10 probes. .El .Pp Example: .Bd -literal -offset indent listen 127.0.0.1 default_server accept_filter=dataready backlog=1024; .Ed .It Ic location Oo Cm = | Cm ~ | Cm ~* | Cm ^~ Oc Ar uri Brq No ... .It Ic location Cm @ Ar name Brq No ... .Bl -tag -width Ds -compact .It default: .It context: Ic server , Ic location .El .Pp Sets configuration depending on a request URI. The matching is performed against a normalized URI, after decoding the text encoded in the .Qq %XX form, resolving references to relative path components .Qo . Qc and .Qq .. , and possible .Ic merge_slashes 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 .Qq ~* modifier (for case-insensitive matching), or the .Qq ~ 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. .Ic location blocks can be nested, with some exceptions mentioned below. For case-insensitive operating systems such as Mac OS X 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 .Qq ^~ modifier then regular expressions are not checked. Also, using the .Cm = 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 .Qq location=/ will speed up the processing of these requests, as search terminates right after the first comparison. Such a location cannot obviously contain nested locations. In versions from 0.7.1 to 0.8.41, if a request matched the prefix location without the .Qq = and .Qq ^~ modifiers, the search also terminated and regular expressions were not checked. Let's illustrate the above by an example: .Bd -literal -offset indent location = / { [ configuration A ] } location / { [ configuration B ] } location /documents/ { [ configuration C ] } location ^~ /images/ { [ configuration D ] } location ~* \\.(gif |jpg |jpeg)$ { [ configuration E ] } .Ed .Pp The .Qq / request will match configuration A, the .Qq /index.html request will match configuration B, the .Qq /documents/document.html request will match configuration C, the .Qq /images/1.gif request will match configuration D, and the .Qq /documents/1.jpg request will match configuration E. The .Cm @ 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 .Ic proxy_pass , .Ic fastcgi_pass , .Ic scgi_pass , .Ic uwsgi_pass , or .Ic memcached_pass , then 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: .Bd -literal -offset indent location /user/ { proxy_pass http://user.example.com; } location = /user { proxy_pass http://login.example.com; } .Ed .It Ic log_not_found Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables logging of errors about not found files into .Ic error_log . .It Ic log_subrequest Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables logging of subrequests into .Ic access_log . .It Ic max_ranges Ar number .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp 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. .It Ic merge_slashes Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server .El .Pp 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 .Qq //scripts/one.php request would not match .Bd -literal -offset indent location /scripts/ { ... } .Ed .Pp and might be processed as a static file. So it gets converted to .Qq /scripts/one.php . Turning the compression .Cm off can become necessary if a URI contains base64-encoded names, since base64 uses the .Qq / character internally. However, for security considerations, it is better to avoid turning the compression off. A directive can be specified on the .Ic server level in the default server. In this case, its value will apply to all virtual servers listening on the same address and port. .It Ic msie_padding Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables adding comments to responses for MSIE clients with status greater than 400 to increase the response size to 512 bytes. .It Ic msie_refresh Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables issuing refreshes instead of redirects for MSIE clients. .It Ic open_file_cache Cm off .It Ic open_file_cache Cm max Ns = Ns Ar N Oo Cm inactive Ns = Ns Ar time Oc .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Configures a cache that can store: .Bl -bullet .It open file descriptors, their sizes and modification times; .It information on existence of directories; .It file lookup errors, such as file not found, no read permission, and so on. Caching of errors should be enabled separately by the .Ic open_file_cache_errors directive. .El .Pp The directive has the following parameters: .Bl -tag -width Ds .It Cm max sets the maximum number of elements in the cache; on cache overflow the least recently used (LRU) elements are removed; .It Cm 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; .It Cm off disables the cache. .El .Pp Example: .Bd -literal -offset indent open_file_cache max=1000 inactive=20s; open_file_cache_valid 30s; open_file_cache_min_uses 2; open_file_cache_errors on; .Ed .It Ic open_file_cache_errors Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables caching of file lookup errors by .Ic open_file_cache . .It Ic open_file_cache_min_uses Ar number .Bl -tag -width Ds -compact .It default: 1 .It context: Ic http , Ic server , Ic location .El .Pp Sets the minimum .Ar number of file accesses during the period configured by the .Cm inactive parameter of the .Ic open_file_cache directive, required for a file descriptor to remain open in the cache. .It Ic open_file_cache_valid Ar time .Bl -tag -width Ds -compact .It default: 60s .It context: Ic http , Ic server , Ic location .El .Pp Sets a time after which .Ic open_file_cache elements should be validated. .It Ic optimize_server_names Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server .El .Pp This directive is obsolete. The .Ic server_name_in_redirect directive should be used instead. .It Ic port_in_redirect Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables specifying the port in redirects issued by nginx. The use of the primary server name in redirects is controlled by the .Ic server_name_in_redirect directive. .It Ic postpone_output Ar size .Bl -tag -width Ds -compact .It default: 1460 .It context: Ic http , Ic server , Ic location .El .Pp If possible, the transmission of client data will be postponed until nginx has at least .Ar size bytes of data to send. The zero value disables postponing data transmission. .It Ic read_ahead Ar size .Bl -tag -width Ds -compact .It default: 0 .It context: Ic http , Ic server , Ic location .El .Pp Sets the amount of pre-reading for the kernel when working with file. On Linux, the .Fn posix_fadvise 0 0 0 POSIX_FADV_SEQUENTIAL system call is used, and so the .Ar size parameter is ignored. On FreeBSD, the .Fn fcntl O_READAHEAD size system call, supported since FreeBSD 9.0-CURRENT, is used. FreeBSD 7 has to be patched. .It Ic recursive_error_pages Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables doing several redirects using the .Ic error_page directive. The number of such redirects is .Ic internal limited . .It Ic request_pool_size Ar size .Bl -tag -width Ds -compact .It default: 4k .It context: Ic http , Ic server .El .Pp Allows accurate tuning of per-request memory allocations. This directive has minimal impact on performance and should not generally be used. .It Ic reset_timedout_connection Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables resetting timed out connections. The reset is performed as follows. Before closing a socket, the .Dv 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. .It Ic resolver Ar address No ... Oo Cm valid Ns = Ns Ar time Oc .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Configures name servers used to resolve names of upstream servers into addresses, for example: .Bd -literal -offset indent resolver 127.0.0.1 [::1]:5353; .Ed .Pp An .Ar address can be specified as a domain name or IP address, and an optional port (1.3.1, 1.2.2). If port is not specified, the port 53 is used. Name servers are queried in a round-robin fashion. Before version 1.1.7, only a single name server could be configured. Specifying name servers using IPv6 addresses is supported starting from versions 1.3.1 and 1.2.2.By default, nginx caches answers using the TTL value of a response. An optional .Cm valid parameter allows overriding it: .Bd -literal -offset indent resolver 127.0.0.1 [::1]:5353 valid=30s; .Ed .Pp Before version 1.1.9, tuning of caching time was not possible, and nginx always cached answers for the duration of 5 minutes. .It Ic resolver_timeout Ar time .Bl -tag -width Ds -compact .It default: 30s .It context: Ic http , Ic server , Ic location .El .Pp Sets a timeout for name resolution, for example: .Bd -literal -offset indent resolver_timeout 5s; .Ed .It Ic root Ar path .Bl -tag -width Ds -compact .It default: Pa html .It context: Ic http , Ic server , Ic location , Ic if in location .El .Pp Sets the root directory for requests. For example, with the following configuration .Bd -literal -offset indent location /i/ { root /data/w3; } .Ed .Pp The .Pa /data/w3/i/top.gif file will be sent in response to the .Qq /i/top.gif request. The .Ar path value can contain variables, except .Va $document_root and .Va $realpath_root . A path to the file is constructed by merely adding a URI to the value of the .Ic root directive. If a URI has to be modified, the .Ic alias directive should be used. .It Ic satisfy Cm all | Cm any .Bl -tag -width Ds -compact .It default: all .It context: Ic http , Ic server , Ic location .El .Pp Allows access if all .Pq Ic all or at least one .Pq Ic any of the .Sx Module ngx_http_access_module , .Sx Module ngx_http_auth_basic_module or .Sx Module ngx_http_auth_request_module modules allow access. Example: .Bd -literal -offset indent location / { satisfy any; allow 192.168.1.0/32; deny all; auth_basic "closed site"; auth_basic_user_file conf/htpasswd; } .Ed .It Ic satisfy_any Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp This directive has been replaced by the .Cm any parameter of the .Ic satisfy directive. .It Ic send_lowat Ar size .Bl -tag -width Ds -compact .It default: 0 .It context: Ic http , Ic server , Ic location .El .Pp 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 .Dv NOTE_LOWAT flag of the .Cm kqueue method or the .Dv SO_SNDLOWAT socket option. In both cases the specified .Ar size is used. This directive is ignored on Linux, Solaris, and Windows. .It Ic send_timeout Ar time .Bl -tag -width Ds -compact .It default: 60s .It context: Ic http , Ic server , Ic location .El .Pp Sets a timeout for transmitting a response to the client. A timeout is set only between two successive write operations, not for the transmission of the whole response. If a client does not receive anything within this time, a connection is closed. .It Ic sendfile Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location , Ic if in location .El .Pp Enables or disables the use of .Fn sendfile . .It Ic sendfile_max_chunk Ar size .Bl -tag -width Ds -compact .It default: 0 .It context: Ic http , Ic server , Ic location .El .Pp When set to a non-zero value, limits the amount of data that can be transferred in a single .Fn sendfile call. Without the limit, one fast connection may seize the worker process entirely. .It Ic server Brq No ... .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp 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 .Ic listen directives describe all addresses and ports that should accept connections for the server, and the .Ic server_name directive lists all server names. .It Ic server_name Ar name No ... .Bl -tag -width Ds -compact .It default: Qq .It context: Ic server .El .Pp Sets names of a virtual server, for example: .Bd -literal -offset indent server { server_name example.com www.example.com; } .Ed .Pp The first name becomes the primary server name. Server names can include an asterisk .Pq Ic * replacing the first or last part of a name: .Bd -literal -offset indent server { server_name example.com *.example.com www.example.*; } .Ed .Pp Such names are called wildcard names. The first two of the names mentioned above can be combined in one: .Bd -literal -offset indent server { server_name .example.com; } .Ed .Pp It is also possible to use regular expressions in server names, preceding the name with a tilde .Pq Ic ~ : .Bd -literal -offset indent server { server_name www.example.com ~^www\\d+\\.example\\.com$; } .Ed .Pp Regular expressions can contain captures (0.7.40) that can later be used in other directives: .Bd -literal -offset indent server { server_name ~^(www\\.)?(.+)$; location / { root /sites/$2; } } server { server_name _; location / { root /sites/default; } } .Ed .Pp Named captures in regular expressions create variables (0.8.25) that can later be used in other directives: .Bd -literal -offset indent server { server_name ~^(www\\.)?(?.+)$; location / { root /sites/$domain; } } server { server_name _; location / { root /sites/default; } } .Ed .Pp If the directive's parameter is set to .Va $hostname (0.9.4), the machine's hostname is inserted. It is also possible to specify an empty server name (0.7.11): .Bd -literal -offset indent server { server_name www.example.com ""; } .Ed .Pp It allows this server to process requests without the Host header field - instead of the default server - for the given .Ar address Ns : Ns Ar 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: .Bl -bullet .It the exact name .It the longest wildcard name starting with an asterisk, e.g. .Ic *.example.com .It the longest wildcard name ending with an asterisk, e.g. .Cm mail.* .It the first matching regular expression (in order of appearance in the configuration file) .El Detailed description of server names is provided in a separate document. .It Ic server_name_in_redirect Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables the use of the primary server name, specified by the .Ic server_name directive, in 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 .Ic port_in_redirect directive. .It Ic server_names_hash_bucket_size Ar size .Bl -tag -width Ds -compact .It default: 32 | 64 | 128 .It context: Ic http .El .Pp 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. .It Ic server_names_hash_max_size Ar size .Bl -tag -width Ds -compact .It default: 512 .It context: Ic http .El .Pp Sets the maximum .Ar size of the server names hash tables. The details of setting up hash tables are provided in a separate document. .It Ic server_tokens Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables emitting nginx version in error messages and in the Server response header field. .It Ic tcp_nodelay Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables the use of the .Dv TCP_NODELAY option. The option is enabled only when a connection is transitioned into the keep-alive state. .It Ic tcp_nopush Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables the use of the .Dv TCP_NOPUSH socket option on FreeBSD or the .Dv TCP_CORK socket option on Linux. The options are enabled only when .Ic sendfile is used. Enabling the option allows .Bl -bullet .It sending the response header and the beginning of a file in one packet, on Linux and FreeBSD 4.*; .It sending a file in full packets. .El .It Ic try_files Ar file No ... Ar uri .It Ic try_files Ar file No ... = Ns Ar code .Bl -tag -width Ds -compact .It default: .It context: Ic server , Ic location .El .Pp 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 .Ar file parameter according to the .Ic root and .Ic alias directives. It is possible to check directory's existence by specifying a slash at the end of a name, e.g. .Qq $uri/ . If none of the files were found, an internal redirect to the .Ar uri specified in the last parameter is made. For example: .Bd -literal -offset indent location /images/ { try_files $uri /images/default.gif; } location = /images/default.gif { expires 30s; } .Ed .Pp 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 .Ar code : .Bd -literal -offset indent location / { try_files $uri $uri/index.html $uri.html =404; } .Ed .Pp Example in proxying Mongrel: .Bd -literal -offset indent location / { try_files /system/maintenance.html $uri $uri/index.html $uri.html @mongrel; } location @mongrel { proxy_pass http://mongrel; } .Ed .Pp Example for Drupal/FastCGI: .Bd -literal -offset indent 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 } .Ed .Pp In the following example, .Bd -literal -offset indent location / { try_files $uri $uri/ @drupal; } .Ed .Pp the .Ic try_files directive is equivalent to .Bd -literal -offset indent location / { error_page 404 = @drupal; log_not_found off; } .Ed .Pp And here, .Bd -literal -offset indent location ~ \\.php$ { try_files $uri @drupal; fastcgi_pass ...; fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; ... } .Ed .Pp .Ic try_files checks the existence of the PHP file before passing the request to the FastCGI server. Example for Wordpress and Joomla: .Bd -literal -offset indent 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 } .Ed .It Ic types Brq No ... .Bl -tag -width Ds -compact .It default: .Bd -literal -offset indent text/html html; image/gif gif; image/jpeg jpg; .Ed .It context: Ic http , Ic server , Ic location .El .Pp Maps file name extensions to MIME types of responses. Extensions are case-insensitive. Several extensions can be mapped to one type, for example: .Bd -literal -offset indent types { application/octet-stream bin exe dll; application/octet-stream deb; application/octet-stream dmg; } .Ed .Pp A sufficiently full mapping table is distributed with nginx in the .Pa 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: .Bd -literal -offset indent location /download/ { types { } default_type application/octet-stream; } .Ed .It Ic types_hash_bucket_size Ar size .Bl -tag -width Ds -compact .It default: 32 | 64 | 128 .It context: Ic http , Ic server , Ic location .El .Pp Sets the bucket size for the types 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. .It Ic types_hash_max_size Ar size .Bl -tag -width Ds -compact .It default: 1024 .It context: Ic http , Ic server , Ic location .El .Pp Sets the maximum .Ar size of the types hash tables. The details of setting up hash tables are provided in a separate document. .It Ic underscores_in_headers Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server .El .Pp 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 .Ic ignore_invalid_headers directive. A directive can be specified on the .Ic server level in a default server. In this case, its value will apply to all virtual servers listening on the same address and port. .It Ic variables_hash_bucket_size Ar size .Bl -tag -width Ds -compact .It default: 64 .It context: Ic http .El .Pp Sets the bucket size for the variables hash table. The details of setting up hash tables are provided in a separate document. .It Ic variables_hash_max_size Ar size .Bl -tag -width Ds -compact .It default: 512 .It context: Ic http .El .Pp Sets the maximum .Ar size of the variables hash table. The details of setting up hash tables are provided in a separate document. .El .Ss Embedded Variables The .Sx Module ngx_http_core_module module supports embedded variables with names matching the Apache Server variables. First of all, these are variables representing client request header fields, such as .Va $http_user_agent , .Va $http_cookie , and so on. Also there are other variables: .Bl -tag -width Ds .It Va $arg_ Ns Ar name argument .Ar name in the request line .It Va $args arguments in the request line .It Va $binary_remote_addr client address in a binary form, value's length is always 4 bytes .It Va $body_bytes_sent number of bytes sent to a client, not counting the response header; this variable is compatible with the .Qq \&%B parameter of the mod_log_config Apache module .It Va $bytes_sent number of bytes sent to a client (1.3.8, 1.2.5) .It Va $connection connection serial number (1.3.8, 1.2.5) .It Va $connection_requests current number of requests made through a connection (1.3.8, 1.2.5) .It Va $content_length Content-Length request header field .It Va $content_type Content-Type request header field .It Va $cookie_ Ns Ar name the .Ar name cookie .It Va $document_root .Ic root or .Ic alias directive's value for the current request .It Va $document_uri same as .Va $uri .It Va $host in this order of precedence: host name from the request line, or host name from the Host request header field, or the server name matching a request .It Va $hostname host name .It Va $http_ Ns Ar name arbitrary request header field; the last part of a variable name is the field name converted to lower case with dashes replaced by underscores .It Va $https .Qq on if connection operates in SSL mode, or an empty string otherwise .It Va $is_args .Qo ? Qc if a request line has arguments, or an empty string otherwise .It Va $limit_rate setting this variable enables response rate limiting; see .Ic limit_rate .It Va $msec current time in seconds with the milliseconds resolution (1.3.9, 1.2.6) .It Va $nginx_version nginx version .It Va $pid PID of the worker process .It Va $pipe .Qq p if request was pipelined, .Qo . Qc otherwise (1.3.12, 1.2.7) .It Va $query_string same as .Va $args .It Va $realpath_root an absolute pathname corresponding to the .Ic root or .Ic alias directive's value for the current request, with all symbolic links resolved to real paths .It Va $remote_addr client address .It Va $remote_port client port .It Va $remote_user user name supplied with the Basic authentication .It Va $request full original request line .It Va $request_body request body .Pp The variable's value is made available in locations processed by the .Ic proxy_pass and .Ic fastcgi_pass directives. .It Va $request_body_file name of a temporary file with the request body .Pp At the end of processing, the file needs to be removed. To always write the request body to a file, .Ic client_body_in_file_only needs to be enabled. When the name of a temporary file is passed in a proxied request or in a request to a FastCGI server, passing the request body should be disabled by the .Ic proxy_pass_request_body Cm off and .Ic fastcgi_pass_request_body Cm off directives, respectively. .It Va $request_completion .Qq OK if a request has completed, or an empty string otherwise .It Va $request_filename file path for the current request, based on the .Ic root or .Ic alias directives, and the request URI .It Va $request_length request length (including request line, header, and request body) (1.3.12, 1.2.7) .It Va $request_method request method, usually .Cm GET or .Cm POST .It Va $request_time request processing time in seconds with a milliseconds resolution (1.3.9, 1.2.6); time elapsed since the first bytes were read from the client .It Va $request_uri full original request URI (with arguments) .It Va $scheme request scheme, .Qq http or .Qq https .It Va $sent_http_ Ns Ar name arbitrary response header field; the last part of a variable name is the field name converted to lower case with dashes replaced by underscores .It Va $server_addr an address of the server which accepted a request .Pp Computing a value of this variable usually requires one system call. To avoid a system call, the .Ic listen directives must specify addresses and use the .Ic bind parameter. .It Va $server_name name of the server which accepted a request .It Va $server_port port of the server which accepted a request .It Va $server_protocol request protocol, usually .Qq HTTP/1.0 or .Qq HTTP/1.1 .It Va $status response status (1.3.2, 1.2.2) .It Va $tcpinfo_rtt , .Va $tcpinfo_rttvar , .Va $tcpinfo_snd_cwnd , .Va $tcpinfo_rcv_space information about the client TCP connection; available on systems that support the .Dv TCP_INFO socket option .It Va $time_iso8601 local time in the ISO 8601 standard format (1.3.12, 1.2.7) .It Va $time_local local time in the Common Log Format (1.3.12, 1.2.7) .It Va $uri current URI in request, normalized .Pp The value of .Va $uri may change during request processing, e.g. when doing internal redirects, or when using index files. .El .Ss Module ngx_http_access_module .Bl -tag -width Ds .It Ic allow Ar address | Ar CIDR | Cm unix: | Cm all .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location , Ic limit_except .El .Pp Allows access for the specified network or address. If the special value .Cm unix: is specified (1.5.1), allows access for all UNIX-domain sockets. .It Ic deny Ar address | Ar CIDR | Cm unix: | Cm all .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location , Ic limit_except .El .Pp Denies access for the specified network or address. If the special value .Cm unix: is specified (1.5.1), denies access for all UNIX-domain sockets. .El .Ss Module ngx_http_addition_module .Em This module is not enabled on OpenBSD. .Bl -tag -width Ds .It Ic add_before_body Ar uri .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Adds the text returned as a result of processing a given subrequest before the response body. An empty string .Pq Ic "" as a parameter cancels addition inherited from the previous configuration level. .It Ic add_after_body Ar uri .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Adds the text returned as a result of processing a given subrequest after the response body. An empty string .Pq Ic "" as a parameter cancels addition inherited from the previous configuration level. .It Ic addition_types Ar mime-type No ... .Bl -tag -width Ds -compact .It default: text/html .It context: Ic http , Ic server , Ic location .El .Pp Allows adding text in responses with the specified MIME types, in addition to .Qq text/html . The special value .Qq * matches any MIME type (0.8.29). .El .Ss Module ngx_http_auth_basic_module .Bl -tag -width Ds .It Ic auth_basic Ar string | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location , Ic limit_except .El .Pp 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 .Cm off allows cancelling the effect of the .Ic auth_basic directive inherited from the previous configuration level. .It Ic auth_basic_user_file Ar file .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location , Ic limit_except .El .Pp Specifies a file that keeps user names and passwords, in the following format: .Bd -literal -offset indent # comment name1:password1 name2:password2:comment name3:password3 .Ed .Pp The following password types are supported: .Bl -bullet .It encrypted with the .Fn crypt function; can be generated using the .Ic htpasswd utility from the Apache HTTP Server distribution or the .Ic openssl passwd command; .It hashed with the Apache variant of the MD5-based password algorithm (apr1); can be generated with the same tools; .It specified by the .Brq Ar scheme data syntax (1.0.3+) as described in RFC 2307; currently implemented schemes include .Cm PLAIN (an example one, should not be used), .Cm SHA (1.3.13) (plain SHA-1 hashing, should not be used) and .Cm SSHA (salted SHA-1 hashing, used by some software packages, notably OpenLDAP and Dovecot). Support for .Cm SHA scheme was added only to aid in migration from other web servers. It should not be used for new passwords, since unsalted SHA-1 hashing that it employs is vulnerable to rainbow table attacks. .El .El .Ss Module ngx_http_auth_request_module .Em This module is not enabled on OpenBSD. .Bl -tag -width Ds .It Ic auth_request Ar uri | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables authorization based on the result of a subrequest and sets the URI to which the subrequest will be sent. .It Ic auth_request_set Ar variable Ar value .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Sets the request .Ar variable to the given .Ar value after the authorization request completes. The value may contain variables from the authorization request, such as .Va $upstream_http_* . .El .Ss Module ngx_http_autoindex_module .Bl -tag -width Ds .It Ic autoindex Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables the directory listing output. .It Ic autoindex_exact_size Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp Specifies whether exact file sizes should be output in the directory listing, or rather rounded to kilobytes, megabytes, and gigabytes. .It Ic autoindex_localtime Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Specifies whether times in the directory listing should be output in the local time zone or UTC. .El .Ss Module ngx_http_browser_module .Bl -tag -width Ds .It Ic ancient_browser Ar string No ... .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp If any of the specified substrings is found in the User-Agent request header field, the browser will be considered ancient. The special string .Cm netscape4 corresponds to the regular expression .Qq ^Mozilla Ns / Ns Oo 1-4 Oc . .It Ic ancient_browser_value Ar string .Bl -tag -width Ds -compact .It default: 1 .It context: Ic http , Ic server , Ic location .El .Pp Sets a value for the .Va $ancient_browser variables. .It Ic modern_browser Ar browser Ar version .It Ic modern_browser Cm unlisted .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Specifies a version starting from which a browser is considered modern. A browser can be any one of the following: .Cm msie , .Cm gecko (browsers based on Mozilla), .Cm opera , .Cm safari , or .Cm konqueror . Versions can be specified in the following formats: X, X.X, X.X.X, or X.X.X.X. The maximum values for each of the format are 4000, 4000.99, 4000.99.99, and 4000.99.99.99, respectively. The special value .Cm unlisted specifies to consider a browser as modern if it was not listed by the .Ic modern_browser and .Ic ancient_browser directives. Otherwise such a browser is considered ancient. If a request does not provide the User-Agent field in the header, the browser is treated as not being listed. .It Ic modern_browser_value Ar string .Bl -tag -width Ds -compact .It default: 1 .It context: Ic http , Ic server , Ic location .El .Pp Sets a value for the .Va $modern_browser variables. .El .Ss Module ngx_http_charset_module .Bl -tag -width Ds .It Ic charset Ar charset | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location , Ic if in location .El .Pp Adds the specified .Ar charset to the Content-Type response header field. If this charset is different from the charset specified in the .Ic source_charset directive, a conversion is performed. The parameter .Cm off cancels the addition of charset to the Content-Type response header field. A charset can be defined with a variable: .Bd -literal -offset indent charset $charset; .Ed .Pp In such a case, all possible values of a variable need to be present in the configuration at least once in the form of the .Ic charset_map , .Ic charset , or .Ic source_charset directives. For .Cm utf-8 , .Cm windows-1251 , and .Cm koi8-r charsets, it is sufficient to include the files .Pa conf/koi-win , .Pa conf/koi-utf , and .Pa conf/win-utf into configuration. For other charsets, simply making a fictitious conversion table works, for example: .Bd -literal -offset indent charset_map iso-8859-5 _ { } .Ed .Pp In addition, a charset can be set in the X-Accel-Charset response header field. This capability can be disabled using the .Ic proxy_ignore_headers and .Ic fastcgi_ignore_headers directives. .It Ic charset_map Ar charset1 Ar charset2 Brq No ... .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp 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 .Qq ? . When converting from UTF-8, characters missing in a one-byte charset are replaced with .Qq &#XXXX; . Example: .Bd -literal -offset indent charset_map koi8-r windows-1251 { C0 FE ; # small yu C1 E0 ; # small a C2 E1 ; # small b C3 F6 ; # small ts ... } .Ed .Pp When describing a conversion table to UTF-8, codes for the UTF-8 charset should be given in the second column, for example: .Bd -literal -offset indent charset_map koi8-r utf-8 { C0 D18E ; # small yu C1 D0B0 ; # small a C2 D0B1 ; # small b C3 D186 ; # small ts ... } .Ed .Pp Full conversion tables from .Cm koi8-r to .Cm windows-1251 , and from .Cm koi8-r and .Cm windows-1251 to .Cm utf-8 are provided in the distribution files .Pa conf/koi-win , .Pa conf/koi-utf , and .Pa conf/win-utf . .It Ic charset_types Ar mime-type No ... .Bl -tag -width Ds -compact .It default: text/html text/xml text/plain text/vnd.wap.wml application/javascript application/rss+xml .It context: Ic http , Ic server , Ic location .El .Pp Enables module processing in responses with the specified MIME types in addition to .Ar text/html. The special value .Qq * matches any MIME type (0.8.29). Until version 1.5.4, application/x-javascript was used as the default MIME type instead of application/javascript . .It Ic override_charset Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location , Ic if in location .El .Pp Determines whether a conversion should be performed for answers received from a proxied or FastCGI server when the answers already carry a charset in the Content-Type response header field. If conversion is enabled, a charset specified in the received response is used as a source charset. It should be noted that if a response is received in a subrequest then the conversion from the response charset to the main request charset is always performed, regardless of the .Ic override_charset directive setting. .It Ic source_charset Ar charset .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location , Ic if in location .El .Pp Defines the source charset of a response. If this charset is different from the charset specified in the .Ic charset directive, a conversion is performed. .El .Ss Module ngx_http_dav_module .Em This module is not enabled on OpenBSD. .Bl -tag -width Ds .It Ic dav_access Ar users Ns : Ns Ar permissions No ... .Bl -tag -width Ds -compact .It default: user:rw .It context: Ic http , Ic server , Ic location .El .Pp Sets access permissions for newly created files and directories, e.g.: .Bd -literal -offset indent dav_access user:rw group:rw all:r; .Ed .Pp If any .Ar group or .Cm all access permissions are specified then .Ar user permissions may be omitted: .Bd -literal -offset indent dav_access group:rw all:r; .Ed .It Ic dav_methods Cm off | Ar method No ... .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Allows the specified HTTP and WebDAV methods. The parameter .Cm off denies all methods processed by this module. The following methods are supported: .Cm PUT , .Cm DELETE , .Cm MKCOL , .Cm COPY , and .Cm MOVE . A file uploaded with the .Cm PUT method is first written to a temporary file, and then the file is renamed. Starting from version 0.8.9, temporary files and the persistent store can be put on different file systems. However, be aware that in this case a file is copied across two file systems instead of the cheap renaming operation. It is thus recommended that for any given location both saved files and a directory holding temporary files, set by the .Ic client_body_temp_path directive, are put on the same file system. When creating a file with the .Cm PUT method, it is possible to specify the modification date by passing it in the Date header field. .It Ic create_full_put_path Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp The WebDAV specification only allows creating files in already existing directories. This directive allows creating all needed intermediate directories. .It Ic min_delete_depth Ar number .Bl -tag -width Ds -compact .It default: 0 .It context: Ic http , Ic server , Ic location .El .Pp 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 .Bd -literal -offset indent min_delete_depth 4; .Ed .Pp allows removing files on requests .Bd -literal -offset indent /users/00/00/name /users/00/00/name/pic.jpg /users/00/00/page.html .Ed .Pp and denies the removal of .Bd -literal -offset indent /users/00/00 .Ed .El .Ss Module ngx_http_empty_gif_module .Bl -tag -width Ds .It Ic empty_gif .Bl -tag -width Ds -compact .It default: .It context: Ic location .El .Pp Turns on module processing in a surrounding location. .El .Ss Module ngx_http_f4f_module .Em This module is only available in the commercial version of nginx. .Bl -tag -width Ds .It Ic f4f .Bl -tag -width Ds -compact .It default: .It context: Ic location .El .Pp Turns on module processing in the surrounding location. .It Ic f4f_buffer_size Ar size .Bl -tag -width Ds -compact .It default: 512k .It context: Ic http , Ic server , Ic location .El .Pp Sets the size of a memory buffer used for reading the .Pa .f4x index file. .El .Ss Module ngx_http_fastcgi_module .Bl -tag -width Ds .It Ic fastcgi_bind Ar address | Cm off .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Makes outgoing connections to a FastCGI server originate from the specified local IP .Ar address. Parameter value can contain variables (1.3.12). The special value .Cm off (1.3.12) cancels the effect of the .Ic fastcgi_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address. .It Ic fastcgi_buffer_size Ar size .Bl -tag -width Ds -compact .It default: 4k | 8k .It context: Ic http , Ic server , Ic location .El .Pp Sets the .Ar size of the buffer used for reading the first part of a response received from the FastCGI server. This part usually contains a small response header. By default, the buffer size is equal to the size of one buffer set by the .Ic fastcgi_buffers directive. It can be made smaller however. .It Ic fastcgi_buffering Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables buffering of responses from the FastCGI server. When buffering is enabled, nginx receives a response from the FastCGI server as soon as possible, saving it into the buffers set by the .Ic fastcgi_buffer_size and .Ic fastcgi_buffers directives. If the whole response does not fit into memory, a part of it can be saved to a .Ic fastcgi_temp_path temporary file on the disk. Writing to temporary files is controlled by the .Ic fastcgi_max_temp_file_size and .Ic fastcgi_temp_file_write_size directives. When buffering is disabled, a response is passed to a client synchronously, immediately as it is received. nginx will not try to read the whole response from the FastCGI server. The maximum size of the data that nginx can receive from the server at a time is set by the .Ic fastcgi_buffer_size directive. Buffering can also be enabled or disabled by passing .Cm yes or .Cm no in the X-Accel-Buffering response header field. This capability can be disabled using the .Ic fastcgi_ignore_headers directive. .It Ic fastcgi_buffers Ar number Ar size .Bl -tag -width Ds -compact .It default: 8 4k | 8k .It context: Ic http , Ic server , Ic location .El .Pp Sets the .Ar number and .Ar size of 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. .It Ic fastcgi_busy_buffers_size Ar size .Bl -tag -width Ds -compact .It default: 8k | 16k .It context: Ic http , Ic server , Ic location .El .Pp When .Ic fastcgi_buffering buffering of responses from the FastCGI server is enabled, limits the total .Ar size of buffers that can be busy sending a response to the client while the response is not yet fully read. In the mean time, the rest of the buffers can be used for reading a response and, if needed, buffering part of a response to a temporary file. By default, .Ar size is limited by the size of two buffers set by the .Ic fastcgi_buffer_size and .Ic fastcgi_buffers directives. .It Ic fastcgi_cache Ar zone | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Defines a shared memory zone used for caching. The same zone can be used in several places. The .Cm off parameter disables caching inherited from the previous configuration level. .It Ic fastcgi_cache_bypass Ar string No ... .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Defines conditions under which the response will not be taken from a cache. If at least one value of the .Ar string parameters is not empty and is not equal to 0 then the response will not be taken from the cache: .Bd -literal -offset indent fastcgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment; fastcgi_cache_bypass $http_pragma $http_authorization; .Ed .Pp Can be used along with the .Ic fastcgi_no_cache directive. .It Ic fastcgi_cache_key Ar string .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Defines a key for caching, for example .Bd -literal -offset indent fastcgi_cache_key localhost:9000$request_uri; .Ed .It Ic fastcgi_cache_lock Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp When enabled, only one request at a time will be allowed to populate a new cache element identified according to the .Ic 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 .Ic fastcgi_cache_lock_timeout directive. .It Ic fastcgi_cache_lock_timeout Ar time .Bl -tag -width Ds -compact .It default: 5s .It context: Ic http , Ic server , Ic location .El .Pp Sets a timeout for .Ic fastcgi_cache_lock . .It Ic fastcgi_cache_methods Cm GET | Cm HEAD | Cm POST No ... .Bl -tag -width Ds -compact .It default: Cm GET Cm HEAD .It context: Ic http , Ic server , Ic location .El .Pp If the client request method is listed in this directive then the response will be cached. .Cm GET and .Cm HEAD methods are always added to the list, though it is recommended to specify them explicitly. See also the .Ic fastcgi_no_cache directive. .It Ic fastcgi_cache_min_uses Ar number .Bl -tag -width Ds -compact .It default: 1 .It context: Ic http , Ic server , Ic location .El .Pp Sets the .Ar number of requests after which the response will be cached. .It Ic fastcgi_cache_path Ar path Oo Cm levels Ns = Ns Ar levels Oc Cm keys_zone Ns = Ns Ar name Ns : Ns Ar size Oo Cm inactive Ns = Ns Ar time Oc Oo Cm max_size Ns = Ns Ar size Oc Oo Cm loader_files Ns = Ns Ar number Oc Oo Cm loader_sleep Ns = Ns Ar time Oc Oo Cm loader_threshold Ns = Ns Ar time Oc .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp 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 .Ar levels parameter defines hierarchy levels of a cache. For example, in the following configuration .Bd -literal -offset indent fastcgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m; .Ed .Pp file names in a cache will look like this: .Bd -literal -offset indent /data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c .Ed .Pp A cached response is first written to a temporary file, and then the file is renamed. Starting from version 0.8.9, temporary files and the cache can be put on different file systems. However, be aware that in this case a file is copied across two file systems instead of the cheap renaming operation. It is thus recommended that for any given location both cache and a directory holding temporary files, set by the .Ic fastcgi_temp_path directive, are put on the same file system. In addition, all active keys and information about data are stored in a shared memory zone, whose .Ar name and .Ar size are configured by the .Cm keys_zone parameter. Cached data that are not accessed during the time specified by the .Cm inactive parameter get removed from the cache regardless of their freshness. By default, .Cm inactive is set to 10 minutes. The special cache manager process monitors the maximum cache size set by the .Cm max_size parameter. When this size is exceeded, it removes the least recently used data. A minute after the start the special cache loader process is activated. It loads information about previously cached data stored on file system into a cache zone. The loading is done in iterations. During one iteration no more than .Cm loader_files items are loaded (by default, 100). Besides, the duration of one iteration is limited by the .Cm loader_threshold parameter (by default, 200 milliseconds). Between iterations, a pause configured by the .Cm loader_sleep parameter (by default, 50 milliseconds) is made. .It Ic fastcgi_cache_use_stale Cm error | Cm timeout | Cm invalid_header | Cm updating | Cm http_500 | Cm http_503 | Cm http_403 | Cm http_404 | Cm off No ... .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp 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 .Ic fastcgi_next_upstream directive. Additionally, the .Cm updating parameter permits using a stale cached response if it is currently being updated. This allows minimizing the number of accesses to FastCGI servers when updating cached data. To minimize the number of accesses to FastCGI servers when populating a new cache element, the .Ic fastcgi_cache_lock directive can be used. .It Ic fastcgi_cache_valid Oo Ar code No ... Oc Ar time .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Sets caching time for different response codes. For example, the following directives .Bd -literal -offset indent fastcgi_cache_valid 200 302 10m; fastcgi_cache_valid 404 1m; .Ed .Pp set 10 minutes of caching for responses with codes 200 and 302 and 1 minute for responses with code 404. If only caching .Ar time is specified .Bd -literal -offset indent fastcgi_cache_valid 5m; .Ed .Pp then only 200, 301, and 302 responses are cached. In addition, the .Cm any parameter can be specified to cache any responses: .Bd -literal -offset indent fastcgi_cache_valid 200 302 10m; fastcgi_cache_valid 301 1h; fastcgi_cache_valid any 1m; .Ed .Pp Parameters of caching can also be set directly in the response header. This has higher priority than setting of caching time using the directive. The X-Accel-Expires header field sets caching time of a response in seconds. The zero value disables caching for a response. If a value starts with the .Qq @ prefix, it sets an absolute time in seconds since Epoch, up to which the response may be cached. If header does not include the X-Accel-Expires field, parameters of caching may be set in the header fields Expires or Cache-Control . If a header includes the Set-Cookie field, such a response will not be cached. Processing of one or more of these response header fields can be disabled using the .Ic fastcgi_ignore_headers directive. .It Ic fastcgi_catch_stderr Ar string .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Sets a string to search for in the error stream of a response received from a FastCGI server. If the .Ar string is found then it is considered that the FastCGI server has returned an .Ic fastcgi_next_upstream invalid response. This allows handling application errors in nginx, for example: .Bd -literal -offset indent location /php { fastcgi_pass backend:9000; ... fastcgi_catch_stderr "PHP Fatal error"; fastcgi_next_upstream error timeout invalid_header; } .Ed .It Ic fastcgi_connect_timeout Ar time .Bl -tag -width Ds -compact .It default: 60s .It context: Ic http , Ic server , Ic location .El .Pp Defines a timeout for establishing a connection with a FastCGI server. It should be noted that this timeout cannot usually exceed 75 seconds. .It Ic fastcgi_hide_header Ar field .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp By default, nginx does not pass the header fields Status and X-Accel-... from the response of a FastCGI server to a client. The .Ic 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 .Ic fastcgi_pass_header directive can be used. .It Ic fastcgi_ignore_client_abort Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Determines whether the connection with a FastCGI server should be closed when a client closes a connection without waiting for a response. .It Ic fastcgi_ignore_headers Ar field No ... .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp 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 and Set-Cookie (0.8.44). If not disabled, processing of these header fields has the following effect: .Bl -bullet .It X-Accel-Expires, Expires, Cache-Control and Set-Cookie set the parameters of response .Ic fastcgi_cache_valid caching; .It X-Accel-Redirect performs an .Ic internal redirect to the specified URI; .It X-Accel-Limit-Rate sets the .Ic limit_rate rate limit for transmission of a response to a client; .It X-Accel-Buffering enables or disables .Ic fastcgi_buffering buffering of a response; .It X-Accel-Charset sets the desired .Ic charset of a response. .El .It Ic fastcgi_index Ar name .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Sets a file name that will be appended after a URI that ends with a slash, in the value of the .Va $fastcgi_script_name variable. For example, with these settings .Bd -literal -offset indent fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; .Ed .Pp and the .Qq /page.php request, the SCRIPT_FILENAME parameter will be equal to .Pa /home/www/scripts/php/page.php , and with the .Qq / request it will be equal to .Pa /home/www/scripts/php/index.php . .It Ic fastcgi_intercept_errors Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Determines whether FastCGI server responses with codes greater than or equal to 300 should be passed to a client or be redirected to nginx for processing with the .Ic error_page directive. .It Ic fastcgi_keep_conn Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp By default, a FastCGI server will close a connection right after sending the response. However, when this directive is set to the value .Cm on , nginx will instruct a FastCGI server to keep connections open. This is necessary, in particular, for .Ic keepalive connections to FastCGI servers to function. .It Ic fastcgi_max_temp_file_size Ar size .Bl -tag -width Ds -compact .It default: 1024m .It context: Ic http , Ic server , Ic location .El .Pp When buffering of responses from the FastCGI server is enabled, and the whole response does not fit into the memory buffers set by the .Ic fastcgi_buffer_size and .Ic fastcgi_buffers directives, a part of the response can be saved to a temporary file. This directive sets the maximum .Ar size of a temporary file. The size of data written to a temporary file at a time is set by the .Ic fastcgi_temp_file_write_size directive. The zero value disables buffering of responses to temporary files. .It Ic fastcgi_next_upstream Cm error | Cm timeout | Cm invalid_header | Cm http_500 | Cm http_503 | Cm http_403 | Cm http_404 | Cm off No ... .Bl -tag -width Ds -compact .It default: Cm error Cm timeout .It context: Ic http , Ic server , Ic location .El .Pp Specifies in which cases a request should be passed to the next server: .Bl -tag -width Ds .It Cm error an error occurred while establishing a connection with the server, passing a request to it, or reading the response header; .It Cm timeout a timeout has occurred while establishing a connection with the server, passing a request to it, or reading the response header; .It Cm invalid_header a server returned an empty or invalid response; .It Cm http_500 a server returned a response with the code 500; .It Cm http_503 a server returned a response with the code 503; .It Cm http_403 a server returned a response with the code 403; .It Cm http_404 a server returned a response with the code 404; .It Cm off disables passing a request to the next server. .El .Pp One should bear in mind that passing a request to the next server is only possible if nothing has been sent to a client yet. That is, if an error or timeout occurs in the middle of the transferring of a response, fixing this is impossible. The directive also defines what is considered an unsuccessful attempt of communication with a server. The cases of .Cm error , .Cm timeout and .Cm invalid_header are always considered unsuccessful attempts, even if they are not specified in the directive. The cases of .Cm http_500 and .Cm http_503 are considered unsuccessful attempts only if they are specified in the directive. The cases of .Cm http_403 and .Cm http_404 are never considered unsuccessful attempts. .It Ic fastcgi_no_cache Ar string No ... .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Defines conditions under which the response will not be saved to a cache. If at least one value of the .Ar string parameters is not empty and is not equal to 0 then the response will not be saved: .Bd -literal -offset indent fastcgi_no_cache $cookie_nocache $arg_nocache$arg_comment; fastcgi_no_cache $http_pragma $http_authorization; .Ed .Pp Can be used along with the .Ic fastcgi_cache_bypass directive. .It Ic fastcgi_param Ar parameter Ar value Oo Cm if_not_empty Oc .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Sets a .Ar parameter that should be passed to the FastCGI server. A .Ar value can contain text, variables, and their combination. These directives are inherited from the previous level if and only if there are no .Ic fastcgi_param directives defined on the current level. The following example shows the minimum required settings for PHP: .Bd -literal -offset indent fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; fastcgi_param QUERY_STRING $query_string; .Ed .Pp The SCRIPT_FILENAME parameter is used in PHP for determining the script name, and the QUERY_STRING parameter is used to pass request parameters. For scripts that process POST requests, the following three parameters are also required: .Bd -literal -offset indent fastcgi_param REQUEST_METHOD $request_method; fastcgi_param CONTENT_TYPE $content_type; fastcgi_param CONTENT_LENGTH $content_length; .Ed .Pp If PHP was built with the .Fl -enable-force-cgi-redirect configuration parameter, the REDIRECT_STATUS parameter should also be passed with the value 200: .Bd -literal -offset indent fastcgi_param REDIRECT_STATUS 200; .Ed .Pp If a directive is specified with .Cm if_not_empty (1.1.11) then such a parameter will not be passed to the server until its value is not empty: .Bd -literal -offset indent fastcgi_param HTTPS $https if_not_empty; .Ed .It Ic fastcgi_pass Ar address .Bl -tag -width Ds -compact .It default: .It context: Ic location , Ic if in location .El .Pp Sets the address of a FastCGI server. The address can be specified as a domain name or IP address, and an optional port: .Bd -literal -offset indent fastcgi_pass localhost:9000; .Ed .Pp or as a UNIX-domain socket path: .Bd -literal -offset indent fastcgi_pass unix:/tmp/fastcgi.socket; .Ed .Pp If a domain name resolves to several addresses, all of them will be used in a round-robin fashion. In addition, an address can be specified as a server group. .It Ic fastcgi_pass_header Ar field .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Permits passing .Ic fastcgi_hide_header otherwise disabled header fields from a FastCGI server to a client. .It Ic fastcgi_read_timeout Ar time .Bl -tag -width Ds -compact .It default: 60s .It context: Ic http , Ic server , Ic location .El .Pp Defines a timeout for reading a response from the FastCGI server. A timeout is set only between two successive read operations, not for the transmission of the whole response. If a FastCGI server does not transmit anything within this time, a connection is closed. .It Ic fastcgi_pass_request_body Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp Indicates whether the original request body is passed to the FastCGI server. See also the .Ic fastcgi_pass_request_headers directive. .It Ic fastcgi_pass_request_headers Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp Indicates whether the header fields of the original request are passed to the FastCGI server. See also the .Ic fastcgi_pass_request_body directive. .It Ic fastcgi_send_lowat Ar size .Bl -tag -width Ds -compact .It default: 0 .It context: Ic http , Ic server , Ic location .El .Pp 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 .Dv NOTE_LOWAT flag of the .Cm kqueue method, or the .Dv SO_SNDLOWAT socket option, with the specified .Ar size . This directive is ignored on Linux, Solaris, and Windows. .It Ic fastcgi_send_timeout Ar time .Bl -tag -width Ds -compact .It default: 60s .It context: Ic http , Ic server , Ic location .El .Pp Sets a timeout for transmitting a request to the FastCGI server. A timeout is set only between two successive write operations, not for the transmission of the whole request. If a FastCGI server does not receive anything within this time, a connection is closed. .It Ic fastcgi_split_path_info Ar regex .Bl -tag -width Ds -compact .It default: .It context: Ic location .El .Pp Defines a regular expression that captures a value for the .Va $fastcgi_path_info variable. A regular expression should have two captures: the first becomes a value of the .Va $fastcgi_script_name variable, the second becomes a value of the .Va $fastcgi_path_info variable. For example, with these settings .Bd -literal -offset indent location ~ ^(.+\\.php)(.*)$ { fastcgi_split_path_info ^(.+\\.php)(.*)$; fastcgi_param SCRIPT_FILENAME /path/to/php$fastcgi_script_name; fastcgi_param PATH_INFO $fastcgi_path_info; .Ed .Pp and the .Qq /show.php/article/0001 request, the SCRIPT_FILENAME parameter will be equal to .Pa /path/to/php/show.php , and the PATH_INFO parameter will be equal to .Pa /article/0001 . .It Ic fastcgi_store Cm on | Cm off | Ar string .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables saving of files to a disk. The .Cm on parameter saves files with paths corresponding to the directives .Ic alias or .Ic root. The .Cm off parameter disables saving of files. In addition, the file name can be set explicitly using the .Ar string with variables: .Bd -literal -offset indent fastcgi_store /data/www$original_uri; .Ed .Pp The modification time of files is set according to the received Last-Modified response header field. A response is first written to a temporary file, and then the file is renamed. Starting from version 0.8.9, temporary files and the persistent store can be put on different file systems. However, be aware that in this case a file is copied across two file systems instead of the cheap renaming operation. It is thus recommended that for any given location both saved files and a directory holding temporary files, set by the .Ic fastcgi_temp_path directive, are put on the same file system. This directive can be used to create local copies of static unchangeable files, e.g.: .Bd -literal -offset indent location /images/ { root /data/www; open_file_cache_errors off; error_page 404 = /fetch$uri; } location /fetch/ { internal; fastcgi_pass backend:9000; ... fastcgi_store on; fastcgi_store_access user:rw group:rw all:r; fastcgi_temp_path /data/temp; alias /data/www/; } .Ed .It Ic fastcgi_store_access Ar users Ns : Ns Ar permissions No ... .Bl -tag -width Ds -compact .It default: user:rw .It context: Ic http , Ic server , Ic location .El .Pp Sets access permissions for newly created files and directories, e.g.: .Bd -literal -offset indent fastcgi_store_access user:rw group:rw all:r; .Ed .Pp If any .Ar group or .Cm all access permissions are specified then .Ar user permissions may be omitted: .Bd -literal -offset indent fastcgi_store_access group:rw all:r; .Ed .It Ic fastcgi_temp_file_write_size Ar size .Bl -tag -width Ds -compact .It default: 8k | 16k .It context: Ic http , Ic server , Ic location .El .Pp Limits the .Ar 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, .Ar size is limited by two buffers set by the .Ic fastcgi_buffer_size and .Ic fastcgi_buffers directives. The maximum size of a temporary file is set by the .Ic fastcgi_max_temp_file_size directive. .It Ic fastcgi_temp_path Ar path Oo Ar level1 Oo Ar level2 Oo Ar level3 Oc Oc Oc .Bl -tag -width Ds -compact .It default: fastcgi_temp .It context: Ic http , Ic server , Ic location .El .Pp 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 .Bd -literal -offset indent fastcgi_temp_path /spool/nginx/fastcgi_temp 1 2; .Ed .Pp a temporary file might look like this: .Bd -literal -offset indent /spool/nginx/fastcgi_temp/7/45/00000123457 .Ed .El .Ss Module ngx_http_flv_module .Em This module is not enabled on OpenBSD. .Bl -tag -width Ds .It Ic flv .Bl -tag -width Ds -compact .It default: .It context: Ic location .El .Pp Turns on module processing in a surrounding location. .El .Ss Module ngx_http_geo_module .Bl -tag -width Ds .It Ic geo Oo Ar $address Oc Ar $variable Brq No ... .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp Describes the dependency of values of the specified variable on the client IP address. By default, the address is taken from the .Va $remote_addr variable, but it can also be taken from another variable (0.7.27), for example: .Bd -literal -offset indent geo $arg_remote_addr $geo { ...; } .Ed .Pp Since variables are evaluated only when used, the mere existence of even a large number of declared .Ic geo variables does not cause any extra costs for request processing. If the value of a variable does not represent a valid IP address then the 255.255.255.255 address is used. Addresses are specified either as prefixes in CIDR notation (including individual addresses) or as ranges (0.7.23). IPv6 prefixes are supported starting from versions 1.3.10 and 1.2.7. The following special parameters are also supported: .Bl -tag -width Ds .It Cm delete deletes the specified network (0.7.23). .It Cm default a value set to the variable if the client address does not match any of the specified addresses. When addresses are specified in CIDR notation, 0.0.0.0/0 and ::/0 can be used instead of .Cm default. When .Cm default is not specified, the default value will be an empty string. .It Cm include includes a file with addresses and values. There can be several inclusions. .It Cm proxy defines trusted addresses (0.8.7, 0.7.63). When a request comes from a trusted address, an address from the X-Forwarded-For request header field will be used instead. In contrast to the regular addresses, trusted addresses are checked sequentially. Trusted IPv6 addresses are supported starting from versions 1.3.0 and 1.2.1. .It Cm proxy_recursive enables recursive address search (1.3.0, 1.2.1). If recursive search is disabled then instead of the original client address that matches one of the trusted addresses, the last address sent in X-Forwarded-For will be used. If recursive search is enabled then instead of the original client address that matches one of the trusted addresses, the last non-trusted address sent in X-Forwarded-For will be used. .It Cm ranges indicates that addresses are specified as ranges (0.7.23). This parameter should be the first. To speed up loading of a geo base, addresses should be put in ascending order. .El .Pp Example: .Bd -literal -offset indent geo $country { default ZZ; include conf/geo.conf; delete 127.0.0.0/16; proxy 192.168.100.0/24; proxy 2001:0db8::/32; 127.0.0.0/24 US; 127.0.0.1/32 RU; 10.1.0.0/16 RU; 192.168.1.0/24 UK; } .Ed .Pp The .Pa conf/geo.conf file could contain the following lines: .Bd -literal -offset indent 10.2.0.0/16 RU; 192.168.2.0/24 RU; .Ed .Pp A value of the most specific match is used. For example, for the 127.0.0.1 address the value RU will be chosen, not US . Example with ranges: .Bd -literal -offset indent geo $country { ranges; default ZZ; 127.0.0.0-127.0.0.0 US; 127.0.0.1-127.0.0.1 RU; 127.0.0.1-127.0.0.255 US; 10.1.0.0-10.1.255.255 RU; 192.168.1.0-192.168.1.255 UK; } .Ed .El .Ss Module ngx_http_geoip_module .Em This module is not enabled on OpenBSD. .Bl -tag -width Ds .It Ic geoip_country Ar file .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp Specifies a database used to determine the country depending on the client IP address. The following variables are available when using this database: .Bl -tag -width Ds .It Va $geoip_country_code two-letter country code, for example, RU, US. .It Va $geoip_country_code3 three-letter country code, for example, RUS, USA. .It Va $geoip_country_name country name, for example, Russian Federation, United States. .El .It Ic geoip_city Ar file .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp 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: .Bl -tag -width Ds .It Va $geoip_area_code telephone area code (US only). This variable may contain outdated information since the corresponding database field is deprecated. .It Va $geoip_city_continent_code two-letter continent code, for example, EU, NA. .It Va $geoip_city_country_code two-letter country code, for example, RU, US. .It Va $geoip_city_country_code3 three-letter country code, for example, RUS, USA. .It Va $geoip_city_country_name country name, for example, Russian Federation, United States. .It Va $geoip_dma_code DMA region code in US (also known as metro code), according to the geotargeting in Google AdWords API. .It Va $geoip_latitude latitude. .It Va $geoip_longitude longitude. .It Va $geoip_region two-symbol country region code (region, territory, state, province, federal land and the like), for example, 48, DC. .It Va $geoip_region_name country region name (region, territory, state, province, federal land and the like), for example, Moscow City, District of Columbia. .It Va $geoip_city city name, for example, Moscow, Washington. .It Va $geoip_postal_code postal code. .El .It Ic geoip_org Ar file .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp Specifies a database used to determine the organization depending on the client IP address. The following variable is available when using this database: .Bl -tag -width Ds .It Va $geoip_org organization name, for example, The University of Melbourne. .El .It Ic geoip_proxy Ar address | Ar CIDR .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp 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. .It Ic geoip_proxy_recursive Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http .El .Pp 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. .El .Ss Module ngx_http_gunzip_module .Em This module is not enabled on OpenBSD. .Bl -tag -width Ds .It Ic gunzip Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp 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: .Ic gzip_http_version , .Ic gzip_proxied , and .Ic gzip_disable . See also the .Ic gzip_vary directive. .It Ic gunzip_buffers Ar number Ar size .Bl -tag -width Ds -compact .It default: 32 4k | 16 8k .It context: Ic http , Ic server , Ic location .El .Pp Sets the .Ar number and .Ar 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. .El .Ss Module ngx_http_gzip_module .Bl -tag -width Ds .It Ic gzip Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location , Ic if in location .El .Pp Enables or disables gzipping of responses. .It Ic gzip_buffers Ar number Ar size .Bl -tag -width Ds -compact .It default: 32 4k | 16 8k .It context: Ic http , Ic server , Ic location .El .Pp Sets the .Ar number and .Ar size of buffers used to compress a response. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform. Until version 0.7.28, four 4K or 8K buffers were used by default. .It Ic gzip_comp_level Ar level .Bl -tag -width Ds -compact .It default: 1 .It context: Ic http , Ic server , Ic location .El .Pp Sets a gzip compression .Ar level of a response. Acceptable values are in the range from 1 to 9. .It Ic gzip_disable Ar regex No ... .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Disables gzipping of responses for requests with User-Agent header fields matching any of the specified regular expressions. The special mask .Cm msie6 (0.7.12) corresponds to the regular expression .Qq MSIE Ns Oo 4-6 Oc \\. , but works faster. Starting from version 0.8.11, .Qq MSIE 6.0; ... SV1 is excluded from this mask. .It Ic gzip_min_length Ar length .Bl -tag -width Ds -compact .It default: 20 .It context: Ic http , Ic server , Ic location .El .Pp Sets the minimum length of a response that will be gzipped. The length is determined only from the Content-Length response header field. .It Ic gzip_http_version Cm 1.0 | Cm 1.1 .Bl -tag -width Ds -compact .It default: 1.1 .It context: Ic http , Ic server , Ic location .El .Pp Sets the minimum HTTP version of a request required to compress a response. .It Ic gzip_proxied Cm off | Cm expired | Cm no-cache | Cm no-store | Cm private | Cm no_last_modified | Cm no_etag | Cm auth | Cm any No ... .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables gzipping of responses for proxied requests depending on the request and response. The fact that the response is proxied is determined by the presence of the Via request header field. A directive accepts multiple parameters: .Bl -tag -width Ds .It Cm off disables compression for all proxied requests, ignoring other parameters; .It Cm expired enables compression if a response header includes the Expires field with a value that disables caching; .It Cm no-cache enables compression if a response header includes the Cache-Control field with the .Cm no-cache parameter; .It Cm no-store enables compression if a response header includes the Cache-Control field with the .Cm no-store parameter; .It Cm private enables compression if a response header includes the Cache-Control field with the .Cm private parameter; .It Cm no_last_modified enables compression if a response header does not include the Last-Modified field; .It Cm no_etag enables compression if a response header does not include the ETag field; .It Cm auth enables compression if a request header includes the Authorization field; .It Cm any enables compression for all proxied requests. .El .It Ic gzip_types Ar mime-type No ... .Bl -tag -width Ds -compact .It default: text/html .It context: Ic http , Ic server , Ic location .El .Pp Enables gzipping of responses for the specified MIME types in addition to .Ar text/html . The special value .Qq * matches any MIME type (0.8.29). Responses with the .Ar text/html type are always compressed. .It Ic gzip_vary Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables inserting the Vary: Accept-Encoding response header field if the directives .Ic gzip , .Ic gzip_static , or .Ic gunzip are active. .El .Ss Module ngx_http_gzip_static_module .Bl -tag -width Ds .It Ic gzip_static Cm on | Cm off | Cm always .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables .Pq Ic on or disables .Pq Ic off checking the existence of precompressed files. The following directives are also taken into account: .Ic gzip_http_version , .Ic gzip_proxied , .Ic gzip_disable , and .Ic gzip_vary . With the .Cm always value (1.3.6), gzipped file is used in all cases, without checking if the client supports it. It is useful if there are no uncompressed files on the disk anyway or the .Sx Module ngx_http_gunzip_module is used. The files can be compressed using the .Ic gzip command, or any other compatible one. It is recommended that the modification date and time of original and compressed files be the same. .El .Ss Module ngx_http_headers_module .Bl -tag -width Ds .It Ic add_header Ar name Ar value .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location , Ic if in location .El .Pp Adds the specified field to a response header provided that the response code equals 200, 201, 204, 206, 301, 302, 303, 304, or 307. A value can contain variables. .It Ic expires Oo Cm modified Oc Ar time .It Ic expires Cm epoch | Cm max | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location , Ic if in location .El .Pp Enables or disables adding or modifying the Expires and Cache-Control response header fields provided that the response code equals 200, 201, 204, 206, 301, 302, 303, 304, or 307. A parameter can be a positive or negative .Ar time . A time in the Expires field is computed as a sum of the current time and .Ar time specified in the directive. If the .Cm modified parameter is used (0.7.0, 0.6.32) then time is computed as a sum of the file's modification time and .Ar time specified in the directive. In addition, it is possible to specify a time of the day using the .Qq @ prefix (0.7.9, 0.6.34): .Bd -literal -offset indent expires @15h30m; .Ed .Pp The .Cm epoch parameter corresponds to the absolute time Thu, 01 Jan 1970 00:00:01 GMT. The contents of the Cache-Control field depends on the sign of the specified time: .Bl -bullet .It time is negative - Cache-Control: no-cache. .It time is positive or zero - Cache-Control: max-age=t, where t is a time specified in the directive, in seconds. .El .Pp The .Cm max parameter sets Expires to the value .Qq Thu, 31 Dec 2037 23:55:55 GMT , and Cache-Control to 10 years. The .Cm off parameter disables adding or modifying the Expires and Cache-Control response header fields. .El .Ss Module ngx_http_hls_module .Em This module is only available in the commercial version of nginx. .Bl -tag -width Ds .It Ic hls .Bl -tag -width Ds -compact .It default: .It context: Ic location .El .Pp Turns on HLS streaming in the surrounding location. .It Ic hls_buffers Ar number Ar size .Bl -tag -width Ds -compact .It default: 8 2m .It context: Ic http , Ic server , Ic location .El .Pp Sets the maximum .Ar number and .Ar size of buffers that are used for reading and writing data frames. .It Ic hls_fragment Ar time .Bl -tag -width Ds -compact .It default: 5s .It context: Ic http , Ic server , Ic location .El .Pp Defines the default fragment length for playlist URIs requested without the len argument. .It Ic hls_mp4_buffer_size Ar size .Bl -tag -width Ds -compact .It default: 512k .It context: Ic http , Ic server , Ic location .El .Pp Sets the initial .Ar size of the memory buffer used to process MP4 files. .It Ic hls_mp4_max_buffer_size Ar size .Bl -tag -width Ds -compact .It default: 10m .It context: Ic http , Ic server , Ic location .El .Pp During metadata processing, a larger buffer may become necessary. Its size cannot exceed the specified .Ar size , or else nginx will return the server error 500 (Internal Server Error), and log the following message: .Bd -literal -offset indent "/some/movie/file.mp4" mp4 moov atom is too large: 12583268, you may want to increase hls_mp4_max_buffer_size .Ed .El .Ss Module ngx_http_image_filter_module .Em This module is not enabled on OpenBSD. .Bl -tag -width Ds .It Ic image_filter Cm off .It Ic image_filter Cm test .It Ic image_filter Cm size .It Ic image_filter Cm rotate Cm 90 | Cm 180 | Cm 270 .It Ic image_filter Cm resize Ar width Ar height .It Ic image_filter Cm crop Ar width Ar height .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic location .El .Pp Sets the type of transformation to perform on images: .Bl -tag -width Ds .It Cm off turns off module processing in a surrounding location. .It Cm test ensures that responses are images in either JPEG, GIF, or PNG format. Otherwise, the 415 (Unsupported Media Type) error is returned. .It Cm size outputs information about images in a JSON format, e.g.: .Bd -literal -offset indent { "img" : { "width": 100, "height": 100, "type": "gif" } } .Ed .Pp In case of an error, the output is as follows: .Bd -literal -offset indent {} .Ed .It Cm rotate Cm 90 | Cm 180 | Cm 270 rotates images counter-clockwise by the specified number of degrees. Parameter value can contain variables. This mode can be used either alone or along with the .Cm resize and .Cm crop transformations. .It Cm resize Ar width Ar height proportionally reduces an image to the specified sizes. To reduce by only one dimension, another dimension can be specified as .Qq - . In case of an error, the server will return code 415 (Unsupported Media Type). Parameter values can contain variables. When used along with the .Cm rotate parameter, the rotation happens after reduction. .It Cm crop Ar width Ar height proportionally reduces an image to the larger side size and crops extraneous edges by another side. To reduce by only one dimension, another dimension can be specified as .Qq - . In case of an error, the server will return code 415 (Unsupported Media Type). Parameter values can contain variables. When used along with the .Cm rotate parameter, the rotation happens before reduction. .El .It Ic image_filter_buffer Ar size .Bl -tag -width Ds -compact .It default: 1M .It context: Ic http , Ic server , Ic location .El .Pp Sets the maximum size of the buffer used for reading images. When the size is exceeded the server returns error 415 (Unsupported Media Type). .It Ic image_filter_interlace Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp If enabled, final images will be interlaced. For JPEG, final images will be in progressive JPEG format. .It Ic image_filter_jpeg_quality Ar quality .Bl -tag -width Ds -compact .It default: 75 .It context: Ic http , Ic server , Ic location .El .Pp Sets the desired .Ar 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. .It Ic image_filter_sharpen Ar percent .Bl -tag -width Ds -compact .It default: 0 .It context: Ic http , Ic server , Ic location .El .Pp Increases sharpness of the final image. The sharpness percentage can exceed 100. The zero value disables sharpening. Parameter value can contain variables. .It Ic image_filter_transparency Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp 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. .El .Ss Module ngx_http_index_module .Bl -tag -width Ds .It Ic index Ar file No ... .Bl -tag -width Ds -compact .It default: Pa index.html .It context: Ic http , Ic server , Ic location .El .Pp Defines files that will be used as an index. The .Ar 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: .Bd -literal -offset indent index index.$geo.html index.0.html /index.html; .Ed .Pp It should be noted that using an index file causes an internal redirect, and the request can be processed in a different location. For example, with the following configuration: .Bd -literal -offset indent location = / { index index.html; } location / { ... } .Ed .Pp a .Qq / request will actually be processed in the second location as .Pa /index.html . .El .Ss Module ngx_http_limit_conn_module .Bl -tag -width Ds .It Ic limit_conn Ar zone Ar number .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp 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 503 (Service Temporarily Unavailable) error in reply to a request. For example, the directives .Bd -literal -offset indent limit_conn_zone $binary_remote_addr zone=addr:10m; server { location /download/ { limit_conn addr 1; } .Ed .Pp allow only one connection per an IP address at a time. When several .Ic limit_conn directives are specified, any configured limit will apply. For example, the following configuration will limit the number of connections to the server per a client IP and, at the same time, the total number of connections to the virtual host: .Bd -literal -offset indent limit_conn_zone $binary_remote_addr zone=perip:10m; limit_conn_zone $server_name zone=perserver:10m; server { ... limit_conn perip 10; limit_conn perserver 100; } .Ed .Pp These directives are inherited from the previous level if and only if there are no .Ic limit_conn directives on the current level. .It Ic limit_conn_log_level Cm info | Cm notice | Cm warn | Cm error .Bl -tag -width Ds -compact .It default: Cm error .It context: Ic http , Ic server , Ic location .El .Pp Sets the desired logging level for cases when the server limits the number of connections. .It Ic limit_conn_status Ar code .Bl -tag -width Ds -compact .It default: 503 .It context: Ic http , Ic server , Ic location .El .Pp Sets the status code to return in response to rejected requests. .It Ic limit_conn_zone Ar $variable Cm zone Ns = Ns Ar name Ns : Ns Ar size .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp 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 is any non-empty value of the specified variable (empty values are not accounted). Usage example: .Bd -literal -offset indent limit_conn_zone $binary_remote_addr zone=addr:10m; .Ed .Pp Here, a client IP address serves as a key. Note that instead of .Va $remote_addr , the .Va $binary_remote_addr variable is used here. The .Va $remote_addr variable's size can vary from 7 to 15 bytes. The stored state occupies either 32 or 64 bytes of memory on 32-bit platforms and always 64 bytes on 64-bit platforms. The .Va $binary_remote_addr variable's size is always 4 bytes. The stored state always occupies 32 bytes on 32-bit platforms and 64 bytes on 64-bit platforms. One megabyte zone can keep about 32 thousand 32-byte states or about 16 thousand 64-byte states. If the zone storage is exhausted, the server will return the 503 (Service Temporarily Unavailable) error to all further requests. .It Ic limit_zone Ar name Ar $variable Ar size .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp This directive is made obsolete in version 1.1.8, an equivalent .Ic limit_conn_zone directive with a changed syntax should be used instead: .Ic limit_conn_zone Ar $variable Cm zone Ns = Ns Ar name Ns : Ns Ar size ; .El .Ss Module ngx_http_limit_req_module .Bl -tag -width Ds .It Ic limit_req Cm zone Ns = Ns Ar name Oo Cm burst Ns = Ns Ar number Oc Oo Cm nodelay Oc .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp 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 503 (Service Temporarily Unavailable). By default, the maximum burst size is equal to zero. For example, the directives .Bd -literal -offset indent limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s; server { location /search/ { limit_req zone=one burst=5; } .Ed .Pp allow not more than 1 request per second at an average, with bursts not exceeding 5 requests. If delaying of excessive requests while requests are being limited is not desired, the parameter .Cm nodelay should be used: .Bd -literal -offset indent limit_req zone=one burst=5 nodelay; .Ed .It Ic limit_req_log_level Cm info | Cm notice | Cm warn | Cm error .Bl -tag -width Ds -compact .It default: Cm error .It context: Ic http , Ic server , Ic location .El .Pp 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 .Ic limit_req_log_level notice is specified, delays are logged with the .Cm info level. .It Ic limit_req_status Ar code .Bl -tag -width Ds -compact .It default: 503 .It context: Ic http , Ic server , Ic location .El .Pp Sets the status code to return in response to rejected requests. .It Ic limit_req_zone Ar $variable Cm zone Ns = Ns Ar name Ns : Ns Ar size Cm rate Ns = Ns Ar rate .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp 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 is any non-empty value of the specified variable (empty values are not accounted). Usage example: .Bd -literal -offset indent limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s; .Ed .Pp Here, the states are kept in a 10 megabyte zone one, and an average request processing rate for this zone cannot exceed 1 request per second. A client IP address serves as a key. Note that instead of .Va $remote_addr , the .Va $binary_remote_addr variable is used here, that allows to decrease the state size down to 64 bytes. One megabyte zone can keep about 16 thousand 64-byte states. If the zone storage is exhausted, the server will return the 503 (Service Temporarily Unavailable) error to all further requests. The rate is specified in requests per second (r/s). If a rate of less than one request per second is desired, it is specified in request per minute (r/m). For example, half-request per second is 30r/m. .El .Ss Module ngx_http_log_module .Bl -tag -width Ds .It Ic access_log Ar path Oo Ar format Oo Cm buffer Ns = Ns Ar size \ Oo Cm flush Ns = Ns Ar time Oc Oc Oc .It Ic access_log Ar path Ar format Cm gzip Ns Oo = Ns level Oc \ Oo Cm buffer Ns = Ns Ar size Oc Oo Cm flush Ns = Ns Ar time Oc .It Ic access_log Cm syslog : Ns Cm server Ns = Ns Ar address \ Oo , Ar parameter Ns = Ns Ar value Oc Oo Ar format Oc .It Ic access_log Cm off .Bl -tag -width Ds -compact .It default: Pa logs/access.log Cm combined .It context: Ic http , Ic server , Ic location , Ic if in location , Ic limit_except .El .Pp Sets the path, format, and configuration for a buffered log write. Several logs can be specified on the same level. Logging to syslog can be configured by specifying the .Cm syslog: prefix in the first parameter. The special value .Cm off cancels all .Ic access_log directives on the current level. If the format is not specified then the predefined combined format is used. If either the .Cm buffer or .Ic gzip (1.3.10, 1.2.7) parameter is used, writes to log will be buffered. The buffer size must not exceed the size of an atomic write to a disk file. For FreeBSD this size is unlimited. When buffering is enabled, the data will be written to the file: .Bl -bullet .It if the next log line does not fit into the buffer; .It if the buffered data is older than specified by the .Cm flush parameter (1.3.10, 1.2.7); .It when a worker process is re-opening log files or is shutting down. .El .Pp If the .Ic gzip parameter is used, then the buffered data will be compressed before writing to the file. The compression level can be set between 1 (fastest, less compression) and 9 (slowest, best compression). By default, the buffer size is equal to 64K bytes, and the compression level is set to 1. Since the data is compressed in atomic blocks, the log file can be decompressed or read by .Ic zcat at any time. Example: .Bd -literal -offset indent access_log /path/to/log.gz combined gzip flush=5m; .Ed .Pp For gzip compression to work, nginx must be built with the zlib library. The file path can contain variables (0.7.6+), but such logs have some constraints: .Bl -bullet .It the .Ar user whose credentials are used by worker processes should have permissions to create files in a directory with such logs; .It buffered writes do not work; .It the file is opened and closed for each log write. However, since the descriptors of frequently used files can be stored in a .Ic open_log_file_cache cache, writing to the old file can continue during the time specified by the .Ic open_log_file_cache directive's .Cm valid parameter .It during each log write the existence of the request's root directory is checked, and if it does not exist the log is not created. It is thus a good idea to specify both .Ic root and .Ic access_log on the same level: .Bd -literal -offset indent server { root /spool/vhost/data/$host; access_log /spool/vhost/logs/$host; ... .Ed .El .Pp The following parameters configure logging to syslog: .Bl -tag -width Ds .It Cm server Ns = Ns Ar address Defines the address of a syslog server. The address can be specified as a domain name, IP address, or a UNIX-domain socket path (specified after the .Cm unix: prefix). With a domain name or IP address, the port can be specified. If port is not specified, the port 514 is used. If a domain name resolves to several IP addresses, the first resolved address is used. .It Cm facility Ns = Ns Ar string Sets facility of syslog messages, as defined in RFC 3164. Facility can be one of .Cm kern , .Cm user , .Cm mail , .Cm daemon , .Cm auth , .Cm intern , .Cm lpr , .Cm news , .Cm uucp , .Cm clock , .Cm authpriv , .Cm ftp , .Cm ntp , .Cm audit , .Cm alert , .Cm cron , .Cm local0 No .. Cm local7 . Default is .Cm local7 . .It Cm severity Ns = Ns Ar string Sets severity of syslog messages, as defined in RFC 3164. Possible values are the same as for the second parameter (level) of the .Ic error_log directive. Default is .Cm info . .It Cm tag Ns = Ns Ar string Sets the tag of syslog messages. Default is .Qq nginx . .El .Pp Example syslog configuration: .Bd -literal -offset indent access_log syslog:server=192.168.1.1; access_log syslog:server=unix:/var/log/nginx.sock; access_log syslog:server=[2001:db8::1]:12345,facility=local7,tag=nginx,severity=info combined; .Ed .It Ic log_format Ar name Ar string No ... .Bl -tag -width Ds -compact .It default: combined Qq ... .It context: Ic http .El .Pp Specifies log format. The log format can contain common variables, and variables that exist only at the time of a log write: .Bl -tag -width Ds .It Va $bytes_sent the number of bytes sent to a client .It Va $connection connection serial number .It Va $connection_requests the current number of requests made through a connection (1.1.18) .It Va $msec time in seconds with a milliseconds resolution at the time of the log write .It Va $pipe .Qq p if request was pipelined, .Qo . Qc otherwise .It Va $request_length request length (including request line, header, and request body) .It Va $request_time request processing time in seconds with a milliseconds resolution; time elapsed between the first bytes were read from the client and the log write after the last bytes were sent to the client .It Va $status response status .It Va $time_iso8601 local time in the ISO 8601 standard format .It Va $time_local local time in the Common Log Format .El .Pp In the modern nginx versions variables .Va $status (1.3.2, 1.2.2), .Va $bytes_sent (1.3.8, 1.2.5), .Va $connection (1.3.8, 1.2.5), .Va $connection_requests (1.3.8, 1.2.5), .Va $msec (1.3.9, 1.2.6), .Va $request_time (1.3.9, 1.2.6), .Va $pipe (1.3.12, 1.2.7), .Va $request_length (1.3.12, 1.2.7), .Va $time_iso8601 (1.3.12, 1.2.7), and .Va $time_local (1.3.12, 1.2.7) are also available as common variables. Header lines sent to a client have the prefix sent_http_, for example, .Va $sent_http_content_range . The configuration always includes the predefined .Cm combined format: .Bd -literal -offset indent log_format combined '$remote_addr - $remote_user [$time_local] ' '"$request" $status $body_bytes_sent ' '"$http_referer" "$http_user_agent"'; .Ed .It Ic open_log_file_cache Cm max Ns = Ns Ar N Oo Cm inactive Ns = Ns Ar time Oc Oo Cm min_uses Ns = Ns Ar N Oc Oo Cm valid Ns = Ns Ar time Oc .It Ic open_log_file_cache Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Defines a cache that stores the file descriptors of frequently used logs whose names contain variables. The directive has the following parameters: .Bl -tag -width Ds .It Cm max sets the maximum number of descriptors in a cache; if the cache becomes full the least recently used (LRU) descriptors are closed .It Cm inactive sets the time after which the cached descriptor is closed if there were no access during this time; by default, 10 seconds .It Cm min_uses sets the minimum number of file uses during the time defined by the .Cm inactive parameter to let the descriptor stay open in a cache; by default, 1 .It Cm valid sets the time after which it should be checked that the file still exists with the same name; by default, 60 seconds .It Cm off disables caching .El .Pp Usage example: .Bd -literal -offset indent open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2; .Ed .El .Ss Module ngx_http_map_module .Bl -tag -width Ds .It Ic map Ar string Ar $variable Brq No ... .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp Creates a new variable whose value depends on values of one or more of the source variables specified in the first parameter. Before version 0.9.0 only a single variable could be specified in the first parameter. Since variables are evaluated only when they are used, the mere declaration even of a large number of .Ic map variables does not add any extra costs to request processing. Parameters inside the .Ic map block specify a mapping between source and resulting values. Source values are specified as strings or regular expressions (0.9.6). A regular expression should either start from the .Qq ~ symbol for a case-sensitive matching, or from the .Qq ~* symbols (1.0.4) for case-insensitive matching. A regular expression can contain named and positional captures that can later be used in other directives along with the resulting variable. If a source value matches one of the names of special parameters described below, it should be prefixed with the \\ symbol. The resulting value can be a string or another variable (0.9.0). The directive also supports three special parameters: .Bl -tag -width Ds .It Cm default Ar value sets the resulting value if the source value matches none of the specified variants. When .Cm default is not specified, the default resulting value will be an empty string. .It Cm hostnames indicates that source values can be hostnames with a prefix or suffix mask: .Bd -literal -offset indent *.example.com 1; example.* 1; .Ed .Pp The following two records .Bd -literal -offset indent example.com 1; *.example.com 1; .Ed .Pp can be combined: .Bd -literal -offset indent .example.com 1; .Ed .Pp This parameter should be specified before the list of values. .It Cm include Ar file includes a file with values. There can be several inclusions. .El .Pp If the source value matches more than one of the specified variants, e.g. both a mask and a regular expression match, the first matching variant will be chosen, in the following order of priority: .Bl -bullet .It string value without a mask .It longest string value with a prefix mask, e.g. .Qq *.example.com .It longest string value with a suffix mask, e.g. .Qq mail.* .It first matching regular expression (in order of appearance in a configuration file) .It default value .El .It Ic map_hash_bucket_size Ar size .Bl -tag -width Ds -compact .It default: 32 | 64 | 128 .It context: Ic http .El .Pp Sets the bucket size for the .Ic 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. .It Ic map_hash_max_size Ar size .Bl -tag -width Ds -compact .It default: 2048 .It context: Ic http .El .Pp Sets the maximum .Ar size of the .Ic map variables hash tables. The details of setting up hash tables are provided in a separate document. .El .Ss Module ngx_http_memcached_module .Bl -tag -width Ds .It Ic memcached_bind Ar address | Cm off .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Makes outgoing connections to a memcached server originate from the specified local IP .Ar address . Parameter value can contain variables (1.3.12). The special value .Cm off (1.3.12) cancels the effect of the .Ic memcached_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address. .It Ic memcached_buffer_size Ar size .Bl -tag -width Ds -compact .It default: 4k | 8k .It context: Ic http , Ic server , Ic location .El .Pp Sets the .Ar size of the buffer used for reading a response received from the memcached server. A response is passed to a client synchronously, as soon as it is received. .It Ic memcached_connect_timeout Ar time .Bl -tag -width Ds -compact .It default: 60s .It context: Ic http , Ic server , Ic location .El .Pp Defines a timeout for establishing a connection with a memcached server. It should be noted that this timeout cannot usually exceed 75 seconds. .It Ic memcached_gzip_flag Ar flag .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Enables the test for the .Ar flag presence in the memcached server response and sets the Content-Encoding response header field to .Ic gzip if the flag is set. .It Ic memcached_next_upstream Cm error | Cm timeout | Cm invalid_response | Cm not_found | Cm off No ... .Bl -tag -width Ds -compact .It default: Cm error Cm timeout .It context: Ic http , Ic server , Ic location .El .Pp Specifies in which cases a request should be passed to the next server: .Bl -tag -width Ds .It Cm error an error occurred while establishing a connection with the server, passing a request to it, or reading the response header; .It Cm timeout a timeout has occurred while establishing a connection with the server, passing a request to it, or reading the response header; .It Cm invalid_response a server returned an empty or invalid response; .It Cm not_found a response was not found on the server; .It Cm off disables passing a request to the next server. .El .Pp One should bear in mind that passing a request to the next server is only possible if nothing has been sent to a client yet. That is, if an error or timeout occurs in the middle of the transferring of a response, fixing this is impossible. The directive also defines what is considered an unsuccessful attempt of communication with a .Ic server . The cases of .Cm error , .Cm timeout and .Cm invalid_header are always considered unsuccessful attempts, even if they are not specified in the directive. The case of .Cm not_found is never considered an unsuccessful attempt. .It Ic memcached_pass Ar address .Bl -tag -width Ds -compact .It default: .It context: Ic location , Ic if in location .El .Pp Sets the memcached server address. The address can be specified as a domain name or an address, and a port: .Bd -literal -offset indent memcached_pass localhost:11211; .Ed .Pp or as a UNIX-domain socket path: .Bd -literal -offset indent memcached_pass unix:/tmp/memcached.socket; .Ed .Pp If a domain name resolves to several addresses, all of them will be used in a round-robin fashion. In addition, an address can be specified as a server group. .It Ic memcached_read_timeout Ar time .Bl -tag -width Ds -compact .It default: 60s .It context: Ic http , Ic server , Ic location .El .Pp Defines a timeout for reading a response from the memcached server. A timeout is set only between two successive read operations, not for the transmission of the whole response. If a memcached server does not transmit anything within this time, the connection is closed. .It Ic memcached_send_timeout Ar time .Bl -tag -width Ds -compact .It default: 60s .It context: Ic http , Ic server , Ic location .El .Pp Sets a timeout for transmitting a request to the memcached server. A timeout is set only between two successive write operations, not for the transmission of the whole request. If a memcached server does not receive anything within this time, a connection is closed. .El .Ss Module ngx_http_mp4_module .Em This module is not enabled on OpenBSD. .Bl -tag -width Ds .It Ic mp4 .Bl -tag -width Ds -compact .It default: .It context: Ic location .El .Pp Turns on module processing in a surrounding location. .It Ic mp4_buffer_size Ar size .Bl -tag -width Ds -compact .It default: 512K .It context: Ic http , Ic server , Ic location .El .Pp Sets the initial size of a memory buffer used for processing MP4 files. .It Ic mp4_max_buffer_size Ar size .Bl -tag -width Ds -compact .It default: 10M .It context: Ic http , Ic server , Ic location .El .Pp During metadata processing, a larger buffer may become necessary. Its size cannot exceed the specified .Ar size , or else nginx will return the 500 (Internal Server Error) server error, and log the following message: .Bd -literal -offset indent "/some/movie/file.mp4" mp4 moov atom is too large: 12583268, you may want to increase mp4_max_buffer_size .Ed .It Ic mp4_limit_rate Cm on | Cm off | Ar factor .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp .Em This directive is only available in the commercial version of nginx. .Pp Enables or disables rate limiting based on the average bitrate of the MP4 file served. To calculate the rate, the bitrate is multiplied by the specified .Ar factor . The special value .Cm on corresponds to the factor of 1.1. .It Ic mp4_limit_rate_after Ar time .Bl -tag -width Ds -compact .It default: 1m .It context: Ic http , Ic server , Ic location .El .Pp .Em This directive is only available in the commercial version of nginx. .Pp Limits the rate after sending the specified amount of media data. .El .Ss Module ngx_http_perl_module .Em This module is not enabled on OpenBSD. .Bl -tag -width Ds .It Ic perl Ar module Ns :: Ns Ar function | 'sub { ... }' .Bl -tag -width Ds -compact .It default: .It context: Ic location , Ic limit_except .El .Pp Sets a Perl handler for the given location. .It Ic perl_modules Ar path .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp Sets an additional path for Perl modules. .It Ic perl_require Ar module .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp Defines the name of a module that will be loaded during each reconfiguration. Several .Ic perl_require directives can be present. .It Ic perl_set Ar $variable Ar module Ns :: Ns Ar function | 'sub { ... }' .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp Installs a Perl handler for the specified variable. .El .Ss Module ngx_http_proxy_module .Bl -tag -width Ds .It Ic proxy_bind Ar address | Cm off .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Makes outgoing connections to a proxied server originate from the specified local IP .Ar address . Parameter value can contain variables (1.3.12). The special value .Cm off (1.3.12) cancels the effect of the .Ic proxy_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address. .It Ic proxy_buffer_size Ar size .Bl -tag -width Ds -compact .It default: 4k | 8k .It context: Ic http , Ic server , Ic location .El .Pp Sets the .Ar size of the buffer used for reading the first part of a response received from the proxied server. This part usually contains a small response header. By default, the buffer size is equal to the size of one buffer set by the .Ic proxy_buffers directive. It can be made smaller however. .It Ic proxy_buffering Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables buffering of responses from the proxied server. When buffering is enabled, nginx receives a response from the proxied server as soon as possible, saving it into the buffers set by the .Ic proxy_buffer_size and .Ic proxy_buffers directives. If the whole response does not fit into memory, a part of it can be saved to a .Ic proxy_temp_path temporary file on the disk. Writing to temporary files is controlled by the .Ic proxy_max_temp_file_size and .Ic proxy_temp_file_write_size directives. When buffering is disabled, a response is passed to a client synchronously, immediately as it is received. nginx will not try to read the whole response from the proxied server. The maximum size of the data that nginx can receive from the server at a time is set by the .Ic proxy_buffer_size directive. Buffering can also be enabled or disabled by passing .Cm yes or .Cm no in the X-Accel-Buffering response header field. This capability can be disabled using the .Ic proxy_ignore_headers directive. .It Ic proxy_buffers Ar number Ar size .Bl -tag -width Ds -compact .It default: 8 4k | 8k .It context: Ic http , Ic server , Ic location .El .Pp Sets the .Ar number and .Ar size of buffers used for reading a response from the proxied server, for a single connection. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform. .It Ic proxy_busy_buffers_size Ar size .Bl -tag -width Ds -compact .It default: 8k | 16k .It context: Ic http , Ic server , Ic location .El .Pp When buffering of responses from the proxied server is enabled, limits the total .Ar size of buffers that can be busy sending a response to the client while the response is not yet fully read. In the mean time, the rest of the buffers can be used for reading a response and, if needed, buffering part of a response to a temporary file. By default, .Ar size is limited by the size of two buffers set by the .Ic proxy_buffer_size and .Ic proxy_buffers directives. .It Ic proxy_cache Ar zone | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Defines a shared memory zone used for caching. The same zone can be used in several places. The .Cm off parameter disables caching inherited from the previous configuration level. .It Ic proxy_cache_bypass Ar string No ... .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp 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: .Bd -literal -offset indent proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment; proxy_cache_bypass $http_pragma $http_authorization; .Ed .Pp Can be used along with the .Ic proxy_no_cache directive. .It Ic proxy_cache_key Ar string .Bl -tag -width Ds -compact .It default: $scheme$proxy_host$request_uri .It context: Ic http , Ic server , Ic location .El .Pp Defines a key for caching, for example .Bd -literal -offset indent proxy_cache_key "$host$request_uri $cookie_user"; .Ed .Pp By default, the directive's value is close to the string .Bd -literal -offset indent proxy_cache_key $scheme$proxy_host$uri$is_args$args; .Ed .It Ic proxy_cache_lock Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp When enabled, only one request at a time will be allowed to populate a new cache element identified according to the .Ic 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 .Ic proxy_cache_lock_timeout directive. .It Ic proxy_cache_lock_timeout Ar time .Bl -tag -width Ds -compact .It default: 5s .It context: Ic http , Ic server , Ic location .El .Pp Sets a timeout for .Ic proxy_cache_lock . .It Ic proxy_cache_methods Cm GET | Cm HEAD | Cm POST No ... .Bl -tag -width Ds -compact .It default: Cm GET Cm HEAD .It context: Ic http , Ic server , Ic location .El .Pp If the client request method is listed in this directive then the response will be cached. .Cm GET and .Cm HEAD methods are always added to the list, though it is recommended to specify them explicitly. See also the .Ic proxy_no_cache directive. .It Ic proxy_cache_min_uses Ar number .Bl -tag -width Ds -compact .It default: 1 .It context: Ic http , Ic server , Ic location .El .Pp Sets the .Ar number of requests after which the response will be cached. .It Ic proxy_cache_path Ar path Oo Cm levels Ns = Ns Ar levels Oc Cm keys_zone Ns = Ns Ar name Ns : Ns Ar size Oo Cm inactive Ns = Ns Ar time Oc Oo Cm max_size Ns = Ns Ar size Oc Oo Cm loader_files Ns = Ns Ar number Oc Oo Cm loader_sleep Ns = Ns Ar time Oc Oo Cm loader_threshold Ns = Ns Ar time Oc .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp 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 .Ar levels parameter defines hierarchy levels of a cache. For example, in the following configuration .Bd -literal -offset indent proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m; .Ed .Pp file names in a cache will look like this: .Bd -literal -offset indent /data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c .Ed .Pp A cached response is first written to a temporary file, and then the file is renamed. Starting from version 0.8.9, temporary files and the cache can be put on different file systems. However, be aware that in this case a file is copied across two file systems instead of the cheap renaming operation. It is thus recommended that for any given location both cache and a directory holding temporary files, set by the .Ic proxy_temp_path directive, are put on the same file system. In addition, all active keys and information about data are stored in a shared memory zone, whose .Ar name and .Ar size are configured by the .Cm keys_zone parameter. Cached data that are not accessed during the time specified by the .Cm inactive parameter get removed from the cache regardless of their freshness. By default, .Cm inactive is set to 10 minutes. The special cache manager process monitors the maximum cache size set by the .Cm max_size parameter. When this size is exceeded, it removes the least recently used data. A minute after the start the special cache loader process is activated. It loads information about previously cached data stored on file system into a cache zone. The loading is done in iterations. During one iteration no more than .Cm loader_files items are loaded (by default, 100). Besides, the duration of one iteration is limited by the .Cm loader_threshold parameter (by default, 200 milliseconds). Between iterations, a pause configured by the .Cm loader_sleep parameter (by default, 50 milliseconds) is made. .It Ic proxy_cache_use_stale Cm error | Cm timeout | Cm invalid_header | Cm updating | Cm http_500 | Cm http_502 | Cm http_503 | Cm http_504 | Cm http_403 | Cm http_404 | Cm off No ... .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Determines in which cases a stale cached response can be used when an error occurs during communication with the proxied server. The directive's parameters match the parameters of the .Ic proxy_next_upstream directive. Additionally, the .Cm updating parameter permits using a stale cached response if it is currently being updated. This allows minimizing the number of accesses to proxied servers when updating cached data. To minimize the number of accesses to proxied servers when populating a new cache element, the .Ic proxy_cache_lock directive can be used. .It Ic proxy_cache_valid Oo Ar code No ... Oc Ar time .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Sets caching time for different response codes. For example, the following directives .Bd -literal -offset indent proxy_cache_valid 200 302 10m; proxy_cache_valid 404 1m; .Ed .Pp set 10 minutes of caching for responses with codes 200 and 302 and 1 minute for responses with code 404. If only caching .Ar time is specified .Bd -literal -offset indent proxy_cache_valid 5m; .Ed .Pp then only 200, 301, and 302 responses are cached. In addition, the .Cm any parameter can be specified to cache any responses: .Bd -literal -offset indent proxy_cache_valid 200 302 10m; proxy_cache_valid 301 1h; proxy_cache_valid any 1m; .Ed .Pp Parameters of caching can also be set directly in the response header. This has higher priority than setting of caching time using the directive. The X-Accel-Expires header field sets caching time of a response in seconds. The zero value disables caching for a response. If a value starts with the .Qq @ prefix, it sets an absolute time in seconds since Epoch, up to which the response may be cached. If header does not include the X-Accel-Expires field, parameters of caching may be set in the header fields Expires or Cache-Control. If a header includes the Set-Cookie field, such a response will not be cached. Processing of one or more of these response header fields can be disabled using the .Ic proxy_ignore_headers directive. .It Ic proxy_connect_timeout Ar time .Bl -tag -width Ds -compact .It default: 60s .It context: Ic http , Ic server , Ic location .El .Pp Defines a timeout for establishing a connection with a proxied server. It should be noted that this timeout cannot usually exceed 75 seconds. .It Ic proxy_cookie_domain Cm off .It Ic proxy_cookie_domain Ar domain Ar replacement .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Sets a text that should be changed in the .Ar 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 .Ar domain Ns = Ns localhost . The directive .Bd -literal -offset indent proxy_cookie_domain localhost example.org; .Ed .Pp will rewrite this attribute to .Ar domain Ns = Ns example.org . A dot at the beginning of the .Ar domain and .Ar replacement strings and the .Ar domain attribute is ignored. Matching is case-insensitive. The .Ar domain and .Ar replacement strings can contain variables: .Bd -literal -offset indent proxy_cookie_domain www.$host $host; .Ed .Pp The directive can also be specified using regular expressions. In this case, .Ar domain should start from the .Qq ~ symbol. A regular expression can contain named and positional captures, and .Ar replacement can reference them: .Bd -literal -offset indent proxy_cookie_domain ~\\.(?P[-0-9a-z]+\\.[a-z]+)$ $sl_domain; .Ed .Pp There could be several .Ic proxy_cookie_domain directives: .Bd -literal -offset indent proxy_cookie_domain localhost example.org; proxy_cookie_domain ~\\.([a-z]+\\.[a-z]+)$ $1; .Ed .Pp The .Cm off parameter cancels the effect of all .Ic proxy_cookie_domain directives on the current level: .Bd -literal -offset indent proxy_cookie_domain off; proxy_cookie_domain localhost example.org; proxy_cookie_domain www.example.org example.org; .Ed .It Ic proxy_cookie_path Cm off .It Ic proxy_cookie_path Ar path Ar replacement .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Sets a text that should be changed in the .Ar 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 .Ar path Ns = Ns /two/some/uri/ . The directive .Bd -literal -offset indent proxy_cookie_path /two/ /; .Ed .Pp will rewrite this attribute to .Ar path Ns = Ns /some/uri/ . The .Ar path and .Ar replacement strings can contain variables: .Bd -literal -offset indent proxy_cookie_path $uri /some$uri; .Ed .Pp The directive can also be specified using regular expressions. In this case, .Ar path should either start from the .Qq ~ symbol for a case-sensitive matching, or from the .Qq ~* symbols for case-insensitive matching. A regular expression can contain named and positional captures, and .Ar replacement can reference them: .Bd -literal -offset indent proxy_cookie_path ~*^/user/([^/]+) /u/$1; .Ed .Pp There could be several .Ic proxy_cookie_path directives: .Bd -literal -offset indent proxy_cookie_path /one/ /; proxy_cookie_path / /two/; .Ed .Pp The .Cm off parameter cancels the effect of all .Ic proxy_cookie_path directives on the current level: .Bd -literal -offset indent proxy_cookie_path off; proxy_cookie_path /two/ /; proxy_cookie_path ~*^/user/([^/]+) /u/$1; .Ed .It Ic proxy_headers_hash_bucket_size Ar size .Bl -tag -width Ds -compact .It default: 64 .It context: Ic http , Ic server , Ic location .El .Pp Sets the bucket .Ar size for hash tables used by the .Ic proxy_hide_header and .Ic proxy_set_header directives. The details of setting up hash tables are provided in a separate document. .It Ic proxy_headers_hash_max_size Ar size .Bl -tag -width Ds -compact .It default: 512 .It context: Ic http , Ic server , Ic location .El .Pp Sets the maximum .Ar size of hash tables used by the .Ic proxy_hide_header and .Ic proxy_set_header directives. The details of setting up hash tables are provided in a separate document. .It Ic proxy_hide_header Ar field .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp 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 .Ic 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 .Ic proxy_pass_header directive can be used. .It Ic proxy_http_version Cm 1.0 | Cm 1.1 .Bl -tag -width Ds -compact .It default: 1.0 .It context: Ic http , Ic server , Ic location .El .Pp Sets the HTTP protocol version for proxying. By default, version 1.0 is used. Version 1.1 is recommended for use with .Ic keepalive connections. .It Ic proxy_ignore_client_abort Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Determines whether the connection with a proxied server should be closed when a client closes a connection without waiting for a response. .It Ic proxy_ignore_headers Ar field No ... .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp 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 and Set-Cookie (0.8.44). If not disabled, processing of these header fields has the following effect: .Bl -bullet .It X-Accel-Expires, Expires, Cache-Control, and Set-Cookie set the parameters of response .Ic proxy_cache_valid caching; .It X-Accel-Redirect performs an .Ic internal redirect to the specified URI; .It X-Accel-Limit-Rate sets the .Ic limit_rate rate limit for transmission of a response to a client; .It X-Accel-Buffering enables or disables buffering of a response; .It X-Accel-Charset sets the desired .Ic charset of a response. .El .It Ic proxy_intercept_errors Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Determines whether proxied responses with codes greater than or equal to 300 should be passed to a client or be redirected to nginx for processing with the .Ic error_page directive. .It Ic proxy_max_temp_file_size Ar size .Bl -tag -width Ds -compact .It default: 1024m .It context: Ic http , Ic server , Ic location .El .Pp When buffering of responses from the proxied server is enabled, and the whole response does not fit into the memory buffers set by the .Ic proxy_buffer_size and .Ic proxy_buffers directives, a part of the response can be saved to a temporary file. This directive sets the maximum .Ar size of a temporary file. The size of data written to a temporary file at a time is set by the .Ic proxy_temp_file_write_size directive. The zero value disables buffering of responses to temporary files. .It Ic proxy_method Ar method .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Specifies the HTTP .Ar method to use in requests forwarded to the proxied server instead of the method from the client request. .It Ic proxy_next_upstream Cm error | Cm timeout | Cm invalid_header | Cm http_500 | Cm http_502 | Cm http_503 | Cm http_504 | Cm http_403 | Cm http_404 | Cm off No ... .Bl -tag -width Ds -compact .It default: Cm error Cm timeout .It context: Ic http , Ic server , Ic location .El .Pp Specifies in which cases a request should be passed to the next server: .Bl -tag -width Ds .It Cm error an error occurred while establishing a connection with the server, passing a request to it, or reading the response header; .It Cm timeout a timeout has occurred while establishing a connection with the server, passing a request to it, or reading the response header; .It Cm invalid_header a server returned an empty or invalid response; .It Cm http_500 a server returned a response with the code 500; .It Cm http_502 a server returned a response with the code 502; .It Cm http_503 a server returned a response with the code 503; .It Cm http_504 a server returned a response with the code 504; .It Cm http_403 a server returned a response with the code 403; .It Cm http_404 a server returned a response with the code 404; .It Cm off disables passing a request to the next server. .El .Pp One should bear in mind that passing a request to the next server is only possible if nothing has been sent to a client yet. That is, if an error or timeout occurs in the middle of the transferring of a response, fixing this is impossible. The directive also defines what is considered an unsuccessful attempt of communication with a .Ic server . The cases of .Cm error , .Cm timeout and .Cm invalid_header are always considered unsuccessful attempts, even if they are not specified in the directive. The cases of .Cm http_500 , .Cm http_502 , .Cm http_503 and .Cm http_504 are considered unsuccessful attempts only if they are specified in the directive. The cases of .Cm http_403 and .Cm http_404 are never considered unsuccessful attempts. .It Ic proxy_no_cache Ar string No ... .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp 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: .Bd -literal -offset indent proxy_no_cache $cookie_nocache $arg_nocache$arg_comment; proxy_no_cache $http_pragma $http_authorization; .Ed .Pp Can be used along with the .Ic proxy_cache_bypass directive. .It Ic proxy_pass Ar URL .Bl -tag -width Ds -compact .It default: .It context: Ic location , Ic if in location , Ic limit_except .El .Pp 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: .Bd -literal -offset indent proxy_pass http://localhost:8000/uri/; .Ed .Pp or as a UNIX-domain socket path specified after the word .Cm unix and enclosed in colons: .Bd -literal -offset indent proxy_pass http://unix:/tmp/backend.socket:/uri/; .Ed .Pp If a domain name resolves to several addresses, all of them will be used in a round-robin fashion. In addition, an address can be specified as a server group. A request URI is passed to the server as follows: .Bl -bullet .It If the .Ic proxy_pass directive is specified with a URI, then when a request is passed to the server, the part of a .Ic location normalized request URI matching the location is replaced by a URI specified in the directive: .Bd -literal -offset indent location /name/ { proxy_pass http://127.0.0.1/remote/; } .Ed .It If .Ic proxy_pass is specified without a URI, the request URI is passed to the server in the same form as sent by a client when the original request is processed, or the full normalized request URI is passed when processing the changed URI: .Bd -literal -offset indent location /some/path/ { proxy_pass http://127.0.0.1; } .Ed .Pp Before version 1.1.12, if .Ic proxy_pass is specified without a URI, the original request URI might be passed instead of the changed URI in some cases. .El .Pp In some cases, the part of a request URI to be replaced cannot be determined: .Bl -bullet .It When location is specified using a regular expression. In this case, the directive should be specified without a URI. .It When the URI is changed inside a proxied location using the .Ic rewrite directive, and this same configuration will be used to process a request .Pq Ic break : .Bd -literal -offset indent location /name/ { rewrite /name/([^/]+) /users?name=$1 break; proxy_pass http://127.0.0.1; } .Ed .Pp In this case, the URI specified in the directive is ignored and the full changed request URI is passed to the server. .El .Pp A server name, its port and the passed URI can also be specified using variables: .Bd -literal -offset indent proxy_pass http://$host$uri; .Ed .Pp or even like this: .Bd -literal -offset indent proxy_pass $request; .Ed .Pp In this case, the server name is searched among the described server groups, and, if not found, is determined using a .Ic resolver . WebSocket proxying requires special configuration and is supported since version 1.3.13. .It Ic proxy_pass_header Ar field .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Permits passing .Ic proxy_hide_header otherwise disabled header fields from a proxied server to a client. .It Ic proxy_read_timeout Ar time .Bl -tag -width Ds -compact .It default: 60s .It context: Ic http , Ic server , Ic location .El .Pp Defines a timeout for reading a response from the proxied server. A timeout is set only between two successive read operations, not for the transmission of the whole response. If a proxied server does not transmit anything within this time, a connection is closed. .It Ic proxy_pass_request_body Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp Indicates whether the original request body is passed to the proxied server. .Bd -literal -offset indent location /x-accel-redirect-here/ { proxy_method GET; proxy_pass_request_body off; proxy_set_header Content-Length ""; proxy_pass ... } .Ed .Pp See also the .Ic proxy_set_header and .Ic proxy_pass_request_headers directives. .It Ic proxy_pass_request_headers Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp Indicates whether the header fields of the original request are passed to the proxied server. .Bd -literal -offset indent location /x-accel-redirect-here/ { proxy_method GET; proxy_pass_request_headers off; proxy_pass_request_body off; proxy_pass ... } .Ed .Pp See also the .Ic proxy_set_header and .Ic proxy_pass_request_body directives. .It Ic proxy_redirect Cm default .It Ic proxy_redirect Cm off .It Ic proxy_redirect Ar redirect Ar replacement .Bl -tag -width Ds -compact .It default: Cm default .It context: Ic http , Ic server , Ic location .El .Pp 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 .Qq Location: http://localhost:8000/two/some/uri/ . The directive .Bd -literal -offset indent proxy_redirect http://localhost:8000/two/ http://frontend/one/; .Ed .Pp will rewrite this string to .Qq Location: http://frontend/one/some/uri/ . A server name may be omitted in the .Ar replacement string: .Bd -literal -offset indent proxy_redirect http://localhost:8000/two/ /; .Ed .Pp then the primary server's name and port, if different from 80, will be inserted. The default replacement specified by the .Cm default parameter uses the parameters of the .Ic location and .Ic proxy_pass directives. Hence, the two configurations below are equivalent: .Bd -literal -offset indent location /one/ { proxy_pass http://upstream:port/two/; proxy_redirect default; .Ed .Bd -literal -offset indent location /one/ { proxy_pass http://upstream:port/two/; proxy_redirect http://upstream:port/two/ /one/; .Ed .Pp The .Cm default parameter is not permitted if .Ic proxy_pass is specified using variables. A .Ar replacement string can contain variables: .Bd -literal -offset indent proxy_redirect http://localhost:8000/ http://$host:$server_port/; .Ed .Pp A .Ar redirect can also contain (1.1.11) variables: .Bd -literal -offset indent proxy_redirect http://$proxy_host:8000/ /; .Ed .Pp The directive can be specified (1.1.11) using regular expressions. In this case, .Ar redirect should either start with the .Qq ~ symbol for a case-sensitive matching, or with the .Qq ~* symbols for case-insensitive matching. A regular expression can contain named and positional captures, and .Ar replacement can reference them: .Bd -literal -offset indent proxy_redirect ~^(http://[^:]+):\\d+(/.+)$ $1$2; proxy_redirect ~*/user/([^/]+)/(.+)$ http://$1.example.com/$2; .Ed .Pp There could be several .Ic proxy_redirect directives: .Bd -literal -offset indent proxy_redirect default; proxy_redirect http://localhost:8000/ /; proxy_redirect http://www.example.com/ /; .Ed .Pp The .Cm off parameter cancels the effect of all .Ic proxy_redirect directives on the current level: .Bd -literal -offset indent proxy_redirect off; proxy_redirect default; proxy_redirect http://localhost:8000/ /; proxy_redirect http://www.example.com/ /; .Ed .Pp Using this directive, it is also possible to add host names to relative redirects issued by a proxied server: .Bd -literal -offset indent proxy_redirect / /; .Ed .It Ic proxy_send_lowat Ar size .Bl -tag -width Ds -compact .It default: 0 .It context: Ic http , Ic server , Ic location .El .Pp 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 .Dv NOTE_LOWAT flag of the .Cm kqueue method, or the .Dv SO_SNDLOWAT socket option, with the specified .Ar size . This directive is ignored on Linux, Solaris, and Windows. .It Ic proxy_send_timeout Ar time .Bl -tag -width Ds -compact .It default: 60s .It context: Ic http , Ic server , Ic location .El .Pp Sets a timeout for transmitting a request to the proxied server. A timeout is set only between two successive write operations, not for the transmission of the whole request. If a proxied server does not receive anything within this time, a connection is closed. .It Ic proxy_set_body Ar value .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Allows redefining the request body passed to the proxied server. A .Ar value can contain text, variables, and their combination. .It Ic proxy_set_header Ar field Ar value .Bl -tag -width Ds -compact .It default: Host $proxy_host .It context: Ic http , Ic server , Ic location .El .Pp Allows redefining or appending fields to the request header passed to the proxied server. A .Ar value can contain text, variables, and their combinations. These directives are inherited from the previous level if and only if there are no .Ic proxy_set_header directives defined on the current level. By default, only two fields are redefined: .Bd -literal -offset indent proxy_set_header Host $proxy_host; proxy_set_header Connection close; .Ed .Pp An unchanged Host request header field can be passed like this: .Bd -literal -offset indent proxy_set_header Host $http_host; .Ed .Pp However, if this field is not present in a client request header then nothing will be passed. In such a case it is better to use the .Va $host variable - its value equals the server name in the Host request header field or the primary server name if this field is not present: .Bd -literal -offset indent proxy_set_header Host $host; .Ed .Pp In addition, the server name can be passed together with the port of the proxied server: .Bd -literal -offset indent proxy_set_header Host $host:$proxy_port; .Ed .Pp If the value of a header field is an empty string then this field will not be passed to a proxied server: .Bd -literal -offset indent proxy_set_header Accept-Encoding ""; .Ed .It Ic proxy_ssl_ciphers Ar ciphers .Bl -tag -width Ds -compact .It default: Cm DEFAULT .It context: Ic http , Ic server , Ic location .El .Pp Specifies the enabled ciphers for requests to a proxied HTTPS server. The ciphers are specified in the format understood by the OpenSSL library. The full list can be viewed using the .Ic openssl ciphers command. .It Ic proxy_ssl_session_reuse Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp Determines whether SSL sessions can be reused when working with the proxied server. If the errors SSL3_GET_FINISHED:digest check failed appear in the logs, try disabling session reuse. .It Ic proxy_ssl_protocols Oo Cm SSLv2 Oc Oo Cm SSLv3 Oc Oo Cm TLSv1 Oc Oo Cm TLSv1.1 Oc Oo Cm TLSv1.2 Oc .Bl -tag -width Ds -compact .It default: SSLv3 TLSv1 TLSv1.1 TLSv1.2 .It context: Ic http , Ic server , Ic location .El .Pp Enables the specified protocols for requests to a proxied HTTPS server. .It Ic proxy_store Cm on | Cm off | Ar string .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables saving of files to a disk. The .Cm on parameter saves files with paths corresponding to the directives .Ic alias or .Ic root . The .Cm off parameter disables saving of files. In addition, the file name can be set explicitly using the .Ar string with variables: .Bd -literal -offset indent proxy_store /data/www$original_uri; .Ed .Pp The modification time of files is set according to the received Last-Modified response header field. A response is first written to a temporary file, and then the file is renamed. Starting from version 0.8.9, temporary files and the persistent store can be put on different file systems. However, be aware that in this case a file is copied across two file systems instead of the cheap renaming operation. It is thus recommended that for any given location both saved files and a directory holding temporary files, set by the .Ic proxy_temp_path directive, are put on the same file system. This directive can be used to create local copies of static unchangeable files, e.g.: .Bd -literal -offset indent location /images/ { root /data/www; open_file_cache_errors off; error_page 404 = /fetch$uri; } location /fetch/ { internal; proxy_pass http://backend/; proxy_store on; proxy_store_access user:rw group:rw all:r; proxy_temp_path /data/temp; alias /data/www/; } .Ed .Pp or like this: .Bd -literal -offset indent location /images/ { root /data/www; error_page 404 = @fetch; } location @fetch { internal; proxy_pass http://backend; proxy_store on; proxy_store_access user:rw group:rw all:r; proxy_temp_path /data/temp; root /data/www; } .Ed .It Ic proxy_store_access Ar users Ns : Ns Ar permissions No ... .Bl -tag -width Ds -compact .It default: user:rw .It context: Ic http , Ic server , Ic location .El .Pp Sets access permissions for newly created files and directories, e.g.: .Bd -literal -offset indent proxy_store_access user:rw group:rw all:r; .Ed .Pp If any .Ar group or .Cm all access permissions are specified then .Ar user permissions may be omitted: .Bd -literal -offset indent proxy_store_access group:rw all:r; .Ed .It Ic proxy_temp_file_write_size Ar size .Bl -tag -width Ds -compact .It default: 8k | 16k .It context: Ic http , Ic server , Ic location .El .Pp Limits the .Ar 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, .Ar size is limited by two buffers set by the .Ic proxy_buffer_size and .Ic proxy_buffers directives. The maximum size of a temporary file is set by the .Ic proxy_max_temp_file_size directive. .It Ic proxy_temp_path Ar path Oo Ar level1 Oo Ar level2 Oo Ar level3 Oc Oc Oc .Bl -tag -width Ds -compact .It default: proxy_temp .It context: Ic http , Ic server , Ic location .El .Pp 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 .Bd -literal -offset indent proxy_temp_path /spool/nginx/proxy_temp 1 2; .Ed .Pp a temporary file might look like this: .Bd -literal -offset indent /spool/nginx/proxy_temp/7/45/00000123457 .Ed .El .Ss Module ngx_http_random_index_module .Em This module is not enabled on OpenBSD. .Bl -tag -width Ds .It Ic random_index Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic location .El .Pp Enables or disables module processing in a surrounding location. .El .Ss Module ngx_http_realip_module .Em This module is not enabled on OpenBSD. .Bl -tag -width Ds .It Ic set_real_ip_from Ar address | Ar CIDR | Cm unix: .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Defines trusted addresses that are known to send correct replacement addresses. If the special value .Cm unix: is specified, all UNIX-domain sockets will be trusted. IPv6 addresses are supported starting from versions 1.3.0 and 1.2.1. .It Ic real_ip_header Ar field | Cm X-Real-IP | Cm X-Forwarded-For .Bl -tag -width Ds -compact .It default: X-Real-IP .It context: Ic http , Ic server , Ic location .El .Pp Defines a request header field used to send the address for a replacement. .It Ic real_ip_recursive Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp 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 .Ic 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. .El .Ss Module ngx_http_referer_module .Bl -tag -width Ds .It Ic referer_hash_bucket_size Ar size .Bl -tag -width Ds -compact .It default: 64 .It context: Ic server , Ic location .El .Pp Sets the bucket size for the valid referers hash tables. The details of setting up hash tables are provided in a separate document. .It Ic referer_hash_max_size Ar size .Bl -tag -width Ds -compact .It default: 2048 .It context: Ic server , Ic location .El .Pp Sets the maximum .Ar size of the valid referers hash tables. The details of setting up hash tables are provided in a separate document. .It Ic valid_referers Cm none | Cm blocked | Cm server_names | Ar string No ... .Bl -tag -width Ds -compact .It default: .It context: Ic server , Ic location .El .Pp Specifies the Referer request header field values that will cause the embedded .Va $invalid_referer variable to be set to an empty string. Otherwise, the variable will be set to 1. Search for a match is case-insensitive. Parameters can be as follows: .Bl -tag -width Ds .It Cm none the Referer field is missing in the request header; .It Cm blocked the Referer field is present in the request header, but its value has been deleted by a firewall or proxy server; such values are strings that do not start with .Qq http:// or .Qq https:// ; .It Cm server_names the Referer request header field contains one of the server names; .It Ar arbitrary string defines a server name and an optional URI prefix. A server name can have an .Qq * at the beginning or end. During the checking, the server's port in the Referer field is ignored; .It Ar regular expression the first symbol should be a .Qq ~ . It should be noted that an expression will be matched against the text starting after the .Qq http:// or .Qq https:// . .El .Pp Example: .Bd -literal -offset indent valid_referers none blocked server_names *.example.com example.* www.example.org/galleries/ ~\\.google\\.; .Ed .El .Ss Module ngx_http_rewrite_module .Bl -tag -width Ds .It Ic break .Bl -tag -width Ds -compact .It default: .It context: Ic server , Ic location , Ic if .El .Pp Stops processing the current set of .Sx Module ngx_http_rewrite_module directives. Example: .Bd -literal -offset indent if ($slow) { limit_rate 10k; break; } .Ed .It Ic if Po Ar condition Pc Brq No ... .Bl -tag -width Ds -compact .It default: .It context: Ic server , Ic location .El .Pp The specified .Ar condition is evaluated. If true, this module directives specified inside the braces are executed, and the request is assigned the configuration inside the .Ic if directive. Configurations inside the .Ic if directives are inherited from the previous configuration level. A condition may be any of the following: .Bl -bullet .It a variable name; false if the value of a variable is an empty string or 0; Before version 1.0.1, any string starting with 0 was considered a false value. .It comparison of a variable with a string using the .Qq = and .Qq != operators; .It matching of a variable against a regular expression using the .Qq ~ (for case-sensitive matching) and .Qq ~* (for case-insensitive matching) operators. Regular expressions can contain captures that are made available for later reuse in the .Va $1 No .. Va $9 variables. Negative operators .Qq !~ and .Qq !~* are also available. If a regular expression includes the .Qq } or .Qo ; Qc characters, the whole expressions should be enclosed in single or double quotes. .It checking of a file existence with the .Fl f and .Ic !-f operators; .It checking of a directory existence with the .Fl d and .Ic !-d operators; .It checking of a file, directory, or symbolic link existence with the .Fl e and .Ic !-e operators; .It checking for an executable file with the .Fl x and .Ic !-x operators. .El .Pp Examples: .Bd -literal -offset indent if ($http_user_agent ~ MSIE) { rewrite ^(.*)$ /msie/$1 break; } if ($http_cookie ~* "id=([^;]+)(?:; |$)") { set $id $1; } if ($request_method = POST) { return 405; } if ($slow) { limit_rate 10k; } if ($invalid_referer) { return 403; } .Ed .Pp A value of the .Va $invalid_referer embedded variable is set by the .Ic valid_referers directive. .It Ic return Ar code Oo Ar text Oc .It Ic return Ar code Ar URL .It Ic return Ar URL .Bl -tag -width Ds -compact .It default: .It context: Ic server , Ic location , Ic if .El .Pp Stops processing and returns the specified .Ar code to a client. The non-standard code 444 closes a connection without sending a response header. Starting from version 0.8.42, it is possible to specify either a redirect URL (for codes 301, 302, 303, and 307), or the response body .Ar text (for other codes). A response body text and redirect URL can contain variables. As a special case, a redirect URL can be specified as a URI local to this server, in which case the full redirect URL is formed according to the request scheme .Pq Va $scheme and the .Ic server_name_in_redirect and .Ic port_in_redirect directives. In addition, a .Ar URL for temporary redirect with the code 302 can be specified as the sole parameter. Such a parameter should start with the .Qq http:// , .Qq https:// , or .Ic $scheme string. A .Ar URL can contain variables. Only the following codes could be returned before version 0.7.51: 204, 400, 402 - 406, 408, 410, 411, 413, 416, and 500 - 504. The code 307 was not treated as a redirect until versions 1.1.16 and 1.0.13. .It Ic rewrite Ar regex Ar replacement Oo Ar flag Oc .Bl -tag -width Ds -compact .It default: .It context: Ic server , Ic location , Ic if .El .Pp If the specified regular expression matches a URI, the URI is changed as specified in the .Ar replacement string. The .Ic 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 .Qq http:// or .Qq https:// , the processing stops and the redirect is returned to a client. An optional .Ar flag parameter can be one of: .Bl -tag -width Ds .It Cm last stops processing the current set of .Sx Module ngx_http_rewrite_module directives and starts a search for a new location matching the changed URI; .It Cm break stops processing the current set of .Sx Module ngx_http_rewrite_module directives; .It Cm redirect returns a temporary redirect with the 302 code; used if a replacement string does not start with .Qq http:// or .Qq https:// ; .It Cm permanent returns a permanent redirect with the 301 code. .El .Pp The full redirect URL is formed according to the request scheme .Pq Va $scheme and the .Ic server_name_in_redirect and .Ic port_in_redirect directives. Example: .Bd -literal -offset indent server { ... rewrite ^(/download/.*)/media/(.*)\\..*$ $1/mp3/$2.mp3 last; rewrite ^(/download/.*)/audio/(.*)\\..*$ $1/mp3/$2.ra last; return 403; ... } .Ed .Pp But if these directives are put inside the .Qq /download/ location, the .Cm last flag should be replaced by .Ic break , or otherwise nginx will make 10 cycles and return the 500 error: .Bd -literal -offset indent location /download/ { rewrite ^(/download/.*)/media/(.*)\\..*$ $1/mp3/$2.mp3 break; rewrite ^(/download/.*)/audio/(.*)\\..*$ $1/mp3/$2.ra break; return 403; } .Ed .Pp If a .Ar replacement string includes the new request arguments, the previous request arguments are appended after them. If this is undesired, putting a question mark at the end of a replacement string avoids having them appended, for example: .Bd -literal -offset indent rewrite ^/users/(.*)$ /show?user=$1? last; .Ed .Pp If a regular expression includes the .Qq } or .Qo ; Qc characters, the whole expressions should be enclosed in single or double quotes. .It Ic rewrite_log Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location , Ic if .El .Pp Enables or disables logging of .Sx Module ngx_http_rewrite_module module directives processing results into the .Ic error_log at the .Cm notice level. .It Ic set Ar variable Ar value .Bl -tag -width Ds -compact .It default: .It context: Ic server , Ic location , Ic if .El .Pp Sets a .Ar value for the specified .Ar variable. A .Ar value can contain text, variables, and their combination. .It Ic uninitialized_variable_warn Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location , Ic if .El .Pp Controls whether warnings about uninitialized variables are logged. .El .Ss Module ngx_http_secure_link_module .Em This module is not enabled on OpenBSD. .Bl -tag -width Ds .It Ic secure_link Ar expression .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Defines a string with variables from which the checksum value and lifetime of a link will be extracted. Variables used in an .Ar expression are usually associated with a request; see .Ic secure_link_md5 example below. The checksum value extracted from the string is compared with the MD5 hash value of the expression defined by the .Ic secure_link_md5 directive. If the checksums are different, the .Va $secure_link variable is set to an empty string. If the checksums are the same, the link lifetime is checked. If the link has a limited lifetime and the time has expired, the .Va $secure_link variable is set to 0. Otherwise, it is set to 1. The MD5 hash value passed in a request is encoded in base64url. If a link has a limited lifetime, the expiration time is set in seconds since Epoch (Thu, 01 Jan 1970 00:00:00 GMT). The value is specified in the expression after the MD5 hash, and is separated by a comma. The expiration time passed in a request is available through the .Va $secure_link_expires variable for a use in the .Ic secure_link_md5 directive. If the expiration time is not specified, a link has the unlimited lifetime. .It Ic secure_link_md5 Ar expression .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Defines an expression for which the MD5 hash value will be computed and compared with the value passed in a request. The expression should contain the secured part of a link (resource) and a secret ingredient. If the link has a limited lifetime, the expression should also contain .Va $secure_link_expires . To prevent unauthorized access, the expression may contain some information about the client, such as its address and browser version. Example: .Bd -literal -offset indent location /s/ { secure_link $arg_md5,$arg_expires; secure_link_md5 "$secure_link_expires$uri$remote_addr secret"; if ($secure_link = "") { return 403; } if ($secure_link = "0") { return 410; } ... } .Ed .Pp The .Qq /s/link?md5 Ns = Ns _e4Nc3iduzkWRm01TBBNYw&expires Ns = Ns 2147483647 link restricts access to .Qq /s/link for the client with the IP address 127.0.0.1. The link also has the limited lifetime until January 19, 2038 (GMT). On UNIX, the .Ar md5 request argument value can be obtained as: .Bd -literal -offset indent echo -n '2147483647/s/link127.0.0.1 secret' | \\ openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d = .Ed .It Ic secure_link_secret Ar word .Bl -tag -width Ds -compact .It default: .It context: Ic location .El .Pp Defines a secret .Ar word used to check authenticity of requested links. The full URI of a requested link looks as follows: .Bd -literal -offset indent /prefix/hash/link .Ed .Pp where .Ar hash is a hexadecimal representation of the MD5 hash computed for the concatenation of the link and secret word, and .Ar prefix is an arbitrary string without slashes. If the requested link passes the authenticity check, the .Va $secure_link variable is set to the link extracted from the request URI. Otherwise, the .Va $secure_link variable is set to an empty string. Example: .Bd -literal -offset indent location /p/ { secure_link_secret secret; if ($secure_link = "") { return 403; } rewrite ^ /secure/$secure_link; } location /secure/ { internal; } .Ed .Pp A request of .Qq /p/5e814704a28d9bc1914ff19fa0c4a00a/link will be internally redirected to .Qq /secure/link . On UNIX, the hash value for this example can be obtained as: .Bd -literal -offset indent echo -n 'linksecret' | openssl md5 -hex .Ed .El .Ss Module ngx_http_session_log_module .Em This module is only available in the commercial version of nginx. .Bl -tag -width Ds .It Ic session_log_format Ar name Ar string No ... .Bl -tag -width Ds -compact .It default: combined Qq ... .It context: Ic http .El .Pp Specifies the output format of a log. The value of the .Va $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. .It Ic session_log_zone Ar path Cm zone Ns = Ns Ar name Ns : Ns Ar size Oo Cm format Ns = Ns Ar format Oc Oo Cm timeout Ns = Ns Ar time Oc Oo Cm id Ns = Ns Ar id Oc Oo Cm md5 Ns = Ns Ar md5 Oc .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp Sets the path to a log file and configures the shared memory zone that is used to store currently active sessions. A session is considered active for as long as the time elapsed since the last request in the session does not exceed the specified .Cm timeout (by default, 30 seconds). Once a session is no longer active, it is written to the log. The .Ar id parameter identifies the session to which a request is mapped. The .Ar id parameter is set to the hexadecimal representation of an MD5 hash (for example, obtained from a cookie using variables). If this parameter is not specified or does not represent the valid MD5 hash, nginx computes the MD5 hash from the value of the .Ar md5 parameter and creates a new session using this hash. Both the .Ar id and .Ar md5 parameters can contain variables. The .Ar format parameter sets the custom session log format configured by the .Ic session_log_format directive. If .Ar format is not specified, the predefined combined format is used. .It Ic session_log Ar name | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables the use of the specified session log. The special value .Cm off cancels all .Ic session_log directives inherited from the previous configuration level. .El .Ss Module ngx_http_spdy_module .Em This module is not enabled on OpenBSD. .Bl -tag -width Ds .It Ic spdy_headers_comp Ar level .Bl -tag -width Ds -compact .It default: 0 .It context: Ic http , Ic server .El .Pp Sets the header compression .Ar level of a response in a range from 1 (fastest, less compression) to 9 (slowest, best compression). The special value 0 turns off the header compression. .El .Ss Module ngx_http_split_clients_module .Bl -tag -width Ds .It Ic split_clients Ar string Ar $variable Brq No ... .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp Creates a variable for A/B testing, for example: .Bd -literal -offset indent split_clients "${remote_addr}AAA" $variant { 0.5% .one; 2.0% .two; * ""; } .Ed .Pp The value of the original string is hashed using MurmurHash2. In the example given, hash values from 0 to 21474835 (0.5%) correspond to the value .Qq .one of the .Va $variant variable, hash values from 21474836 to 107374180 (2%) correspond to the value .Qq .two , and hash values from 107374181 to 4294967295 correspond to the value .Qq (an empty string). .El .Ss Module ngx_http_ssi_module .Bl -tag -width Ds .It Ic ssi Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location , Ic if in location .El .Pp Enables or disables processing of SSI commands in responses. .It Ic ssi_last_modified Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Allows preserving the Last-Modified header field from the original response during SSI processing to facilitate response caching. By default, the header field is removed as contents of the response are modified during processing and may contain dynamically generated elements or parts that are changed independently of the original response. .It Ic ssi_min_file_chunk Cm size .Bl -tag -width Ds -compact .It default: 1k .It context: Ic http , Ic server , Ic location .El .Pp Sets the minimum .Ar size for parts of a response stored on disk, starting from which it makes sense to send them using .Ic sendfile . .It Ic ssi_silent_errors Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp If enabled, suppresses the output of the .Qq an error occurred while processing the directive string if an error occurred during SSI processing. .It Ic ssi_types Ar mime-type No ... .Bl -tag -width Ds -compact .It default: text/html .It context: Ic http , Ic server , Ic location .El .Pp Enables processing of SSI commands in responses with the specified MIME types in addition to text/html. The special value .Qq * matches any MIME type (0.8.29). .It Ic ssi_value_length Ar length .Bl -tag -width Ds -compact .It default: 256 .It context: Ic http , Ic server , Ic location .El .Pp Sets the maximum length of parameter values in SSI commands. .El .Ss Module ngx_http_ssl_module .Bl -tag -width Ds .It Ic ssl Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server .El .Pp Enables the HTTPS protocol for the given virtual server. It is recommended to use the .Ar ssl parameter of the .Ic listen directive instead of this directive. .It Ic ssl_certificate Ar file .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server .El .Pp Specifies a .Ar 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. It should be kept in mind that due to the HTTPS protocol limitations virtual servers should listen on different IP addresses: .Bd -literal -offset indent server { listen 192.168.1.1:443; server_name one.example.com; ssl_certificate /usr/local/nginx/conf/one.example.com.cert; ... } server { listen 192.168.1.2:443; server_name two.example.com; ssl_certificate /usr/local/nginx/conf/two.example.com.cert; ... } .Ed .Pp otherwise the first server's certificate will be issued for the second site. .It Ic ssl_certificate_key Ar file .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server .El .Pp Specifies a .Ar file with the secret key in the PEM format for the given virtual server. .It Ic ssl_ciphers Ar ciphers .Bl -tag -width Ds -compact .It default: HIGH:!aNULL:!MD5 .It context: Ic http , Ic server .El .Pp Specifies the enabled ciphers. The ciphers are specified in the format understood by the OpenSSL library, for example: .Bd -literal -offset indent ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP; .Ed .Pp The full list can be viewed using the .Ic openssl ciphers command. The previous versions of nginx used different ciphers by default. .It Ic ssl_client_certificate Ar file .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server .El .Pp Specifies a .Ar file with trusted CA certificates in the PEM format used to verify client certificates and OCSP responses if .Ic ssl_stapling is enabled. The list of certificates will be sent to clients. If this is not desired, the .Ic ssl_trusted_certificate directive can be used. .It Ic ssl_crl Ar file .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server .El .Pp Specifies a .Ar file with revoked certificates (CRL) in the PEM format used to verify client certificates. .It Ic ssl_dhparam Ar file .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server .El .Pp Specifies a .Ar file with DH parameters for EDH ciphers. .It Ic ssl_prefer_server_ciphers Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server .El .Pp Specifies that server ciphers should be preferred over client ciphers when using the SSLv3 and TLS protocols. .It Ic ssl_protocols Oo Cm SSLv2 Oc Oo Cm SSLv3 Oc Oo Cm TLSv1 Oc Oo Cm TLSv1.1 Oc Oo Cm TLSv1.2 Oc .Bl -tag -width Ds -compact .It default: SSLv3 TLSv1 TLSv1.1 TLSv1.2 .It context: Ic http , Ic server .El .Pp Enables the specified protocols. The .Cm TLSv1.1 and .Cm TLSv1.2 parameters work only when the OpenSSL library of version 1.0.1 or higher is used. The .Cm TLSv1.1 and .Cm TLSv1.2 parameters are supported starting from versions 1.1.13 and 1.0.12, so when the OpenSSL version 1.0.1 or higher is used on older nginx versions, these protocols work, but cannot be disabled. .It Ic ssl_session_cache Cm off | Cm none | \ Oo Cm builtin Ns Oo : Ns Ar size Oc Oc Oo Cm shared: Ar name: Ar size Oc .Bl -tag -width Ds -compact .It default: Cm none .It context: Ic http , Ic server .El .Pp Sets the types and sizes of caches that store session parameters. A cache can be of any of the following types: .Bl -tag -width Ds .It Cm off the use of a session cache is strictly prohibited: nginx explicitly tells a client that sessions may not be reused. .It Cm none the use of a session cache is gently disallowed: nginx tells a client that sessions may be reused, but does not actually store session parameters in the cache. .It Cm builtin a cache built in OpenSSL; used by one worker process only. The cache size is specified in sessions. If size is not given, it is equal to 20480 sessions. Use of the built-in cache can cause memory fragmentation. .It Cm shared a cache shared between all worker processes. The cache size is specified in bytes; one megabyte can store about 4000 sessions. Each shared cache should have an arbitrary name. A cache with the same name can be used in several virtual servers. .El .Pp Both cache types can be used simultaneously, for example: .Bd -literal -offset indent ssl_session_cache builtin:1000 shared:SSL:10m; .Ed .Pp but using only shared cache without the built-in cache should be more efficient. .It Ic ssl_session_timeout Ar time .Bl -tag -width Ds -compact .It default: 5m .It context: Ic http , Ic server .El .Pp Specifies a time during which a client may reuse the session parameters stored in a cache. .It Ic ssl_stapling Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server .El .Pp Enables or disables stapling of OCSP responses by the server. Example: .Bd -literal -offset indent ssl_stapling on; resolver 192.0.2.1; .Ed .Pp For the OCSP stapling to work, the certificate of the server certificate issuer should be known. If the .Ic ssl_certificate file does not contain intermediate certificates, the certificate of the server certificate issuer should be present in the .Ic ssl_trusted_certificate file. For a resolution of the OCSP responder hostname, the .Ic resolver directive should also be specified. .It Ic ssl_stapling_file Ar file .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server .El .Pp When set, the stapled OCSP response will be taken from the specified .Ar file instead of querying the OCSP responder specified in the server certificate. The file should be in the DER format as produced by the .Ic openssl ocsp command. .It Ic ssl_stapling_responder Ar url .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server .El .Pp Overrides the URL of the OCSP responder specified in the Authority Information Access certificate extension. Only .Qq http:// OCSP responders are supported: .Bd -literal -offset indent ssl_stapling_responder http://ocsp.example.com/; .Ed .It Ic ssl_stapling_verify Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server .El .Pp Enables or disables verification of OCSP responses by the server. For verification to work, the certificate of the server certificate issuer, the root certificate, and all intermediate certificates should be configured as trusted using the .Ic ssl_trusted_certificate directive. .It Ic ssl_trusted_certificate Ar file .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server .El .Pp Specifies a .Ar file with trusted CA certificates in the PEM format used to verify client certificates and OCSP responses if .Ic ssl_stapling is enabled. In contrast to the certificate set by .Ic ssl_client_certificate , the list of these certificates will not be sent to clients. .It Ic ssl_verify_client Cm on | Cm off | Cm optional | Cm optional_no_ca .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server .El .Pp Enables verification of client certificates. The verification result is stored in the .Va $ssl_client_verify variable. The .Cm optional parameter (0.8.7+) requests the client certificate and verifies it if the certificate is present. The .Cm optional_no_ca parameter (1.3.8, 1.2.5) requests the client certificate but does not require it to be signed by a trusted CA certificate. This is intended for the use in cases when a service that is external to nginx performs the actual certificate verification. The contents of the certificate is accessible through the .Va $ssl_client_cert variable. .It Ic ssl_verify_depth Ar number .Bl -tag -width Ds -compact .It default: 1 .It context: Ic http , Ic server .El .Pp Sets the verification depth in the client certificates chain. .El .Ss Module ngx_http_status_module .Em This module is only available in the commercial version of nginx. .Bl -tag -width Ds .It Ic status .Bl -tag -width Ds -compact .It default: .It context: Ic location .El .Pp The status information will be accessible from the surrounding location. .It Ic status_format Cm json .It Ic status_format Cm jsonp Oo Ar callback Oc .Bl -tag -width Ds -compact .It default: json .It context: Ic http , Ic server , Ic location .El .Pp By default, status information is output in the JSON format. Alternatively, data may be output as JSONP. The .Ar callback parameter specifies the name of a callback function. The value can contain variables. If parameter is omitted, or the computed value is an empty string, then .Sx Module ngx_status_jsonp_callback is used. .El .Ss Module ngx_http_stub_status_module .Bl -tag -width Ds .It Ic stub_status Cm on .Bl -tag -width Ds -compact .It default: .It context: Ic location .El .Pp The status information will be accessible from the surrounding location. .El .Ss Module ngx_http_sub_module .Em This module is not enabled on OpenBSD. .Bl -tag -width Ds .It Ic sub_filter Ar string Ar replacement .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Sets a string to replace and a replacement string. The string to replace is matched ignoring the case. The replacement string can contain variables. .It Ic sub_filter_last_modified Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Allows preserving the Last-Modified header field from the original response during replacement to facilitate response caching. By default, the header field is removed as contents of the response are modified during processing. .It Ic sub_filter_once Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm on .It context: Ic http , Ic server , Ic location .El .Pp Indicates whether to look for a string to replace once or several times. .It Ic sub_filter_types Ar mime-type No ... .Bl -tag -width Ds -compact .It default: text/html .It context: Ic http , Ic server , Ic location .El .Pp Enables string replacement in responses with the specified MIME types in addition to .Ar text/html . The special value .Qq * matches any MIME type (0.8.29). .El .Ss Module ngx_http_upstream_module .Bl -tag -width Ds .It Ic upstream Ar name Brq No ... .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp Defines a group of servers. Servers can listen on different ports. In addition, servers listening on TCP and UNIX-domain sockets can be mixed. Example: .Bd -literal -offset indent upstream backend { server backend1.example.com weight=5; server 127.0.0.1:8080 max_fails=3 fail_timeout=30s; server unix:/tmp/backend3; } .Ed .Pp By default, requests are distributed between the servers using a weighted round-robin balancing method. In the above example, each 7 requests will be distributed as follows: 5 requests go to backend1.example.com and one request to each of the second and third servers. If an error occurs during communication with a server, the request will be passed to the next server, and so on until all of the functioning servers will be tried. If a successful response could not be obtained from any of the servers, the client will receive the result of the communication with the last server. .It Ic server Ar address Oo Ar parameters Oc .Bl -tag -width Ds -compact .It default: .It context: Ic upstream .El .Pp Defines the .Ar address and other .Ar 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 .Cm unix: prefix. If a port is not specified, the port 80 is used. A domain name that resolves to several IP addresses defines multiple servers at once. The following parameters can be defined: .Bl -tag -width Ds .It Cm weight Ns = Ns Ar number sets the weight of the server, by default, 1. .It Cm max_fails Ns = Ns Ar number sets the number of unsuccessful attempts to communicate with the server that should happen in the duration set by the .Cm fail_timeout parameter to consider the server unavailable for a duration also set by the .Cm fail_timeout parameter. By default, the number of unsuccessful attempts is set to 1. The zero value disables the accounting of attempts. What is considered an unsuccessful attempt is defined by the .Ic proxy_next_upstream , .Ic fastcgi_next_upstream , and .Ic memcached_next_upstream directives. .It Cm fail_timeout Ns = Ns Ar time sets .Bl -bullet .It the time during which the specified number of unsuccessful attempts to communicate with the server should happen to consider the server unavailable; .It and the period of time the server will be considered unavailable. .El .Pp By default, the parameter is set to 10 seconds. .It Cm slow_start Ns = Ns Ar time sets the .Ar time during which the server will recover its weight from zero to a nominal value, when unhealthy server becomes healthy, or when the server becomes available after a period of time it was considered unavailable. Default value is zero, i.e. slow start is disabled. .Pp .Em This option is only available in the commercial version of nginx. .It Cm backup marks the server as a backup server. It will be passed requests when the primary servers are unavailable. .It Cm down marks the server as permanently unavailable; used along with the .Ic ip_hash directive. .It Cm route Ns = Ns Ar string sets the server route name. .Pp .Em This option is only available in the commercial version of nginx. .El .Pp Example: .Bd -literal -offset indent upstream backend { server backend1.example.com weight=5; server 127.0.0.1:8080 max_fails=3 fail_timeout=30s; server unix:/tmp/backend3; server backup1.example.com:8080 backup; } .Ed .Pp If there is only a single server in a group, .Cm max_fails , .Cm fail_timeout and .Cm slow_start parameters are ignored, and such a server will never be considered unavailable. .It Ic zone Ar name Ar size .Bl -tag -width Ds -compact .It default: .It context: Ic upstream .El .Pp .Em This directive is only available in the commercial version of nginx. .Pp Makes the group dynamically configurable. Defines the .Ar name and .Ar size of a shared memory zone that keeps group's configuration and run-time state that are shared between worker processes. Such groups allow to add, remove, and modify servers at run time. The configuration is accessible via a special location handled by .Ic upstream_conf . .It Ic ip_hash .Bl -tag -width Ds -compact .It default: .It context: Ic upstream .El .Pp Specifies that a group should use a load balancing method where requests are distributed between servers based on client IP addresses. The first three octets of the client IPv4 address, or the entire IPv6 address, are used as a hashing key. The method ensures that requests from the same client will always be passed to the same server except when this server is unavailable. In the latter case client requests will be passed to another server. Most probably, it will always be the same server as well. IPv6 addresses are supported starting from versions 1.3.2 and 1.2.2. If one of the servers needs to be temporarily removed, it should be marked with the .Cm down parameter in order to preserve the current hashing of client IP addresses. Example: .Bd -literal -offset indent upstream backend { ip_hash; server backend1.example.com; server backend2.example.com; server backend3.example.com down; server backend4.example.com; } .Ed .Pp Until versions 1.3.1 and 1.2.2, it was not possible to specify a weight for servers using the .Ic ip_hash load balancing method. .It Ic keepalive Ar connections .Bl -tag -width Ds -compact .It default: .It context: Ic upstream .El .Pp Activates the cache for connections to upstream servers. The .Ar connections parameter sets the maximum number of idle keepalive connections to upstream servers that are preserved in the cache of each worker process. When this number is exceeded, the least recently used connections are closed. It should be particularly noted that the .Ic keepalive directive does not limit the total number of connections to upstream servers that an nginx worker process can open. The .Ar connections parameter should be set to a number small enough to let upstream servers process new incoming connections as well. Example configuration of memcached upstream with keepalive connections: .Bd -literal -offset indent upstream memcached_backend { server 127.0.0.1:11211; server 10.0.0.2:11211; keepalive 32; } server { ... location /memcached/ { set $memcached_key $uri; memcached_pass memcached_backend; } } .Ed .Pp For HTTP, the .Ic proxy_http_version directive should be set to 1.1 and the Connection header field should be cleared: .Bd -literal -offset indent upstream http_backend { server 127.0.0.1:8080; keepalive 16; } server { ... location /http/ { proxy_pass http://http_backend; proxy_http_version 1.1; proxy_set_header Connection ""; ... } } .Ed .Pp Alternatively, HTTP/1.0 persistent connections can be used by passing the Connection: Keep-Alive header field to an upstream server, though this method is not recommended. For FastCGI servers, it is required to set .Ic fastcgi_keep_conn for keepalive connections to work: .Bd -literal -offset indent upstream fastcgi_backend { server 127.0.0.1:9000; keepalive 8; } server { ... location /fastcgi/ { fastcgi_pass fastcgi_backend; fastcgi_keep_conn on; ... } } .Ed .Pp When using load balancer methods other than the default round-robin method, it is necessary to activate them before the .Ic keepalive directive. SCGI and uwsgi protocols do not have a notion of keepalive connections. .It Ic least_conn .Bl -tag -width Ds -compact .It default: .It context: Ic upstream .El .Pp 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 using a weighted round-robin balancing method. .It Ic health_check Oo Cm interval Ns = Ns Ar time Oc Oo Cm fails Ns = Ns Ar number Oc Oo Cm passes Ns = Ns Ar number Oc Oo Cm uri Ns = Ns Ar uri Oc Oo Cm match Ns = Ns Ar name Oc .Bl -tag -width Ds -compact .It default: .It context: Ic location .El .Pp .Em This directive is only available in the commercial version of nginx. .Pp Enables periodic health checks of the servers in a .Ic upstream .Ar group referenced in the surrounding location. The following optional parameters are supported: .Bl -bullet .It .Cm interval sets the interval between two consecutive health checks, by default, 5 seconds; .It .Cm fails sets the number of consecutive failed health checks of a particular server after which this server will be considered unhealthy, by default, 1; .It .Cm passes sets the number of consecutive passed health checks of a particular server after which the server will be considered healthy, by default, 1; .It .Ar uri defines the URI used in health check requests, by default, .Qq / ; .It .Ic match specifies the .Ic match block configuring the tests that a response should pass in order for a health check to pass; by default, the response should have status code 2xx or 3xx. .El .Pp For example, .Bd -literal -offset indent location / { proxy_pass http://backend; health_check; } .Ed .Pp will send .Qq / requests to each server in the backend group every five seconds. If any communication error or timeout occurs, or a proxied server responds with the status code other than 2xx or 3xx, the health check will fail, and the server will be considered unhealthy. Client requests are not passed to unhealthy servers. Health checks can be configured to test the status code of a response, presence of certain header fields and their values, and the body contents. Tests are configured separately using the .Ic match directive and referenced in the .Ic match parameter. For example: .Bd -literal -offset indent http { server { ... location / { proxy_pass http://backend; health_check match=welcome; } } match welcome { status 200; header Content-Type = text/html; body ~ "Welcome to nginx!"; } } .Ed .Pp This configuration tells that for a health check to pass, the response to a health check request should succeed, have status 200, content type text/html, and contain .Qq Welcome to nginx! in the body. The server group must reside in the shared memory. If several health checks are defined for the same group of servers, a single failure of any check will make the corresponding server be considered unhealthy. .It Ic match Ar name Brq No ... .Bl -tag -width Ds -compact .It default: .It context: Ic http .El .Pp .Em This directive is only available in the commercial version of nginx. .Pp Defines the named test set used to verify responses to health check requests. The following items can be tested in a response: .Bl -tag -width Ds .It Cm status 200; status is 200 .It Cm status ! 500; status is not 500 .It Cm status 200 204; status is 200 or 204 .It Cm status ! 301 302; status is neither 301 nor 302 .It Cm status 200-399; status is in the range from 200 to 399 .It Cm status ! 400-599; status is not in the range from 400 to 599 .It Cm status 301-303 307; status is either 301, 302, 303, or 307 .El .Bl -tag -width Ds .It Cm header Content-Type Ns = Ns Cm text/html; header contains Content-Type with value text/html .It Cm header Content-Type ! Ns = Ns Cm text/html; header contains Content-Type with value other than text/html .It Cm header Connection ~ close; header contains Connection with value matching regular expression close .It Cm header Connection !~ close; header contains Connection with value not matching regular expression close .It Cm header Host; header contains Host .It Cm header ! X-Accel-Redirect; header lacks X-Accel-Redirect .El .Bl -tag -width Ds .It Cm body ~ "Welcome to nginx!"; body matches regular expression Welcome to nginx! .It Cm body !~ "Welcome to nginx!"; body does not match regular expression Welcome to nginx! .El .Pp If several tests are specified, the response matches only if it matches all tests. Only the first 256k of the response body are examined. Examples: .Bd -literal -offset indent # status is 200, content type is "text/html", # and body contains "Welcome to nginx!" match welcome { status 200; header Content-Type = text/html; body ~ "Welcome to nginx!"; } .Ed .Bd -literal -offset indent # status is not one of 301, 302, 303, or 307, and header does not have "Refresh:" match not_redirect { status ! 301-303 307; header ! Refresh; } .Ed .Bd -literal -offset indent # status ok and not in maintenance mode match server_ok { status 200-399; body !~ "maintenance mode"; } .Ed .It Ic sticky Cm cookie Ar name Oo Cm expires Ns = Ns Ar time Oc Oo Cm domain Ns = Ns Ar domain Oc Oo Cm path Ns = Ns Ar path Oc .It Ic sticky Cm route Ar variable No ... .Bl -tag -width Ds -compact .It default: .It context: Ic upstream .El .Pp .Em This directive is only available in the commercial version of nginx. .Pp Enables session affinity, which causes requests from the same client to be passed to the same server in a group of servers. Two methods are available, .Cm cookie and .Cm route . When the .Cm cookie method is used, information about the designated server is passed in an HTTP cookie: .Bd -literal -offset indent upstream backend { server backend1.example.com; server backend2.example.com; sticky cookie srv_id expires=1h domain=.example.com path=/; } .Ed .Pp A request that comes from a client not yet bound to a particular server is passed to the server selected by the configured balancing method. Further requests from the same client are passed to the same server. If the designated server cannot process a request, the new server is selected as if the client has not been bound yet. The first parameter sets the name of the cookie to be set or inspected. Additional parameters may be as follows: .Bl -tag -width Ds .It Cm expires Sets the time for which a browser should keep the cookie. The special value .Cm max will cause the cookie to expire on 31 Dec 2037 23:55:55 GMT. This is the maximum time understood by old browsers. If the parameter is not specified, it will cause the cookie to expire at the end of a browser session. .It Cm domain Defines the domain for which the cookie is set. .It Cm path Defines the path for which the cookie is set. .El .Pp If any parameters are omitted, the corresponding cookie fields are not set. When the .Cm route method is used, proxied server assigns client a route on receipt of the first request. All subsequent requests from this client will carry routing information in a cookie or URI. This information is compared with the .Cm route parameter of the .Ic server directive to identify the server to which the request should be proxied. If the designated server cannot process a request, the new server is selected by the configured balancing method as if there is no routing information in the request. The parameters of the .Cm route method specify variables that may contain routing information. The first non-empty variable is used to find the matching server. Example: .Bd -literal -offset indent map $cookie_jsessionid $route_cookie { ~.+\\.(?P\\w+)$ $route; } map $request_uri $route_uri { ~jsessionid=.+\\.(?P\\w+)$ $route; } upstream backend { server backend1.example.com route=a; server backend2.example.com route=b; sticky route $route_cookie $route_uri; } .Ed .Pp Here, the route is taken from the JSESSIONID cookie if present in a request. Otherwise, the route from the URI is used. .It Ic sticky_cookie_insert Ar name Oo Cm expires Ns = Ns Ar time Oc Oo Cm domain Ns = Ns Ar domain Oc Oo Cm path Ns = Ns Ar path Oc .Bl -tag -width Ds -compact .It default: .It context: Ic upstream .El .Pp This directive is obsolete since version 1.5.7. An equivalent .Ic sticky directive with a new syntax should be used instead: .Ic sticky cookie Ar name Oo Cm expires Ns = Ns Ar time Oc Oo Cm domain Ns = Ns Ar domain Oc Oo Cm path Ns = Ns Ar path Oc ; .It Ic upstream_conf .Bl -tag -width Ds -compact .It default: .It context: Ic location .El .Pp .Em This directive is only available in the commercial version of nginx. .Pp Turns on the HTTP interface of upstream configuration in the surrounding location. Access to this location should be .Ic satisfy limited . Configuration commands can be used to: .Bl -bullet .It view all primary or backup servers in a group; .It view an individual server; .It modify an individual server; .It add a new server (see the note below); .It remove an individual server. .El .Pp As noted in the .Ic server directive, specifying a server as a domain name may result in several servers being added to the group. Since addresses in a group are not required to be unique, individual servers in a group can be uniquely referenced to only by their ID. IDs are assigned automatically and shown on viewing of the group configuration. A configuration command consists of parameters passed as request arguments, for example: .Bd -literal -offset indent http://127.0.0.1/upstream_conf?upstream=appservers .Ed .Pp The following parameters are supported: .Bl -tag -width Ds .It Cm upstream Ns = Ns Ar name Selects a group. This parameter is mandatory. .It Cm backup Ns = If not set, selects primary servers in the group. If set, selects backup servers in the group. .It Cm id Ns = Ns Ar number Selects an individual primary or backup server in the group. .It Cm remove Ns = Removes an individual primary or backup server from the group. .It Cm add Ns = Adds a new primary or backup server to the group. .It Cm server Ns = Ns Ar address Same as the .Ar address parameter of the .Ic server directive. .It Cm weight Ns = Ns Ar number Same as the .Cm weight parameter of the .Ic server directive. .It Cm max_fails Ns = Ns Ar number Same as the .Cm max_fails parameter of the .Ic server directive. .It Cm fail_timeout Ns = Ns Ar time Same as the .Cm fail_timeout parameter of the .Ic server directive. .It Cm slow_start Ns = Ns Ar time Same as the .Cm slow_start parameter of the .Ic server directive. .It Cm down Ns = Same as the .Cm down parameter of the .Ic server directive. .It Cm up Ns = The opposite of the .Cm down parameter of the .Ic server directive. .It Cm route Ns = Ns Ar string Same as the .Cm route parameter of the .Ic server directive. .El .Pp The first three parameters select a target the command applies to. Without other parameters, the command shows configuration of the selected target. For example, to view the primary servers in the group, send: .Bd -literal -offset indent http://127.0.0.1/upstream_conf?upstream=appservers .Ed .Pp To view the backup servers in the group, send: .Bd -literal -offset indent http://127.0.0.1/upstream_conf?upstream=appservers&backup= .Ed .Pp To view an individual primary server in the group, send: .Bd -literal -offset indent http://127.0.0.1/upstream_conf?upstream=appservers&id=42 .Ed .Pp To view an individual backup server in the group, send: .Bd -literal -offset indent http://127.0.0.1/upstream_conf?upstream=appservers&backup=&id=42 .Ed .Pp To add a new primary or backup server to the group, specify its address in the .Ic server Ns = parameter. Without other parameters specified, a server will be added with other parameters set to their default values (see the .Ic server directive). For example, to add a new primary server to the group, send: .Bd -literal -offset indent http://127.0.0.1/upstream_conf?add=&upstream=appservers&server=127.0.0.1:8080 .Ed .Pp To add a new backup server to the group, send: .Bd -literal -offset indent http://127.0.0.1/upstream_conf?add=&upstream=appservers&backup=&server=127.0.0.1:8080 .Ed .Pp To add a new primary server to the group, set its parameters to non-default values and mark it as .Cm down , send: .Bd -literal -offset indent http://127.0.0.1/upstream_conf?add=&upstream=appservers&server=127.0.0.1:8080&weight=2&max_fails=3&fail_timeout=3s&down= .Ed .Pp To remove an individual primary or backup server from the group, select it with the .Cm id Ns = parameter. For example, to remove an individual primary server from the group, send: .Bd -literal -offset indent http://127.0.0.1/upstream_conf?remove=&upstream=appservers&id=42 .Ed .Pp To remove an individual backup server from the group, send: .Bd -literal -offset indent http://127.0.0.1/upstream_conf?remove=&upstream=appservers&backup=&id=42 .Ed .Pp To modify an individual primary or backup server in the group, select it with the .Cm id Ns = parameter. For example, to modify an individual primary server in the group by marking it as .Cm down , send: .Bd -literal -offset indent http://127.0.0.1/upstream_conf?upstream=appservers&id=42&down= .Ed .Pp To modify the address of an individual backup server in the group, send: .Bd -literal -offset indent http://127.0.0.1/upstream_conf?upstream=appservers&backup=&id=42&server=192.0.2.3:8123 .Ed .Pp To modify other parameters of an individual primary server in the group, send: .Bd -literal -offset indent http://127.0.0.1/upstream_conf?upstream=appservers&id=42&max_fails=3&weight=4 .Ed .El .Ss Module ngx_http_userid_module .Bl -tag -width Ds .It Ic userid Cm on | Cm v1 | Cm log | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Enables or disables setting cookies and logging the received cookies: .Bl -tag -width Ds .It Cm on enables the setting of version 2 cookies and logging of the received cookies; .It Cm v1 enables the setting of version 1 cookies and logging of the received cookies; .It Cm log disables the setting of cookies, but enables logging of the received cookies; .It Cm off disables the setting of cookies and logging of the received cookies. .El .It Ic userid_domain Ar name | Cm none .Bl -tag -width Ds -compact .It default: Cm none .It context: Ic http , Ic server , Ic location .El .Pp Defines a domain for which the cookie is set. The .Cm none parameter disables setting of a domain for the cookie. .It Ic userid_expires Ar time | Cm max | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Sets a time during which a browser should keep the cookie. The parameter .Cm max will cause the cookie to expire on 31 Dec 2037 23:55:55 GMT. This is the maximum time understood by old browsers. The parameter .Cm off will cause the cookie to expire at the end of a browser session. .It Ic userid_mark Ar letter | Ar digit | Ns = Ns | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp If the parameter is not .Cm off , enables the cookie marking mechanism and sets the character used as a mark. This mechanism is used to add or change .Ic 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 .Qq = character. If the mark is set, it is compared with the first padding symbol in the base64 representation of the client identifier passed in a cookie. If they do not match, the cookie is resent with the specified mark, expiration time, and P3P header. .It Ic userid_name Ar name .Bl -tag -width Ds -compact .It default: uid .It context: Ic http , Ic server , Ic location .El .Pp Sets the cookie name. .It Ic userid_p3p Ar string | Cm none .Bl -tag -width Ds -compact .It default: Cm none .It context: Ic http , Ic server , Ic location .El .Pp 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 .Cm none , the P3P header will not be sent in a response. .It Ic userid_path Ar path .Bl -tag -width Ds -compact .It default: / .It context: Ic http , Ic server , Ic location .El .Pp Defines a path for which the cookie is set. .It Ic userid_service Ar number .Bl -tag -width Ds -compact .It default: IP address of the server .It context: Ic http , Ic server , Ic location .El .Pp If identifiers are issued by multiple servers (services), each service should be assigned its own .Ar 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. .El .Ss Module ngx_http_xslt_module .Em This module is not enabled on OpenBSD. .Bl -tag -width Ds .It Ic xml_entities Ar path .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp 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: .Bd -literal -offset indent .Ed .It Ic xslt_last_modified Cm on | Cm off .Bl -tag -width Ds -compact .It default: Cm off .It context: Ic http , Ic server , Ic location .El .Pp Allows preserving the Last-Modified header field from the original response during XSLT transformations to facilitate response caching. By default, the header field is removed as contents of the response are modified during transformations and may contain dynamically generated elements or parts that are changed independently of the original response. .It Ic xslt_param Ar parameter Ar value .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Defines the parameters for XSLT stylesheets. The .Ar value is treated as an XPath expression. The .Ar value can contain variables. To pass a string value to a stylesheet, the .Ic xslt_string_param directive can be used. There could be several .Ic xslt_param directives. These directives are inherited from the previous level if and only if there are no .Ic xslt_param and .Ic xslt_string_param directives defined on the current level. .It Ic xslt_string_param Ar parameter Ar value .Bl -tag -width Ds -compact .It default: .It context: Ic http , Ic server , Ic location .El .Pp Defines the string parameters for XSLT stylesheets. XPath expressions in the .Ar value are not interpreted. The .Ar value can contain variables. There could be several .Ic xslt_string_param directives. These directives are inherited from the previous level if and only if there are no .Ic xslt_param and .Ic xslt_string_param directives defined on the current level. .It Ic xslt_stylesheet Ar stylesheet Oo Ar parameter Ns = Ns Ar value No ... Oc .Bl -tag -width Ds -compact .It default: .It context: Ic location .El .Pp Defines the XSLT stylesheet and its optional parameters. A stylesheet is compiled at the configuration stage. Parameters can either be specified separately, or grouped in a single line using the .Qo : Qc delimiter. If a parameter includes the .Qo : Qc character, it should be escaped as .Qq %3A . Also, libxslt requires to enclose parameters that contain non-alphanumeric characters into single or double quotes, for example: .Bd -literal -offset indent param1='http%3A//www.example.com':param2=value2 .Ed .Pp The parameters description can contain variables, for example, the whole line of parameters can be taken from a single variable: .Bd -literal -offset indent location / { xslt_stylesheet /site/xslt/one.xslt $arg_xslt_params param1='$value1':param2=value2 param3=value3; } .Ed .Pp It is possible to specify several stylesheets. They will be applied sequentially in the specified order. .It Ic xslt_types Ar mime-type No ... .Bl -tag -width Ds -compact .It default: text/xml .It context: Ic http , Ic server , Ic location .El .Pp Enables transformations in responses with the specified MIME types in addition to text/xml. The special value .Qq * matches any MIME type (0.8.29). If the transformation result is an HTML response, its MIME type is changed to text/html. .El .Sh FILES .Pa /etc/nginx/nginx.conf .Sh EXAMPLES The following is a valid configuration file, but such creative use of whitespace is not recommended: .Bd -literal -offset indent worker_processes #whitespace is required here auto #a comment is allowed here ;events{}user #whitespace is again required here www #and here, too www;# but not here .Ed .Sh SEE ALSO .Xr nginx 8 .Sh HISTORY This manual has been available since .Ox 5.5 . .Sh AUTHORS .An -nosplit The bulk of the text was semi-automatically converted from the XML sources of .Lk http://nginx.org/en/docs/#development to .Xr mdoc 7 by .An Florian Obser Aq Mt florian@openbsd.org . The description of the grammar was written by .An Ingo Schwarze Aq Mt schwarze@openbsd.org .