accept_mutex

Serializes the accept() method on new connections by worker processes.

Valid context: events

Default value: on

accept_mutex_delay

The maximum time a worker process will wait to accept new connections if another worker is already doing this.

Valid context: events

Default value: 500ms

access_log

Describes where and how are to be written. The first parameter is a path to the file where the logs are to be stored. Variables may be used in constructing the path. The special value, off, disables the access log. An optional second parameter indicates the log_format directive that will be used to write the logs. If no second parameter is configured, the predefined combined format is used. An optional third parameter indicates the size of the buffer if write buffering should be used to record the logs. If write buffering is used, this size cannot exceed the size of the atomic disk write for that filesystem.

Valid contexts: http, server, location, if in location, and limit_except

Default value: logs/access.log combined

add_after_body

Adds the result of processing a subrequest after the response body.

Valid contexts: http, server, and location

Default value: -

add_before_body

Adds the result of processing a subrequest before the response body.

Valid contexts: http, server, and location

Default value: -

add_header

Adds fields to a header present in responses with the HTTP codes 200, 204, 206, 301, 302, 303, 304, or 307.

Valid contexts: http, server, location, and if in location

Default value: -

addition_types

Lists the MIME types of a response in addition to text/html, in which an addition will be made. May be * to enable all MIME types.

Valid contexts: http, server, and location

Default value: text/html

aio

Enables the use of asynchronous file I/O. It is available on all modern versions of FreeBSD and distributions of Linux. On FreeBSD, aio may be used to preload data for sendfile. Under Linux, directio is required, which automatically disables sendfile.

Valid contexts: http, server, and location

Default value: off

alias

Defines another name for the location, as found on the filesystem. If the location is specified with a regular expression, the alias directive should reference captures defined in that regular expression.

Valid context: location

Default value: -

allow

Allows access from this IP address, network, or all.

Valid contexts: http, server, location, and limit_except

Default value: -

ancient_browser

One or more strings, which if found in the User-Agent header, will indicate that the browser is considered ancient by setting the $ancient_browser variable to the ancient_browser_value directive.

Valid contexts: http, server, and location

Default value: -

ancient_browser_value

The value to which the $ancient_browser variable will be set.

Valid contexts: http, server, and location

Default value: 1

auth_basic

Enables authentication using HTTP Basic Authentication. The string parameter is used as the realm name. If the special value, off, is used, this indicates that the auth_basic value of the parent configuration level is negated.

Valid contexts: http, server, location, and limit_except

Default value: off

auth_basic_user_file

The location of a file of the username:password:comment tuples used to authenticate users. The password needs to be encrypted with the crypt algorithm. The comment is optional.

Valid contexts: http, server, location, and limit_except

Default value: -

auth_http

The server used for authenticating the POP3/IMAP user.

Valid contexts: mail and server

Default value: -

auth_http_header

Sets an additional header (first parameter) to the specified value (second parameter).

Valid contexts: mail and server

Default value: -

auth_http_pass_client_cert

Specifies whether to pass the PEM-encoded client certificate as the Auth-SSL-Cert header.

Valid contexts: mail and server

Default value: off

auth_http_timeout

The maximum amount of time NGINX will wait when communicating with an authentication server.

Valid contexts: mail and server

Default value: 60s

auth_request

The URI to which an authorization subrequest should be sent.

Valid contexts: http, server, and location

Default value: off

auth_request_set

The given variable to the value, which may contain variables from the authorization request.

Valid contexts: http, server, and location

Default value: -

autoindex

The automatic generation of a directory listing page.

Valid contexts: http, server, and location

Default value: off

autoindex_exact_size

Indicates whether the file sizes in a directory listing page should be listed in bytes or rounded to kilobytes, megabytes, and gigabytes.

Valid contexts: http, server, and location.

Default value: on

autoindex_format

The format to be used for the directory listing.

Valid contexts: http, server, and location

Default value: html

autoindex_localtime

Sets the file modification time in a directory listing page to either local time (on) or UTC (off).

Valid contexts: http, server, and location

Default value: off

break

Ends the processing of the rewrite module directives found within the same context.

Valid contexts: server, location, and if

Default value: -

charset

Adds the character set specified to the Content-Type response header. If this is different than the source_charset directive, a conversion is performed.

Valid contexts: http, server, location, and if in location

Default value: off

charset_map

Sets up a conversion table from one character set to another. Each character code is specified in hexadecimal. The files conf/koi-win, conf/koi-utf, and conf/win-utf include mappings from koi8-r to windows-1251, from koi8-r to utf-8, and from windows-1251 to utf-8, respectively.

Valid context: http

Default value: -

charset_types

Lists the MIME types of a response in addition to text/html, in which a character set conversion will be made. It may be * to enable all MIME types.

Valid contexts: http, server, and location

Default values: text/html, text/xml, text/plain, text/vnd.wap.wml, application/x-javascript, and application/rss+xml

chunked_transfer_encoding

Allows disabling the standard HTTP/1.1 chunked transfer encoding in responses to clients.

Valid contexts: http, server, and location

Default value: on

client_body_buffer_size

Used to set a buffer size for the client request body larger than the default two memory pages, in order to prevent temporary files from being written to disk.

Valid contexts: http, server, and location

Default value: 8k|16k (platform dependent)

client_body_in_file_only

Used for debugging or further processing of the client request body; this directive can be set to on to force saving the client request body to a file. The value, clean, will cause the files to be removed after the request processing has finished.

Valid contexts: http, server, and location

Default value: off

client_body_in_single_buffer

This directive will force NGINX to save the entire client request body in a single buffer, to reduce copy operations.

Valid contexts: http, server, and location

Default value: off

client_body_temp_path

Defines a directory path for saving the client request body. If a second, third, or fourth parameter is given, these specify a subdirectory hierarchy with the parameter value as the number of characters in the subdirectory name.

Valid contexts: http, server, and location

Default value: client_body_temp

client_body_timeout

Specifies the length of time between successive read operations of the client body. If reached, the client receives a 408 error message (Request Timeout).

Valid contexts: http, server, and location

Default value: 60s

client_header_buffer_size

Used for specifying a buffer size for the client request header, when this needs to be larger than the default 1 KB.

Valid contexts: http and server

Default value: 1k

client_header_timeout

Specifies the length of time for reading the entire client header. If reached, the client receives a 408 error message (Request Timeout).

Valid contexts: http and server

Default value: 60s

client_max_body_size

Defines the largest allowable client request body, before a 413 (Request Entity Too Large) error is returned to the browser.

Valid contexts: http, server, and location

Default value: 1m

connection_pool_size

Fine tunes per-connection memory allocation.

Valid contexts: http and server

Default values: 256 (on 32-bit platforms) and 512 (on 64-bit platforms)

create_full_put_path

Allows recursive directory creation when using WebDAV.

Valid contexts: http, server, and location

Default value: off

daemon

Sets whether or not to daemonize the NGINX process.

Valid context: main

Default value: on

dav_access

Sets filesystem access permissions for newly-created files and directories. If group or all is specified, user may be omitted.

Valid contexts: http, server, and location

Default value: user:rw

dav_methods

Allows the specified HTTP and WebDAV methods. When PUT is used, a temporary file is first created, and then renamed. So, it's recommended to put client_body_temp_path on the same filesystem as the destination. A modification date for such files may be specified in the Date header.

Valid contexts: http, server, and location

Default value: off

debug_connection

Enables debug logging for any client matching the value of this directive. It may be specified multiple times. To debug UNIX-domain sockets, use unix:.

Valid context: events

Default value: -

debug_points

When debugging, the process will either create a core file (abort) or stop (stop) so that a system debugger may be attached.

Valid context: main

Default value: -

default_type

Sets the default MIME type of a response. This comes into play if the MIME type of the file cannot be matched to one of those specified by the types directive.

Valid contexts: http, server, and location

Default value: text/plain

deny

Denies access from this IP address, network, or all.

Valid contexts: http, server, location, and limit_except

Default value: -

directio

