path: root/usr.sbin/nginx/man/nginx.conf.5

.\"	$OpenBSD: nginx.conf.5,v 1.6 2013/12/16 11:19:03 florian Exp $
.\"
.\" Copyright (C) 2002-2012 Igor Sysoev
.\" Copyright (C) 2011-2013 Nginx, Inc.
.\" Copyright (C) 2013 Florian Obser <florian@openbsd.org>
.\" Copyright (C) 2013 Ingo Schwarze <schwarze@openbsd.org>
.\" 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: December 16 2013 $
.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 -offset indent -ragged
.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 -offset indent -ragged
.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 -offset indent -ragged
.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 -offset indent -ragged
.Ar ws
.Li ::=
.Ar ws-char
.Op Ar opt-ws
.Ed
.Bd -offset indent -ragged
.Ar ws-char
.Li ::=
.Aq space
.Li \&|
.Aq tab
.Li \&|
.Aq newline
.Ed
.Bd -offset indent -ragged
.Ar opt-ws
.Li ::=
.Pq Ar comment | ws-char
.Op Ar opt-ws
.Ed
.Bd -offset indent -ragged
.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, preceeding 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\\.)?(?<domain>.+)$;
    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<sl_domain>[-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<route>\\w+)$ $route;
}
map $request_uri $route_uri {
    ~jsessionid=.+\\.(?P<route>\\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
<!ENTITY nbsp "&#xa0;">
.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,
.Lb 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 -offset indent -literal
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