Enables the operating system-specific flag or function for serving files larger than the parameter given. This directive is required when using aio on Linux.

Valid contexts: http, server, and location

Default value: off

directio_alignment

Sets the alignment for directio. The default value of 512 is usually enough, although it's recommended to increase this to 4K when using XFS on Linux.

Valid contexts: http, server, and location

Default value: 512

disable_symlinks

For more information on this directive, refer to the table (The HTTP file path directives) given in the Finding files section in Chapter 6, The NGINX HTTP Server.

Valid contexts: http, server, and location

Default value: off

empty_gif

Causes a 1x1 pixel transparent GIF to be emitted for that location.

Valid context: location

Default value: -

env

Sets the environment variables for use in the following ways:

Valid context: main

Default value: TZ

error_log

The error_log file is where all errors will be written. It may be set to a file or stderr. If no other error_log is given in a separate context, this log file will be used for all errors, globally. A second parameter to this directive indicates at which level (debug, info, notice, warn, error, crit, alert, emerg) errors will be written to the log. Note that the debug level errors are only available if the --with-debug configuration switch was given at compile time.

Valid contexts: main, http, server, and location

Default value: logs/error.log error

error_page

Defines a URI to be served when an error level response code is encountered. Adding an = parameter allows the response code to be changed. If the argument to this parameter is left empty, the response code will be taken from the URI, which must in this case be served by an upstream server of some sort.

Valid contexts: http, server, location, and if in location

Default value: -

etag

Disables automatically generating the ETag response header for static resources.

Valid contexts: http, server, and location

Default value: on

events

Defines a new context in which connection-processing directives are specified.

Valid context: main.

Default value: -

expires

For more information on this directive, refer to the table (Header modifying directives) given in the Caching in the filesystem section in Chapter 7, NGINX for the Application Developer.

Valid contexts: http, server, location, and if in location

Default value: off

fastcgi_bind

Specifies the address that should be used for outgoing connections to a FastCGI server.

Valid contexts: http, server, and location

Default value: -

fastcgi_buffer_size

The size of the buffer used for the first part of the response from the FastCGI server, in which the response headers are found.

Valid contexts: http, server, and location

Default value: 4k|8k (platform dependent)

fastcgi_buffering

Whether or not to buffer responses from the FastCGI server.

Valid contexts: http, server, and location

Default value: on

fastcgi_buffers

The number and size of buffers used for the response from a FastCGI server, for a single connection.

Valid contexts: http, server, and location

Default value: 4k|8k (platform dependent)

fastcgi_busy_buffers_size

The total size of the buffer space allocated to sending the response to the client while still being read from the FastCGI server. This is typically set to two fastcgi_buffers.

Valid contexts: http, server, and location

Default value: 4k|8k (platform dependent)

fastcgi_cache

Defines a shared memory zone to be used for caching.

Valid contexts: http, server, and location

Default value: off

fastcgi_cache_bypass

One or more string variables, which when nonempty or nonzero, will cause the response to be taken from the FastCGI server instead of the cache.

Valid contexts: http, server, and location

Default value: -

fastcgi_cache_key

A string used as the key for storing and retrieving cache values.

Valid contexts: http, server, and location

Default value: -

fastcgi_cache_lock

Enabling this directive will prevent multiple requests from making an entry into the same cache key.

Valid contexts: http, server, and location

Default value: off

fastcgi_cache_lock_age

The time for an entry to appear in the cache or one final request will be made.

Valid contexts: http, server, and location

Default value: 5s

fastcgi_cache_lock_timeout

The length of time a request will wait for an entry to appear in the cache or for the fastcgi_cache_lock to be released.

Valid contexts: http, server, and location

Default value: 5s

fastcgi_cache_methods

This directive specifies the methods that are present in the client request in order for it to be cached.

Valid contexts: http, server, and location

Default value: GET HEAD

fastcgi_cache_min_uses

The number of requests for a certain key needed before a response is cached.

Valid contexts: http, server, and location

Default value: 1

fastcgi_cache_path

For more information on this directive, refer to the table (FastCGI directives) given in the Using NGINX with PHP-FPM section in Chapter 6, The NGINX HTTP Server.

Valid context: http

Default value: -

fastcgi_cache_revalidate

Whether the If-Modified-Since and If-None-Match headers should be used to revalidate expired cache entries.

Valid contexts: http, server, and location

Default value: off

fastcgi_cache_use_stale

The cases under which it is acceptable to serve stale cached data when an error occurs while accessing the FastCGI server. The updating parameter indicates the case when fresh data are being loaded.

Valid contexts: http, server, and location

Default value: off

fastcgi_cache_valid

Indicates the length of time for which a cached response with response code 200, 301, or 302 is valid. If an optional response code is given before the time parameter, this time is only for that response code. The special parameter, any, indicates that any response code should be cached for that length of time.

Valid contexts: http, server, and location

Default value: -

fastcgi_connect_timeout

The maximum amount of time NGINX will wait for its connection to be accepted when making a request to a FastCGI server.

Valid contexts: http, server, and location

Default value: 60s

fastcgi_force_ranges

Forces byte-range support, irrespective of the value of the Accept-Ranges header.

Valid contexts: http, server, and location

Default value: off

fastcgi_hide_header

A list of header fields that should not be passed on to the client.

Valid contexts: http, server, and location

Default value: -

fastcgi_ignore_client_abort

If set to on, NGINX will not abort the connection to a FastCGI server if the client aborts the connection.

Valid contexts: http, server, and location

Default value: off

fastcgi_ignore_headers

Sets which headers may be disregarded when processing the response from the FastCGI server.

Valid contexts: http, server, and location

Default value: -

fastcgi_index

Sets the name of a file to be appended to $fastcgi_script_name that ends with a slash.

Valid contexts: http, server, and location

Default value: -

fastcgi_intercept_errors

If enabled, NGINX will display a configured error_page directive instead of the response directly from the FastCGI server.

Valid contexts: http, server, and location

Default value: off

fastcgi_keep_conn

Enables the keepalive connections to the FastCGI servers by instructing the server not to immediately close the connection.

Valid contexts: http, server, and location

Default value: off

fastcgi_limit_rate

If buffering is enabled, the bytes/s at which the response from the FastCGI server will be read.

Valid contexts: http, server, and location

Default value: 0 (disabled)

fastcgi_max_temp_file_size

The maximum size of the overflow file; this directive is written when the response doesn't fit into the memory buffers.

Valid contexts: http, server, and location

Default value: 1024m

fastcgi_next_upstream

For more information on this directive, refer to the table (FastCGI directives) given in the Using NGINX with PHP-FPM section in Chapter 6, The NGINX HTTP Server.

Valid contexts: http, server, and location

Default value: error timeout

fastcgi_next_upstream_timeout

The time limit for passing the request to the next server.

Valid contexts: http, server, and location

Default value: 0

fastcgi_next_upstream_tries

The number of tries before the request is passed to the next server.

Valid contexts: http, server, and location

Default value: 0

fastcgi_no_cache

One or more string variables, which when nonempty or nonzero will instruct NGINX not to save the response from the FastCGI server in the cache.

Valid contexts: http, server, and location

Default value: -

fastcgi_param

Sets a parameter and its value to be passed to the FastCGI server. If the parameter should only be passed when the value is nonempty, the additional if_not_empty parameter should be set.

Valid contexts: http, server, and location

Default value: -

fastcgi_pass

Specifies the FastCGI server to which the request is passed, either as an address:port combination or as unix:path for a UNIX-domain socket.

Valid contexts: location and if in location

Default value: -

fastcgi_pass_header

Overrides the disabled headers set in fastcgi_hide_header, allowing them to be sent to the client.

Valid contexts: http, server, and location

Default value: -

fastcgi_pass_request_body

Whether or not the original request body will be passed to the FastCGI server.

Valid contexts: http, server, and location

Default value: on

fastcgi_pass_request_header

Specifies whether or not the headers of the original request will be passed to the FastCGI server.

Valid contexts: http, server, and location

Default value: on

fastcgi_read_timeout

Specifies the length of time that needs to elapse between two successive read operations from a FastCGI server before the connection is closed.

Valid contexts: http, server, and location

Default value: 60s

fastcgi_request_buffering

Whether or not the complete client request body will be buffered before sending the request to the FastCGI server.

Valid contexts: http, server, and location

Default value: on

fastcgi_send_lowat

This is a FreeBSD directive. When nonzero, it will tell NGINX to use either the NOTE_LOWAT kqueue method or the SO_SNDLOWAT socket option with the specified size when communicating with an upstream server. This directive is ignored in Linux, Solaris, and Windows.

Valid contexts: http, server, and location

Default value: 0

fastcgi_send_timeout

The length of time that needs to elapse between two successive write operations to a FastCGI server before the connection is closed.

Valid contexts: http, server, and location

Default value: 60s

fastcgi_split_path_info

Defines a regular expression with two captures. The first capture will be the value of the $fastcgi_script_name variable. The second capture becomes the value of the $fastcgi_path_info variable.

Valid context: location

Default value: -

fastcgi_store

Enables storing responses retrieved from a FastCGI server as files on the disk. The on parameter will use the alias or root directive as the base path under which to store the file. A string may instead be given, to indicate an alternative location to store the files.

Valid contexts: http, server, and location

Default value: off

fastcgi_store_access

Sets file access permissions for the newly-created fastcgi_store files.

Valid contexts: http, server, and location

Default value: user:rw

fastcgi_temp_file_write_size

Limits the amount of data buffered to a temporary file at one time so that NGINX will not be blocked for too long on a single request.

Valid contexts: http, server, and location

Default value: 8k|16k (platform dependent)

fastcgi_temp_path

In this directory, temporary files may be buffered as they are proxied from the FastCGI server, optionally multilevel deep. If a second, third, or fourth parameter is given, these parameters specify a subdirectory hierarchy with the parameter value as the number of characters in the subdirectory name.

Valid contexts: http, server, and location

Default value: fastcgi_temp

flv

Activates the flv module for this location.

Valid context: location

Default value: -

geo

Defines a new context, in which a variable is set to a specified value, dependent on the IP address found in another variable. If no other variable is specified, $remote_addr is used to determine the IP address. The format of the context definition is as follows:

geo [$address-variable] $variable-to-be-set { … }

The following parameters are recognized within the context:

Valid context: http

Default value: -

geoip_city

The path to a GeoIP database file containing IP address-to-city mappings. The following variables then become available:

Valid context: http

Default value: -

geoip_country

The path to a GeoIP database file containing the IP address-to-country mappings. The following variables then become available:

Valid context: http

Default value: -

geoip_org

The path to a GeoIP database file containing the IP address-to-organization mappings. The following variable then becomes available:

Valid context: http.

Default value: -

geoip_proxy

Defines an address or network of a direct connection from which the IP address will be taken from the X-Forwarded-For header.

Valid context: http

Default value: -

geoip_proxy_recursive

Works with geoip_proxy to specify that the last address in a multivalued X-Forwarded-For header will be used.

Valid context: http

Default value: off

gunzip

Enables the decompression of the gzip files when the client doesn't support gzip.

Valid contexts: http, server, and location

Default value: off

gunzip_buffers

Specifies the number and size of buffers used for decompressing a response.

Valid contexts: http, server, and location

Default value: 32 4k|16 8k (platform dependent)

gzip

Enables or disables the compression of responses.

Valid contexts: http, server, location, and if in location

Default value: off

gzip_buffers

Specifies the number and size of buffers used for compressing a response.

Valid contexts: http, server, and location

Default value: 32 4k|16 8k (platform dependent)

gzip_comp_level

The gzip compression level (1-9).

Valid contexts: http, server, and location

Default value: 1

gzip_disable

A regular expression of user-agents that shouldn't receive a compressed response. The special value, msie6, is a shortcut for MSIE [4-6]\., excluding MSIE 6.0; ... SV1.

Valid contexts: http, server, and location

Default value: -

gzip_http_version

The minimum HTTP version of a request before compression is considered.

Valid contexts: http, server, and location

Default value: 1.1

gzip_min_length

The minimum length of a response before compression is considered, determined by the Content-Length header.

Valid contexts: http, server, and location

Default value: 20

gzip_proxied

Refer to the table (The Gzip module directives) in the Compressing data section in Chapter 5, Reverse Proxy Advanced Topics.

Valid contexts: http, server, and location

Default value: off

gzip_static

Enables checking for precompressed files to be delivered directly to clients that support the gzip compression.

Valid contexts: http, server, and location

Default value: off

gzip_types

The MIME types that should be compressed with gzip, in addition to the default text/html value. It may be * to enable all MIME types.

Valid contexts: http, server, and location

Default value: text/html

gzip_vary

Enables or disables the response header, Vary: Accept-Encoding, if gzip or gzip_static is active.

Valid contexts: http, server, and location

Default value: off

hash

The key that is used to map to the upstream server for each request. To use the ketama consistent hashing algorithm instead of rehashing when servers are added or removed, specify the consistent parameter.

Valid context: upstream

Default value: -

http

Sets up a configuration context in which the HTTP server directives are specified.

Valid context: main

Default value: -

http2_chunk_size

Sets the maximum chunk size for the response body.

Valid contexts: http, server, and location

Default value: 8k

http2_idle_timeout

The amount of time with no activity after which the connection is closed.

Valid contexts: http and server

Default value: 3m

http2_max_concurrent_streams

Sets the number of HTTP/2 streams that may be active in a single connection.

Valid contexts: http and server

Default value: 128

http2_max_field_size

Sets the maximum size of the compressed request header field.

Valid contexts: http and server

Default value: 4k

http2_max_header_size

Sets the maximum size of the uncompressed request headers.

Valid contexts: http and server

Default value: 16k

http2_recv_buffer_size

The size of the input buffer for each worker.

Valid context: http

Default value: 256k

http2_recv_timeout

The amount of time a client has to send data before the connection is closed.

Valid contexts: http and server

Default value: 30s

if

Refer to the table (The rewrite module directives) given in the Introducing the rewrite module section in Appendix B, The Rewrite Rule Guide.

Valid contexts: server and location

Default value: -

if_modified_since

Controls how the modification time of a response is compared to the value of the If-Modified-Since request header:

Valid contexts: http, server, and location

Default value: exact

ignore_invalid_headers

Disables ignoring headers with invalid names. A valid name is composed of ASCII letters, numbers, the hyphen, and possibly the underscore (controlled by the underscores_in_headers directive).

Valid contexts: http and server

Default value: on

image_filter

Refer to the table (The image filter directives) given in the Generating images section in Chapter 7, NGINX for the Application Developer.

Valid context: location

Default value: -

image_filter_buffer

The size of the buffer used to process images. If more memory is needed, the server will return a 415 error (Unsupported Media Type).

Valid contexts: http, server, and location

Default value: 1M

image_filter_interlace

Whether or not to interlace images produced by this filter.

Valid contexts: http, server, and location

Default value: off

image_filter_jpeg_quality

The quality of the resulting JPEG image, after processing. The value is not recommended to exceed 95.

Valid contexts: http, server, and location

Default value: 75

image_filter_sharpen

Increases the sharpness of a processed image by this percentage.

Valid contexts: http, server, and location

Default value: 0

image_filter_transparency

Disables preserving the transparency of the transformed GIF and PNG images. The default value, on, preserves transparency.

Valid contexts: http, server, and location

Default value: on

imap_auth

Sets the supported client authentication mechanism. It can be one or more of login, plain, or cram-md5.

Valid contexts: mail and server

Default value: plain

imap_capabilities

The IMAP4 capabilities that are supported by the backend server.

Valid contexts: mail and server

Default value: IMAP4 IMAP4rev1 UIDPLUS

imap_client_buffer

Sets the size of the read buffer for the IMAP commands.

Valid contexts: mail and server

Default value: 4k|8k (platform dependent)

include

The path to a file containing additional configuration directives. It may be specified as glob to include multiple files.

Valid context: any

Default value: -

index

Defines the file that will be served to the client when a URI ending with / is received. It may be multivalued.

Valid contexts: http, server, and location

Default value: index.html

internal

Specifies a location that can only be used for internal requests (redirects defined in other directives, the rewrite requests, and similar request processing directives).

Valid context: location

Default value: -

ip_hash

Ensures the distribution of clients evenly over all server contexts by hashing the IP address, keying on its class C network.

Valid context: upstream

Default value: -

keepalive

The number of connections to the upstream servers that are cached per worker process. When used with the HTTP connections, proxy_http_version should be set to 1.1 and proxy_set_header to Connection.

Valid context: upstream

Default value: -

keepalive_disable

Disables the keepalive requests for certain browser types.

Valid contexts: http, server, and location

Default value: msie6

keepalive_requests

Defines how many requests may be made over one keepalive connection before it is closed.

Valid contexts: http, server, and location

Default value: 100

keepalive_timeout

Specifies how long a keepalive connection will stay open. A second parameter may be given, to set a Keep-Alive header in the response.

Valid contexts: http, server, and location

Default value: 75s

large_client_header_buffers

Defines the maximum number and size of a large client request header.

Valid contexts: http and server

Default value: 4 8k

least_conn

Activates the load-balancing algorithm where the server with the least number of active connections is chosen for the next new connection.

Valid context: upstream

Default value: -

limit_conn

Specifies a shared memory zone (configured with limit_conn_zone) and the maximum number of connections that are allowed per key value.

Valid contexts: http, server, and location

Default value: -

limit_conn_log_level

When NGINX limits a connection due to the limit_conn directive, this directive specifies at which log level that limitation is reported.

Valid contexts: http, server, and location

Default value: error

limit_conn_status

Which response code to send to the client when the request is rejected.

Valid contexts: http, server, and location

Default value: 503

limit_conn_zone

Specifies the key to be limited in limit_conn as the first parameter. The second parameter, zone, indicates the name of the shared memory zone used to store the key and current number of connections per key and the size of that zone (name:size).

Valid context: http

Default value: -

limit_except

Will limit a location to the specified HTTP verb(s) (GET also includes HEAD).

Valid context: location

Default value: -

limit_rate

Limits the rate (in bytes per second) at which clients can download content. The rate limit works on a connection level, meaning that a single client could increase their throughput by opening multiple connections.

Valid context: http, server, location, and if in location

Default value: 0

limit_rate_after

Starts the limit_rate directive after this number of bytes has been transferred.

Valid contexts: http, server, location, and if in location

Default value: 0

limit_req

Sets a limit with bursting capability on the number of requests for a specific key in a shared memory store (configured with limit_req_zone). The burst may be specified with the second parameter. If there shouldn't be a delay in between requests up to the burst, a third parameter, nodelay, needs to be configured.

Valid context: http, server, and location

Default value: -

limit_req_log_level

When NGINX limits the number of requests due to the limit_req directive, this directive specifies at which log level that limitation is reported. A delay is logged at a level one less than the one indicated here.

Valid contexts: http, server, and location

Default value: -

limit_req_status

Which response code to send to the client when the request is rejected.

Valid contexts: http, server, and location

Default value: 503

limit_req_zone

Specifies the key to be limited in limit_req as the first parameter. The second parameter, zone , indicates the name of the shared memory zone used to store the key and current number of requests per key and the size of that zone (name:size). The third parameter, rate, configures the number of requests per second (r/s) or per minute (r/m) before the limit is imposed.

Valid context: http

Default value: -

limit_zone

Deprecated. Use limit _conn_zone instead.

Valid context: http

Default value: -

lingering_close

This directive specifies how a client connection will be kept open for more data.

Valid contexts: http, server, and location

Default value: on

lingering_time

In connection with the lingering_close directive, this directive will specify how long a client connection will be kept open for processing more data.

Valid contexts: http, server, and location

Default value: 30s

lingering_timeout

Also in conjunction with lingering_close, this directive indicates how long NGINX will wait for additional data before closing the client connection.

Valid contexts: http, server, and location

default value: 5s

listen (http)

Refer to the table (the lis ten parameters) given in the The virtual server section in Chapter 2, A Configuration Guide.

Valid context: server

Default value: *:80 | *:8000

listen (mail)

The listen directive uniquely identifies a socket binding under NGINX. It takes the following parameter:

Valid context: server

Default value: -

location

Defines a new context based on the request URI.

Valid contexts: server and location

Default value: -

lock_file

The prefix name for the lock files. Depending on the platform, a lock file may be needed to implement accept_mutex and shared memory access serialization.

Valid context: main

Default value: logs/nginx.lock

log_format

Specifies which fields should appear in the log file and what format they should take.

Valid context: http

Default value: combined $remote_addr - $remote_user [$time_local], "$request" $status $body_bytes_sent, and "$http_referer""$http_user_agent"'

log_not_found

Disables reporting of 404 errors in the error log.

Valid contexts: http, server, and location

Default value: on

log_subrequest

Enables the logging of subrequests in the access log.

Valid contexts: http, server, and location

Default value: off

mail

Sets up a configuration context in which the mail server directives are specified.

Valid context: main

Default value: -

map

Defines a new context, in which a variable is set to a specified value, dependent on the value of a source variable. The format of the context definition is as follows:

map $source-variable $variable-to-be-set { … }

The string or strings to be mapped may also be regular expressions. The following parameters are recognized within the context:

Valid context: http

Default value: -

map_hash_bucket_size

The bucket size used to hold the map hash tables.

Valid context: http

Default value: 32|64|128

map_hash_max_size

The maximum size of the map hash tables.

Valid context: http

Default value: 2048

master_process

Determines whether or not to start worker processes.

Valid context: main

Default value: on

max_ranges

Sets the maximum number of ranges allowed in a byte-range request. Specifying 0 disables the byte-range support.

Valid contexts: http, server, and location

Default value: -

memcached_bind

Specifies which address should be used for outgoing connections to a memcached server.

Valid contexts: http, server, and location

Default value: -

memcached_buffer_size

The size of the buffer for the response from memcached. This response is then sent synchronously to the client.

Valid contexts: http, server, and location

Default value: 4k|8k

memcached_connect_timeout

The maximum length of time NGINX will wait for its connection to be accepted when making a request to a memcached server.

Valid contexts: http, server, and location

Default value: 60s

memcached_gzip_flag

Specifies a value, when found in the response from a memcached server, which will set the Content-Encoding header to gzip.

Valid contexts: http, server, and location

Default value: -

memcached_next_upstream

Refer to the table (The memcached module directives) given in the Caching in the database section in Chapter 7, NGINX for the Application Developer.

Valid contexts: http, server, and location

Default value: error timeout

memcached_next_upstream_timeout

How much time can pass before the request is passed to the next server. (The default value is disabled.)

Valid contexts: http, server, and location

Default value: 0

memcached_next_upstream_tries

How many tries are made before the request is passed to the next server. (The default value is disabled.)

Valid contexts: http, server, and location

Default value: 0

memcached_pass

Specifies the name or address of a memcached server and its port. It may also be a server group, as declared in an upstream context.

Valid contexts: location and if in location

Default value: -

memcached_read_timeout

This directive specifies the length of time that needs to elapse between two successive read operations from a memcached server before the connection is closed.

Valid contexts: http, server, and location

Default value: 60s

memcached_send_timeout

The length of time that needs to elapse between two successive write operations to a memcached server before the connection is closed.

Valid contexts: http, server, and location

Default value: 60s

merge_slashes

Disables the removal of multiple slashes. The default value of on means that NGINX will compress two or more / characters into one.

Valid contexts: http and server

Default value: on

min_delete_depth

Allows the WebDAV DELETE method to remove files when at least this number of elements is present in the request path.

Valid contexts: http, server, and location

Default value: 0

modern_browser

Specifies a browser and version parameter, which together will indicate that the browser is considered modern by setting the $modern_browser variable to modern_browser_value. The browser parameter may take one of the following values: msie, gecko, opera, safari, or konqueror. An alternative parameter unlisted may be specified to indicate that any browser not found in ancient_browser nor in modern_browser or has a missing User-Agent header is considered modern.

Valid contexts: http, server, and location

Default value: -

modern_browser_value

The value to which the $modern_browser variable will be set.

Valid contexts: http, server, and location

Default value: 1

mp4

Activates the mp4 module for this location.

Valid context: location

Default value: -

mp4_buffer_size

Sets the initial buffer size for delivering the MP4 files.

Valid contexts: http, server, and location

Default value: 512K

mp4_max_buffer_size

Sets the maximum size of the buffer used to process the MP4 metadata.

Valid contexts: http, server, and location

Default value: 10M

msie_padding

Enables the disabling of adding comments to responses with a status greater than 400 for the MSIE clients, in order to pad the response size to 512 bytes.

Valid contexts: http, server, and location

Default value: on

msie_refresh

This directive enables the sending of a refresh instead of a redirect for the MSIE clients.

Valid contexts: http, server, and location

Default value: off

multi_accept

Instructs a worker process to accept all new connections at once. This directive is disregarded if the kqueue event method is used because kqueue reports the number of new connections waiting to be accepted.

Valid context: events

Default value: off

open_file_cache

Configures a cache that can store open file descriptors, directory lookups, and file lookup errors.

Valid contexts: http, server, and location

Default value: off

open_file_cache_errors

Enables the caching of the file lookup errors by the open_file_cache directive.

Valid contexts: http, server, and location

Default value: off

open_file_cache_min_uses

Configures the minimum number of uses for a file within the inactive parameter to open_file_cache for that file descriptor to remain open in the cache.

Valid contexts: http, server, and location

Default value: 1

open_file_cache_valid

Specifies the time interval between the validity checks for the items in the open_file_cache directive.

Valid contexts: http, server, and location

Default value: 60s

open_log_file_cache

For more information on this directive, refer to the table (HTTP logging directives) given in the Logging in NGINX section in Chapter 6, The NGINX HTTP Server.

Valid contexts: http, server, and location

Default value: off

override_charset

Indicates whether the charset specified in the Content-Type header of a response received from a proxy_pass or fastcgi_pass request should be converted or not. If the response comes as a result of a subrequest, conversion to the main request's charset will always be performed.

Valid contexts: http, server, location, and if in location

Default value: off

pcre_jit

Enables just-in-time compilation of Perl-compatible regular expressions known at configuration time. JIT support needs to be enabled in the PCRE library to make use of this speedup.

Valid context: main

Default value: off

perl

Activates a Perl handler for this location. The argument is the name of the handler or a string describing a full subroutine.

Valid contexts: location and limit_except

Default value: -

perl_modules

Specifies an additional search path for Perl modules.

Valid context: http

Default value: -

perl_require

Indicates a Perl module that will be loaded at each NGINX reconfiguration. It may be specified multiple times for separate modules.

Valid context: http

Default value: -

perl_set

Installs a Perl handler to set the value of a variable. The argument is the name of the handler or a string, describing a full subroutine.

Valid context: http

Default value: -

pid

The file where the process ID of the main process will be written, overwriting the compiled-in default.

Valid context: main

Default value: nginx.pid

pop3_auth

Sets the supported client authentication mechanism. It can be one or more of plain, apop, or cram-md5.

Valid contexts: mail and server

Default value: plain

pop3_capabilities

Indicates the POP3 capabilities that are supported by the backend server.

Valid contexts: mail and server

Default value: TOP USER UIDL

port_in_redirect

Determines whether or not the port will be specified in a redirect method issued by NGINX.

Valid contexts: http, server, and location

Default value: on

postpone_output

Specifies the minimum size of data for NGINX to send to the client. If possible, no data will be sent until this value is reached.

Valid contexts: http, server, and location

Default value: 1460

protocol

Indicates the protocol that is supported by this mail server context. It may be one of imap, pop3, or smtp.

Valid context: server

Default value: -

proxy

Enables or disables e-mail proxying.

Valid context: server

Default value: -

proxy_bind

Specifies the address that should be used for outgoing connections to a proxied server.

Valid contexts: http, server, and location

Default value: -

proxy_buffer

Allows setting the size of the buffer used for the mail proxy connection beyond the default of one page.

Valid contexts: mail and server

Default value: 4k|8k (platform dependent)

proxy_buffer_size

The size of the buffer used for the first part of the response from the upstream server, in which the response headers are found.

Valid contexts: http, server, and location

Default value: 4k|8k (platform dependent)

proxy_buffering

Activates the buffering of proxied content; when switched off, responses are sent synchronously to the client as soon as they are received.

Valid contexts: http, server, and location

Default value: on

proxy_buffers

The number and size of buffers used for responses from upstream servers.

Valid contexts: http, server, and location

Default value: 8 4k|8k (platform dependent)

proxy_busy_buffers_size

The total size of buffer space allocated to sending the response to the client while still being read from the upstream server. This is typically set to two proxy_buffers.

Valid contexts: http, server, and location

Default value: 8k|16k (platform dependent)

proxy_cache

Defines a shared memory zone to be used for caching.

Valid contexts: http, server, and location

Default value: off

proxy_cache_bypass

One or more string variables, which when nonempty or nonzero, will cause the response to be taken from the upstream server instead of the cache.

Valid contexts: http, server, and location

Default value: -

proxy_cache_convert_head

Converts HEAD to GET when caching.

Valid contexts: http, server, and location

Default value: on

proxy_cache_key

A string used as the key for storing and retrieving cache values.

Valid contexts: http, server, and location

Default value: $scheme$proxy_host$request_uri

proxy_cache_lock

Enabling this directive will prevent multiple requests from making an entry into the same cache key.

Valid contexts: http, server, and location

Default value: off

proxy_cache_lock_age

How long to wait for the proxy_cache_lock directive before passing the request to the upstream server.

Valid contexts: http, server, and location

Default value: 5s

proxy_cache_lock_timeout

The length of time a request will wait for an entry to appear in the cache or for the proxy_cache_lock directive to be released.

Valid contexts: http, server, and location

Default value: 5s

proxy_cache_methods

Which methods indicate that a request will be cached.

Valid contexts: http, server, and location

Default value: GET HEAD

proxy_cache_min_uses

The number of requests for a certain key needed before a response is cached.

Valid contexts: http, server, and location

Default value: 1

proxy_cache_path

For more information on this directive, to the table (Proxy module caching directives) given in the Caching data section in Chapter 5, Reverse Proxy Advanced Topics.

Valid context: http

Default value: -

proxy_cache_revalidate

Enables revalidation, depending on the values of the If-Modified-Since and If-None-Match headers.

Valid contexts: http, server, and location

Default value: off

proxy_cache_use_stale

The cases under which it is acceptable to serve stale cached data when an error occurs accessing the upstream server. The updating parameter indicates the case when fresh data are being loaded.

Valid contexts: http, server, and location

Default value: off

proxy_cache_valid

Indicates the length of time for which a cached response with the response code, 200, 301, or 302, is valid. If an optional response code is given before the time parameter, this time is only for that response code. The special parameter, any, indicates that any response code should be cached for that length of time.

Valid contexts: http, server, and location

Default value: -

proxy_connect_timeout

The maximum amount of time NGINX will wait for its connection to be accepted when making a request to an upstream server.

Valid contexts: http, server, and location

Default value: 60s

proxy_cookie_domain

Replaces the domain attribute of the Set-Cookie header from the upstream server; the domain to be replaced can either be a string or a regular expression, or reference a variable.

Valid contexts: http, server, and location

Default value: off

proxy_cookie_path

Replaces the path attribute of the Set-Cookie header from the upstream server; the path to be replaced can either be a string or a regular expression, or reference a variable.

Valid contexts: http, server, and location

Default value: off

proxy_force_ranges

Forces byte-range support irrespective of the value of the Accept-Ranges header.

Valid contexts: http, server, and location

Default value: off

proxy_header_hash_bucket_size

The bucket size used to hold proxy header names (one name cannot be longer than the value of this directive).

Valid contexts: http, server, location, and if

Default value: 64

proxy_header_hash_max_size

The total size of headers received from the upstream server.

Valid contexts: http, server, and location

Default value: 512

proxy_hide_header

A list of header fields that should not be passed on to the client.

Valid contexts: http, server, and location

Default value: -

proxy_http_version

The HTTP protocol version used to communicate with upstream servers (use 1.1 for keepalive connections).

Valid contexts: http, server, and location

Default value: 1.0

proxy_ignore_client_abort

If set to on, NGINX will not abort the connection to an upstream server if the client aborts the connection.

Valid contexts: http, server, and location

Default value: off

proxy_ignore_headers

Sets the headers that may be disregarded when processing the response from the upstream server.

Valid contexts: http, server, and location

Default value: -

proxy_intercept_errors

If enabled, NGINX will display a configured error_page instead of the response directly from the upstream server.

Valid contexts: http, server, and location

Default value: off

proxy_limit_rate

If buffering is enabled, the bytes/s at which the response from the upstream server will be read.

Valid contexts: http, server, and location

Default value: 0 (disabled)

proxy_max_temp_file_size

The maximum size of the overflow file, written when the response doesn't fit into memory buffers.

Valid contexts: http, server, and location

Default value: 1024m

proxy_method

The HTTP method to substitute when proxying to the upstream server.

Valid contexts: http, server, and location

Default value: -

proxy_next_upstream

Indicates the conditions under which the next upstream server will be selected for the response. This won't be used if the client has already been sent something. The conditions are specified using the following parameters:

Valid contexts: http, server, and location

Default value: error timeout

proxy_next_upstream_timeout

The number of seconds that pass before giving the request to the next server.

Valid contexts: http, server, and location

Default value: 0 (disabled)

proxy_next_upstream_tries

The number of tries before passing the request to the next server.

Valid contexts: http, server, and location

Default value: 0 (disabled)

proxy_no_cache

Defines the conditions under which the response will not be saved to the cache. The parameters are string variables, which evaluate to something nonempty and nonzero to not cache.

Valid contexts: http, server, and location

Default value: -

proxy_pass

Specifies the upstream server to which the request is passed, in the form of a URL.

Valid contexts: location, if in location, and limit_except

Default value: -

proxy_pass_error_message

Useful in situations where the backend authentication process emits a useful error message to the client.

Valid contexts: mail and server

Default value: off

proxy_pass_header

Overrides the disabled headers set in proxy_hide_header, allowing them to be sent to the client.

Valid contexts: http, server, and location

Default value: -

proxy_pass_request_body

Prevents sending the body of the request to the upstream server if set to off.

Valid contexts: http, server, and location

Default value: on

proxy_pass_request_headers

Prevents sending the headers of the request to the upstream server if set to off.

Valid contexts: http, server, and location

Default value: on

proxy_read_timeout

Specifies the length of time that needs to elapse between the two successive read operations from an upstream server before the connection is closed.

Valid contexts: http, server, and location

Default value: 60s

proxy_redirect

Rewrites the Location and Refresh headers received from the upstream servers; this directive is useful for working around assumptions made by an application framework.

Valid contexts: http, server, and location

Default value: default

proxy_request_buffering

Whether or not the complete client request body will be buffered before sending the request to the upstream server.

Valid contexts: http, server, and location

Default value: on

proxy_send_lowat

If non-zero, NGINX will try to minimize the number of send operations on outgoing connections to a proxied. It is ignored in Linux, Solaris, and Windows.

Valid contexts: http, server, and location

Default value: 0

proxy_send_timeout

The length of time that needs to elapse between two successive write operations to an upstream server before the connection is closed.

Valid contexts: http, server, and location

Default value: 60s

proxy_set_body

The body of a request sent to an upstream server may be altered by setting this directive.

Valid contexts: http, server, and location

Default value: -

proxy_set_header

Rewrites the contents of the headers sent to an upstream server; this directive may also be used to not send certain headers by setting its value to the empty string.

Valid contexts: http, server, and location

Default value: Host $proxy_host and Connection close

proxy_ssl_certificate

The path to a PEM-encoded file of the certificate to use for authenticating with an HTTPS upstream server.

Valid contexts: http, server, and location

Default value: -

proxy_ssl_certificate_key

The path to a PEM-encoded file of the secret key to use to use for authenticating with an HTTPS upstream server.

Valid contexts: http, server, and location

Default value: -

proxy_ssl_session_reuse

Sets whether or not SSL sessions may be reused when proxying.

Valid contexts: http, server, and location

Default value: on

proxy_store

Enables storing responses retrieved from an upstream server as files on disk. The on parameter will use the alias or root directive as the base path under which to store the file. A string may instead be given to indicate an alternative location to store the files.

Valid contexts: http, server, and location

Default value: off

proxy_store_access

Sets file access permissions for the newly-created proxy_store files.

Valid contexts: http, server, and location

Default value: user:rw

proxy_temp_file_write_size

Limits the amount of data buffered to a temporary file at one time so that NGINX will not be blocked for too long on a single request.

Valid contexts: http, server, and location

Default value: 8k|16k (platform dependent)

proxy_temp_path

A directory where temporary files may be buffered as they are proxied from the upstream server, optionally multilevel deep. If a second, third, or fourth parameter is given, these specify a subdirectory hierarchy with the parameter value as the number of characters in the subdirectory name.

Valid contexts: http, server, and location

Default value: proxy_temp

proxy_timeout

If a timeout beyond the default of 24 hours is required, this directive can be used.

Valid contexts: mail and server

Default value: 24h

random_index

Activates randomly choosing a file to be served to the client when a URI ending with / is received.

Valid context: location

Default value: off

read_ahead

If possible, the kernel will preread files up to the size parameter. This directive is supported on current FreeBSD and Linux (the size parameter is ignored on Linux).

Valid contexts: http, server, and location

Default value: 0

real_ip_header

Sets the header whose value is used as the client IP address when set_real_ip_from matches the connecting IP.

Valid contexts: http, server, and location

Default value: X-Real-IP

real_ip_recursive

Works with set_real_ip_from, to specify that the last address in a multivalued real_ip_header header will be used.

Valid contexts: http, server, and location

Default value: off

recursive_error_pages

Enables doing more than one redirect using the error_page directive (default is off).

Valid contexts: http, server, and location

Default value: off

referer_hash_bucket_size

The bucket size of the valid referers hash tables.

Valid contexts: server and location

Default value: 64

referer_hash_max_size

The maximum size of the valid referers hash tables.

Valid contexts: server and location

Default value: 2048

request_pool_size

Fine tunes per-request memory allocation.

Valid contexts: http and server

Default value: 4k

reset_timedout_connection

With this directive enabled, connections that have been timed out will immediately be reset, freeing all associated memory. The default value is to leave the socket in the FIN_WAIT1 state, which will always be the case for the keepalive connections.

Valid contexts: http, server, and location

Default value: off

resolver

Configures one or more name servers to be used to resolve upstream server names into IP addresses. An optional valid parameter overrides the TTL of the domain name record (now commercial).

Valid contexts: http, server, and location

Default value: -

resolver_timeout

Sets the timeout for name resolution (now commercial).

Valid contexts: http, server, and location

Default value: 30s

return

Stops processing and returns the specified code to the client. The nonstandard code, 444, will close the connection without sending any response headers. If a code additionally has text accompanying it, the text will be placed in the response body. If instead, a URL is given after the code, this URL will be the value of the Location header. A URL without a code is treated as a code 302.

Valid contexts: server, location, and if

Default value: -

rewrite

For more information on this directive, refer to the table (The rewrite module directives) given in the Introducing the rewrite module section in Appendix B, The Rewrite Rule Guide.

Valid contexts: server, location, and if

Default value: -

rewrite_log

Activates notice level logging of rewrites to the error_log.

Valid contexts: http, server, if in server, location, and if in location

Default value: off

root

Sets the path to the document root. Files are found by appending the URI to the value of this directive.

Valid contexts: http, server, location, and if in location

Default value: html

satisfy

Allows access if all or any of the access or auth_basic directives grant access. The default value, all, indicates that a user must come from a specific network address and enter the correct password.

Valid contexts: http, server, and location

Default value: all

satisfy_any

This is deprecated. Use the any parameter of the satisfy directive.

Valid contexts: http, server, and location

Default value: off

secure_link_secret

A salt used to compute the MD5 hash of a URI.

Valid context: location

Default value: -

send_lowat

If non-zero, NGINX will try to minimize the number of send operations on client sockets. This directive is ignored in Linux, Solaris, and Windows.

Valid contexts: http, server, and location

Default value: 0

send_timeout

This directive sets a timeout between two successive write operations for a client receiving a response.

Valid contexts: http, server, and location

Default value: 60s

sendfile

Enables using sendfile(2) to directly copy data from one file descriptor to another.

Valid contexts: http, server, location, if in location

Default value: off

sendfile_max_chunk

Sets the maximum size of data to copy in one sendfile(2) call to prevent a worker from seizing.

Valid contexts: http, server, and location

Default value: 0

server (http)

Creates a new configuration context, defining a virtual host. The listen directive specifies the IP address(es) and port(s); the server_name directive lists the Host header values that this context matches.

Valid context: http

Default value: -

server (upstream)

For more information on this directive, refer to the table (The upstream module directives) given in the The upstream module section in Chapter 4, NGINX as a Reverse Proxy.

Valid context: upstream

Default value: -

server (mail)

Creates a new configuration context, defining a mail server. The listen directive specifies the IP address(es) and port(s); the server_name directive sets the name of the server.

Valid context: mail

Default value: -

server_name (http)

Configures the names that a virtual host may respond to.

Valid context: server

Default value: ""

server_name (mail)

Sets the name of the server, which is used in the following ways:

Valid contexts: mail and server

Default value: hostname

server_name_in_redirect

Activates using the first value of the server_name directive in any redirect issued by NGINX within this context.

Valid contexts: http, server, and location

Default value: off

server_names_hash_bucket_size

The bucket size used to hold the server_name hash tables.

Valid context: http

Default value: 32|64|128 (processor dependent)

server_names_hash_max_size

The maximum size of the server_name hash tables.

Valid context: http

Default value: 512

server_tokens

Disables sending the NGINX version string in error messages and the Server response header (default value is on).

Valid contexts: http, server, and location

Default value: on

set

This directive sets a given variable to a specific value.

Valid context: server, location, and if

Default value: -

set_real_ip_from

Defines the connecting address(es) from which the client IP will be extracted from the real_ip_header directive. The value, unix:, means that all connections from the UNIX-domain sockets will be treated this way.

Valid contexts: http, server, and location

Default value: -

slice

The size of the slice to use when splitting a request into smaller, cacheable subrequests.

Valid contexts: http, server, and location

Default value: 0

smtp_auth

Sets the supported SASL client authentication mechanism. It can be one or more of login, plain, or cram-md5.

Valid contexts: mail and server

Default values: login and plain

smtp_capabilities

Indicates the SMTP capabilities that are supported by the backend server.

Valid contexts: mail and server

Default value: -

so_keepalive

Sets the TCP kee palive parameter on the socket connection to the proxied server.

Valid contexts: mail and server

Default value: off

source_charset

Defines the charset of a response. If it is different from the defined charset, a conversion is performed.

Valid contexts: http, server, location, and if in location

Default value: -

split_clients

Creates a context in which variables appropriate to A/B (or split) testing are set. The string specified in the first parameter is hashed using MurmurHash2. The variable specified in the second parameter is then set to a value based on how the string falls within the range of hash values. The match is specified as either a percentage or * to place weights on the values.

Valid context: http

default value: -

ssi

Enables the processing of SSI files.

Valid contexts: http, server, location, and if in location

Default value: off

ssi_min_file_chunk

Sets the minimum size of a file above which it should be sent using sendfile(2).

Valid contexts: http, server, and location

Default value: 1k

ssi_silent_errors

Suppresses the error message normally output when an error occurs during SSI processing.

Valid contexts: http, server, and location

Default value: off

ssi_types

Lists the MIME types of a response in addition to text/html in which the SSI commands are processed. It may be * to enable all MIME types.

Valid contexts: http, server, and location

Default value: text/html

ssi_value_length

Sets the maximum length of values for parameters used in Server Side Includes.

Valid contexts: http, server, and location

Default value: 256

ssl (http)

Enables the HTTPS protocol for this virtual server.

Valid contexts: http and server

Default value: off

ssl (mail)

Indicates if this context should support the SSL/TLS transactions.

Valid contexts: mail and server

Default value: off

ssl_buffer_size

The size of the buffer to use for sending data. Set low to minimize Time To First Byte.

Valid contexts: http and server

Default value: 16k

ssl_certificate (http)

The path to the file containing the SSL certificate for this server_name in the PEM format. If intermediate certificates are required, they need to be added in order after the certificate corresponding to the server_name directive, up to the root, if necessary.

Valid contexts: http and server

Default value: -

ssl_certificate (mail)

The path to the PEM-encoded SSL certificate(s) for this virtual server.

Valid contexts: mail and server

Default value: -

ssl_certificate_key (http)

This directive specifies the path to the file containing the SSL certificate's secret key.

Valid contexts: http and server

Default value: -

ssl_certificate_key (mail)

The path to the PEM-encoded SSL secret key for this virtual server.

Valid contexts: mail and server

Default value: -

ssl_ciphers

The ciphers that should be supported in this virtual server context (OpenSSL format).

Valid contexts: http and server

Default value: HIGH:!aNULL:!MD5

ssl_client_certificate

The path to the file containing the PEM-encoded public CA certificate(s) of the certificate authorities used to sign client certificates.

Valid contexts: http and server

Default value: -

ssl_crl

The path to the file containing the PEM-encoded certificate revocation list (CRL) for the client certificates that are to be verified.

Valid contexts: http and server

Default value: -

ssl_dhparam

The path to a file containing the DH parameters, used for the EDH ciphers.

Valid contexts: http and server

Default value: -

ssl_ecdh_curve

The curve to use for the ECDHE ciphers.

Valid contexts: http and server

Default value: prime256v1

ssl_engine

Specifies a hardware SSL accelerator.

Valid context: main

Default value: -

ssl_password_file

The path to a file, which contains passphrases for the secret keys used, one per line.

Valid contexts: http and server

Default value: -

ssl_prefer_server_ciphers (http)

Indicates that the server's ciphers are to be preferred over the client's ciphers when using the SSLv3 and TLS protocols.

Valid contexts: http and server

Default value: off

ssl_prefer_server_ciphers (mail)

Indicates that SSLv3 and TLSv1 server ciphers are preferred over the client's ciphers.

Valid contexts: mail and server

Default value: off

ssl_protocols (http)

Indicates the SSL protocols that should be enabled.

Valid contexts: http and server

Default value: TLSv1, TLSv1.1, and TLSv1.2

ssl_protocols (mail)

Indicates the SSL protocols that should be enabled.

Valid contexts: mail and server

Default value: TLSv1, TLSv1.1, and TLSv1.2

ssl_session_cache (http)

Sets the type and size of the SSL cache to store the session parameters. A cache can be one of the following types:

Valid contexts: http and server

Default value: none

ssl_session_cache (mail)

Sets the type and size of the SSL cache to store session parameters. A cache can be one of the following types:

Valid contexts: mail and server

Default value: none

ssl_session_timeout (http)

This directive specifies how long the client can use the same SSL parameters, provided they are stored in the cache.

Valid contexts: http and server

Default value: 5m

ssl_session_timeout (mail)

This directive specifies how long the client can use the same SSL parameters, provided they are stored in the cache.

Valid contexts: mail and server

Default value: 5m

ssl_stapling

This directive enables the stapling of OCSP responses. The CA certificate of the server's issuer should be contained in the file specified by ssl_trusted_certificate. A resolver should also be specified to be able to resolve the OCSP responder hostname.

Valid contexts: http and server

Default value: off

ssl_stapling_file

This directive specifies the path to a DER-formatted file containing the stapled OCSP response.

Valid contexts: http and server

Default value: -

ssl_stapling_responder

This directive specifies a URL specifying the OCSP responder. Only URLs beginning with http:// are currently supported.

Valid contexts: http and server

Default value: -

ssl_stapling_verify

This directive enables the verification of OCSP responses.

Valid contexts: http and server

Default value: -

ssl_trusted_certificate

This directive specifies the path to a file containing PEM-formatted SSL certificates of the CA's signing client certificates and OCSP responses when ssl_stapling is enabled.

Valid contexts: http and server

Default value: -

ssl_verify_client

Enables the verification of SSL client certificates. If the optional parameter is specified, a client certificate will be requested and, if present, verified. If the optional_no_ca parameter is specified, a client certificate is requested, but doesn't require it to be signed by a trusted CA certificate.

Valid contexts: http and server

Default value: off

ssl_verify_depth

Sets how many signers will be checked before declaring the certificate invalid.

Valid contexts: http and server

Default value: 1

starttls

Indicates whether or not STLS/STARTTLS are supported and/or required for further communication with this server.

Valid contexts: mail and server

Default value: off

sub_filter

The string to be matched without regards to case and the string to be substituted into that match. The substitution string may contain variables.

Valid contexts: http, server, and location

Default value: -

sub_filter_once

Setting this directive to off will cause the match in sub_filter to be made as many times as the string is found.

Valid contexts: http, server, and location

Default value: on

sub_filter_types

Lists the MIME types of a response in addition to text/html in which a substitution will be made. It may be * to enable all MIME types.

Valid contexts: http, server, and location

Default value: text/html

tcp_nodelay

Enables or disables the TCP_NODELAY option for keepalive connections.

Valid contexts: http, server, and location

Default value: on

tcp_nopush

This directive is relevant only when the sendfile directive is used. This directive enables NGINX to attempt to the send response headers in one packet, as well as sending a file in full packets.

Valid contexts: http, server, and location

Default value: off

threadpool

A named thread pool used for file I/O, so worker processes don't block.

Valid context: main

Default value: default threads=32 maxqueue=65536

timeout

The amount of time NGINX will wait before a connection to the backend server is finalized.

Valid contexts: mail and server

Default value: 60s

timer_resolution

Specifies how often gett imeofday() is called instead of each time a kernel event is received.

Valid context: main

Default value: -

try_files

Tests the existence of files given as parameters. If none of the previous files are found, the last entry is used as a fallback, so ensure that this path or named location exists.

Valid contexts: server and location

Default value: -

types

Sets up a map of MIME types to filename extensions. NGINX ships with a conf/mime.types file that contains most MIME type mappings. Using include to load this file should be sufficient for most purposes.

Valid contexts: http, server, and location

Default value: This value is as follows:

text/html html;

image/gif gif;

image/jpeg jpg

types_hash_bucket_size

The bucket size used to hold the types hash tables.

Valid contexts: http, server, and location

Default value: 32|64|128 (processor dependent)

types_hash_max_size

The maximum size of the types hash tables.

Valid contexts: http, server, and location

Default value: 1024

underscores_in_headers

Enables the use of the underscore character in client request headers. If left at the default value off, evaluation of such headers is subject to the value of the ignore_invalid_headers directive.

Valid contexts: http and server

Default value: off

uninitialized_variable_warn

Controls whether or not warnings about uninitialized variables are logged.

Valid contexts: http, server, location, and if

Default value: on

upstream

Sets up a named context in which a group of servers is defined.

Valid context: http

Default value: -

use

The use directive indicates the connection processing method that should be used. This will overwrite the compiled-in default value, and must be contained in an events context, if used. It is especially useful when the compiled-in default value is found to produce errors over time.

Valid context: events

Default value: -

user

The user and group under which the worker processes will run is configured using this parameter. If the group is omitted, a group name equal to that of the user will be used.

Valid context: main

Default value: nobody nobody

userid

Activates the module, according to the following parameters:

Valid contexts: http, server, and location

Default value: off

userid_domain

Configures a domain to be set in the cookie.

Valid contexts: http, server, and location

Default value: none

userid_expires

Sets the age of the cookie. If the keyword max is used, this directive translates to 31 Dec 2037 23:55:55 GMT.

Valid contexts: http, server, and location

Default value: -

userid_mark

Sets the first character of the tail of the base64 representation of the userid_name cookie.

Valid contexts: http, server, and location

Default value: off

userid_name

Sets the name of the cookie.

Valid contexts: http, server, and location

Default value: uid

userid_p3p

Configures the P3P header.

Valid contexts: http, server, and location

Default value: -

userid_path

Defines the path set in the cookie.

Valid contexts: http, server, and location

Default value: /

userid_service

Identity of the service that set the cookie. For example, the default value for Version 2 cookies is the IP address of the server that set the cookie.

Valid contexts: http, server, and location

Default value: The IP address of the server

valid_referers

Defines the values of the Referer header that will cause the $invalid_referer variable to be set to an empty string. Otherwise, it will be set to 1. The parameters can be one or more of the following:

Valid context: server and location

Default value: -

variables_hash_bucket_size

The bucket size used to hold the remaining variables.

Valid context: http

Default value: 64

variables_hash_max_size

The maximum size of the hash that holds the remaining variables.

Valid context: http

Default value: 1024

worker_aio_requests

The number of open asynchronous I/O operations for a single worker process when using aio with epoll.

Valid context: events

Default value: 32

worker_connections

This directive configures the maximum number of simultaneous connections that a worker process may have open. This includes, but is not limited to, the client connections and connections to upstream servers.

Valid context: events

Default value: 512

worker_cpu_affinity

Binds worker processes to CPU sets, as specified by a bitmask. This directive is only available on FreeBSD and Linux.

Valid context: main

Default value: -

worker_priority

Sets the scheduling priority for worker processes. This directive works like the nice command, with a negative number being a higher priority.

Valid context: main

Default value: 0

worker_processes

This is the number of worker processes that will be started. These processes will handle all connections made by clients. Choosing the right number is a complex process; a good rule of thumb is to set this equal to the number of CPU cores.

Valid context: main

Default value: 1

worker_rlimit_core

Changes the limit on core file size of a running process.

Valid context: main

Default value: -

worker_rlimit_nofile

Changes the limit on the number of open files of a running process.

Valid context: main

Default value: -

worker_rlimit_sigpending

Changes the limit on the number of pending signals of a running process when using the rtsig connection processing method.

Valid context: main

Default value: -

working_directory

The current working directory for worker processes. It should be writable by the worker to produce core files.

Valid context: main

Default value: -

xclient

The SMTP protocol allows checking based on the IP, HELO, or LOGIN parameters, which are passed via the XCLIENT command. This directive enables NGINX to communicate this information.

Valid contexts: mail and server

Default value: on

xml_entities

The path to the DTD that declares the character entities referenced in the XML to be processed.

Valid contexts: http, server, and location

default value: -

xslt_last_modified

Whether or not to preserve the Last-Modified header when doing an XSLT transformation.

Valid contexts: http, server, and location

Default value: off

xslt_param

Parameters passed to the stylesheets, whose values are the XPath expressions.

Valid contexts: http, server, and location

Default value: -

xslt_string_param

Parameters passed to the stylesheets, whose values are strings.

Valid contexts: http, server, and location

Default value: -

xslt_stylesheet

The path to an XSLT stylesheet used to transform an XML response. Parameters may be passed as a series of key/value pairs.

Valid context: location

Default value: -

xslt_types

Lists the MIME types of a response in addition to text/xml, in which a substitution will be made. It may be * to enable all MIME types. If the transformation results in an HTML response, the MIME type will be changed to text/html.

Valid contexts: http, server, and location

Default value: text/xml