syntax 1
\n", "syntax 2
\n"}, DescriptionMd: "Test", DescriptionHtml: "Test
\n", }, @@ -66,7 +67,8 @@ func TestWrite(t *testing.T) { Name: "Directive 1", Default: "Default", Contexts: []string{"Context 1", "Context 2"}, - Syntax: []string{"I am Syntax"}, + SyntaxMd: []string{"I am Syntax"}, + SyntaxHtml: []string{"I am Syntax
"}, DescriptionMd: "It is a directive", DescriptionHtml: "It is a directive
", }, diff --git a/reference-converter/internal/parse/elements.go b/reference-converter/internal/parse/elements.go index 702f9a6..da1428d 100644 --- a/reference-converter/internal/parse/elements.go +++ b/reference-converter/internal/parse/elements.go @@ -33,6 +33,19 @@ func (ss Syntaxes) ToMarkdown() []string { return ret } +func (ss Syntaxes) ToHTML() []string { + if len(ss) == 0 { + return nil + } + + ret := make([]string, 0, len(ss)) + for _, s := range ss { + md := []byte(s.ToMarkdown()) + ret = append(ret, string(mdToHTML(md))) + } + return ret +} + func (ss Syntaxes) IsBlock() bool { isBlock := false for _, s := range ss { diff --git a/reference-lib/index.ts b/reference-lib/index.ts index 2444dbe..fce6fd3 100644 --- a/reference-lib/index.ts +++ b/reference-lib/index.ts @@ -51,7 +51,7 @@ export function getDirectives(format=Format.HTML): Directive[] { name: d.name, module: d.module, description: format === Format.HTML ? d.description_html : d.description_md, - syntax: d.syntax, + syntax: format === Format.HTML ? d.syntax_html : d.syntax_md, contexts: d.contexts, isBlock: d.isBlock, default: d.default diff --git a/reference-lib/package-lock.json b/reference-lib/package-lock.json index 93b0719..7897c9e 100644 --- a/reference-lib/package-lock.json +++ b/reference-lib/package-lock.json @@ -1,12 +1,12 @@ { "name": "@nginxinc/reference-lib", - "version": "1.0.0", + "version": "1.0.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@nginxinc/reference-lib", - "version": "1.0.0", + "version": "1.0.1", "devDependencies": { "@rollup/plugin-json": "^6.0.0", "@rollup/plugin-typescript": "^11.1.2", diff --git a/reference-lib/package.json b/reference-lib/package.json index 2d00476..c9f1aa8 100644 --- a/reference-lib/package.json +++ b/reference-lib/package.json @@ -1,6 +1,6 @@ { "name": "@nginxinc/reference-lib", - "version": "1.0.0", + "version": "1.0.1", "description": "", "main": "dist/index.js", "scripts": { diff --git a/reference-lib/src/__mocks__/reference_mock.json b/reference-lib/src/__mocks__/reference_mock.json index 4d9df0c..64e8b91 100644 --- a/reference-lib/src/__mocks__/reference_mock.json +++ b/reference-lib/src/__mocks__/reference_mock.json @@ -12,9 +12,12 @@ "location", "limit_except" ], - "syntax": [ + "syntax_md": [ "*`address`* | *`CIDR`* | `unix:` | `all`" ], + "syntax_html": [ + "address | CIDR | unix: | all
address | CIDR | unix: | all
Allows access for the specified network or address.\nIf the special value unix: is specified (1.5.1),\nallows access for all UNIX-domain sockets.
address | CIDR | unix: | all
Denies access for the specified network or address.\nIf the special value unix: is specified (1.5.1),\ndenies access for all UNIX-domain sockets.
uri
Adds the text returned as a result of processing a given subrequest\nbefore the response body.\nAn empty string ("") as a parameter cancels addition\ninherited from the previous configuration level.
uri
Adds the text returned as a result of processing a given subrequest\nafter the response body.\nAn empty string ("") as a parameter cancels addition\ninherited from the previous configuration level.
mime-type …
Allows adding text in responses with the specified MIME types,\nin addition to “text/html”.\nThe special value “*” matches any MIME type (0.8.29).
[write=on|off]
Turns on the REST API interface in the surrounding location.\nAccess to this location should be\nlimited.
\n\nThe write parameter determines whether the API\nis read-only or read-write.\nBy default, the API is read-only.
All API requests should contain a supported API version in the URI.\nIf the request URI equals the location prefix,\nthe list of supported API versions is returned.\nThe current API version is “9”.
The optional “fields” argument in the request line\nspecifies which fields of the requested objects will be output:
http://127.0.0.1/api/9/nginx?fields=version,build\nzone
Enables collection of virtual\nhttp\nor\nstream\nserver status information in the specified zone.\nSeveral servers may share the same zone.
Starting from 1.17.0, status information can be collected\nper location.\nThe special value off disables statistics collection\nin nested location blocks.\nNote that the statistics is collected\nin the context of a location where processing ends.\nIt may be different from the original location, if an\ninternal redirect happens during request processing.
string | off
Enables validation of user name and password using the\n“HTTP Basic Authentication” protocol.\nThe specified parameter is used as a realm.\nParameter value can contain variables (1.3.10, 1.2.7).\nThe special value off cancels the effect\nof the auth_basic directive\ninherited from the previous configuration level.
file
Specifies a file that keeps user names and passwords,\nin the following format:
\n\n# comment\nname1:password1\nname2:password2:comment\nname3:password3\nThe file name can contain variables.
The following password types are supported:
\n\ncrypt() function; can be generated using\nthe “htpasswd” utility from the Apache HTTP Server\ndistribution or the “openssl passwd” command;{scheme}*data*”\nsyntax (1.0.3+) as described in\nRFC 2307;\ncurrently implemented schemes include PLAIN (an example one,\nshould not be used), SHA (1.3.13) (plain SHA-1\nhashing, should not be used) and SSHA (salted SHA-1 hashing,\nused by some software packages, notably OpenLDAP and Dovecot).\n> Support for SHA scheme was added only to aid\n> in migration from other web servers.\n> It should not be used for new passwords, since unsalted SHA-1 hashing\n> that it employs is vulnerable to\n> rainbow table\n> attacks.string [token=$variable] | off
Enables validation of JSON Web Token.\nThe specified string is used as a realm.\nParameter value can contain variables.
The optional token parameter specifies a variable\nthat contains JSON Web Token.\nBy default, JWT is passed in the “Authorization” header\nas a\nBearer Token.\nJWT may be also passed as a cookie or a part of a query string:
auth_jwt "closed site" token=$cookie_auth_token;\nThe special value off cancels the effect\nof the auth_jwt directive\ninherited from the previous configuration level.
$variable name …
Sets the variable to a JWT claim parameter\nidentified by key names.\nName matching starts from the top level of the JSON tree.\nFor arrays, the variable keeps a list of array elements separated by commas.
auth_jwt_claim_set $email info e-mail;\nauth_jwt_claim_set $job info "job title";\n\n\n" @@ -200,9 +233,12 @@ "contexts": [ "http" ], - "syntax": [ + "syntax_md": [ "*`$variable`* *`name`* ..." ], + "syntax_html": [ + "Prior to version 1.13.7, only one key name could be specified,\nand the result was undefined for arrays.
\n\nVariable values for tokens encrypted with JWE\nare available only after decryption which occurs during the\nAccess phase.
\n
$variable name …
Sets the variable to a JOSE header parameter\nidentified by key names.\nName matching starts from the top level of the JSON tree.\nFor arrays, the variable keeps a list of array elements separated by commas.
\n\n" @@ -215,9 +251,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "Prior to version 1.13.7, only one key name could be specified,\nand the result was undefined for arrays.
\n
time
Enables or disables caching of keys\nobtained from a file\nor from a subrequest,\nand sets caching time for them.\nCaching of keys obtained from variables is not supported.\nBy default, caching of keys is disabled.
\n" @@ -231,9 +270,12 @@ "location", "limit_except" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "file
Specifies a file in\nJSON Web Key Set\nformat for validating JWT signature.\nParameter value can contain variables.
Several auth_jwt_key_file directives\ncan be specified on the same level (1.21.1):
auth_jwt_key_file conf/keys.json;\nauth_jwt_key_file conf/key.jwk;\nIf at least one of the specified keys cannot be loaded or processed,\nnginx will return the\n500 (Internal Server Error) error.
\n" @@ -247,9 +289,12 @@ "location", "limit_except" ], - "syntax": [ + "syntax_md": [ "*`uri`*" ], + "syntax_html": [ + "uri
Allows retrieving a\nJSON Web Key Set\nfile from a subrequest for validating JWT signature and\nsets the URI where the subrequest will be sent to.\nParameter value can contain variables.\nTo avoid validation overhead,\nit is recommended to cache the key file:
\n\nproxy_cache_path /data/nginx/cache levels=1 keys_zone=foo:10m;\n\nserver {\n ...\n\n location / {\n auth_jwt "closed site";\n auth_jwt_key_request /jwks_uri;\n }\n\n location = /jwks_uri {\n internal;\n proxy_cache foo;\n proxy_pass http://idp.example.com/keys;\n }\n}\nSeveral auth_jwt_key_request directives\ncan be specified on the same level (1.21.1):
auth_jwt_key_request /jwks_uri;\nauth_jwt_key_request /jwks2_uri;\nIf at least one of the specified keys cannot be loaded or processed,\nnginx will return the\n500 (Internal Server Error) error.
\n" @@ -262,9 +307,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Sets the maximum allowable leeway to compensate\nclock skew when verifying the\nexp\nand\nnbf\nJWT claims.
\n" @@ -278,9 +326,12 @@ "location", "limit_except" ], - "syntax": [ + "syntax_md": [ "*`signed`* | *`encrypted`* | *`nested`*" ], + "syntax_html": [ + "signed | encrypted | nested
Specifies which type of JSON Web Token to expect:\nJWS (signed),\nJWE (encrypted),\nor signed and then encrypted\nNested JWT (nested) (1.21.0).
$value … [error=401 | 403]
Specifies additional checks for JWT validation.\nThe value can contain text, variables, and their combination,\nand must start with a variable (1.21.7).\nThe authentication will succeed only\nif all the values are not empty and are not equal to “0”.
\n\nmap $jwt_claim_iss $valid_jwt_iss {\n "good" 1;\n}\n...\n\nauth_jwt_require $valid_jwt_iss;\nIf any of the checks fails,\nthe 401 error code is returned.\nThe optional error parameter (1.21.7)\nallows redefining the error code to 403.
uri | off
Enables authorization based on the result of a subrequest and sets\nthe URI to which the subrequest will be sent.
\n" @@ -330,9 +387,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`$variable`* *`value`*" ], + "syntax_html": [ + "$variable value
Sets the request variable to the given\nvalue after the authorization request completes.\nThe value may contain variables from the authorization request,\nsuch as $upstream_http_*.
on | off
Enables or disables the directory listing output.
\n" @@ -366,9 +429,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
For the HTML format,\nspecifies whether exact file sizes should be output in the directory listing,\nor rather rounded to kilobytes, megabytes, and gigabytes.
\n" @@ -381,9 +447,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`html` | `xml` | `json` | `jsonp`" ], + "syntax_html": [ + "html | xml | json | jsonp
Sets the format of a directory listing.
\n\nWhen the JSONP format is used, the name of a callback function is set\nwith the callback request argument.\nIf the argument is missing or has an empty value,\nthen the JSON format is used.
The XML output can be transformed using the\nngx_http_xslt_module module.
\n" @@ -396,9 +465,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
For the HTML format,\nspecifies whether times in the directory listing should be\noutput in the local time zone or UTC.
\n" @@ -417,9 +489,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`string`* ..." ], + "syntax_html": [ + "string …
If any of the specified substrings is found in the “User-Agent”\nrequest header field, the browser will be considered ancient.\nThe special string “netscape4” corresponds to the\nregular expression “^Mozilla/[1-4]”.
string
Sets a value for the $ancient_browser variables.
browser version
unlisted
Specifies a version starting from which a browser is considered modern.\nA browser can be any one of the following: msie,\ngecko (browsers based on Mozilla),\nopera, safari,\nor konqueror.
Versions can be specified in the following formats: X, X.X, X.X.X, or X.X.X.X.\nThe maximum values for each of the format are\n4000, 4000.99, 4000.99.99, and 4000.99.99.99, respectively.
\n\nThe special value unlisted specifies to consider\na browser as modern if it was not listed by the\nmodern_browser and ancient_browser\ndirectives.\nOtherwise such a browser is considered ancient.\nIf a request does not provide the “User-Agent” field\nin the header, the browser is treated as not being listed.
string
Sets a value for the $modern_browser variables.
charset | off
Adds the specified charset to the “Content-Type”\nresponse header field.\nIf this charset is different from the charset specified\nin the source_charset directive, a conversion is performed.
The parameter off cancels the addition of charset\nto the “Content-Type” response header field.
A charset can be defined with a variable:
\n\ncharset $charset;\nIn such a case, all possible values of a variable need to be present\nin the configuration at least once in the form of the\ncharset_map, charset, or\nsource_charset directives.\nFor utf-8, windows-1251, and\nkoi8-r charsets, it is sufficient to include the files\nconf/koi-win, conf/koi-utf, and\nconf/win-utf into configuration.\nFor other charsets, simply making a fictitious conversion table works,\nfor example:
charset_map iso-8859-5 _ { }\nIn addition, a charset can be set in the\n“X-Accel-Charset” response header field.\nThis capability can be disabled using the\nproxy_ignore_headers,\nfastcgi_ignore_headers,\nuwsgi_ignore_headers,\nscgi_ignore_headers,\nand\ngrpc_ignore_headers\ndirectives.
charset1 charset2 {...}
Describes the conversion table from one charset to another.\nA reverse conversion table is built using the same data.\nCharacter codes are given in hexadecimal.\nMissing characters in the range 80-FF are replaced with “?”.\nWhen converting from UTF-8, characters missing in a one-byte charset\nare replaced with “&#XXXX;”.
Example:
\n\ncharset_map koi8-r windows-1251 {\n C0 FE ; # small yu\n C1 E0 ; # small a\n C2 E1 ; # small b\n C3 F6 ; # small ts\n ...\n}\nWhen describing a conversion table to UTF-8, codes for the UTF-8 charset should\nbe given in the second column, for example:
\n\ncharset_map koi8-r utf-8 {\n C0 D18E ; # small yu\n C1 D0B0 ; # small a\n C2 D0B1 ; # small b\n C3 D186 ; # small ts\n ...\n}\nFull conversion tables from koi8-r to\nwindows-1251, and from koi8-r and\nwindows-1251 to utf-8\nare provided in the distribution files conf/koi-win,\nconf/koi-utf, and conf/win-utf.
mime-type …
Enables module processing in responses with the specified MIME types\nin addition to “text/html”.\nThe special value “*” matches any MIME type (0.8.29).
\n\n" @@ -529,9 +623,12 @@ "location", "if in location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "Until version 1.5.4, “
\napplication/x-javascript” was used\nas the default MIME type instead of “application/javascript”.
on | off
Determines whether a conversion should be performed for answers\nreceived from a proxied or a FastCGI/uwsgi/SCGI/gRPC server\nwhen the answers already carry a charset in the “Content-Type”\nresponse header field.\nIf conversion is enabled, a charset specified in the received\nresponse is used as a source charset.
\n\n\n\n" @@ -545,9 +642,12 @@ "location", "if in location" ], - "syntax": [ + "syntax_md": [ "*`charset`*" ], + "syntax_html": [ + "It should be noted that if a response is received in a subrequest\nthen the conversion from the response charset to the main request charset\nis always performed, regardless of the
\noverride_charset\ndirective setting.
charset
Defines the source charset of a response.\nIf this charset is different from the charset specified\nin the charset directive, a conversion is performed.
on | off
If disabled, redirects issued by nginx will be relative.
\n\nSee also server_name_in_redirect\nand port_in_redirect directives.
on | off | threads[=pool]
Enables or disables the use of asynchronous file I/O (AIO)\non FreeBSD and Linux:
\n\nlocation /video/ {\n aio on;\n output_buffers 1 64k;\n}\nOn FreeBSD, AIO can be used starting from FreeBSD 4.3.\nPrior to FreeBSD 11.0,\nAIO can either be linked statically into a kernel:
\n\noptions VFS_AIO\nor loaded dynamically as a kernel loadable module:
\n\nkldload aio\nOn Linux, AIO can be used starting from kernel version 2.6.22.\nAlso, it is necessary to enable\ndirectio,\nor otherwise reading will be blocking:
location /video/ {\n aio on;\n directio 512;\n output_buffers 1 128k;\n}\nOn Linux,\ndirectio\ncan only be used for reading blocks that are aligned on 512-byte\nboundaries (or 4K for XFS).\nFile’s unaligned end is read in blocking mode.\nThe same holds true for byte range requests and for FLV requests\nnot from the beginning of a file: reading of unaligned data at the\nbeginning and end of a file will be blocking.
When both AIO and sendfile are enabled on Linux,\nAIO is used for files that are larger than or equal to\nthe size specified in the directio directive,\nwhile sendfile is used for files of smaller sizes\nor when directio is disabled.
location /video/ {\n sendfile on;\n aio on;\n directio 8m;\n}\nFinally, files can be read and sent\nusing multi-threading (1.7.11),\nwithout blocking a worker process:
\n\nlocation /video/ {\n sendfile on;\n aio threads;\n}\nRead and send file operations are offloaded to threads of the specified\npool.\nIf the pool name is omitted,\nthe pool with the name “default” is used.\nThe pool name can also be set with variables:
aio threads=pool$disk;\nBy default, multi-threading is disabled, it should be\nenabled with the\n--with-threads configuration parameter.\nCurrently, multi-threading is compatible only with the\nepoll,\nkqueue,\nand\neventport methods.\nMulti-threaded sending of files is only supported on Linux.
See also the sendfile directive.
on | off
If aio is enabled, specifies whether it is used for writing files.\nCurrently, this only works when using\naio threads\nand is limited to writing temporary files\nwith data received from proxied servers.
path
Defines a replacement for the specified location.\nFor example, with the following configuration
\n\nlocation /i/ {\n alias /data/w3/images/;\n}\non request of\n“/i/top.gif”, the file\n/data/w3/images/top.gif will be sent.
The path value can contain variables,\nexcept $document_root and $realpath_root.
If alias is used inside a location defined\nwith a regular expression then such regular expression should\ncontain captures and alias should refer to\nthese captures (0.7.40), for example:
location ~ ^/users/(.+\\.(?:gif|jpe?g|png))$ {\n alias /data/w3/images/$1;\n}\nWhen location matches the last part of the directive’s value:
\n\nlocation /images/ {\n alias /data/w3/images/;\n}\nit is better to use the\nroot\ndirective instead:
location /images/ {\n root /data/w3;\n}\ntime
Delays processing of unauthorized requests with 401 response code\nto prevent timing attacks when access is limited by\npassword, by the\nresult of subrequest,\nor by JWT.
\n" @@ -639,9 +754,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Allows disabling chunked transfer encoding in HTTP/1.1.\nIt may come in handy when using a software failing to support\nchunked encoding despite the standard’s requirement.
\n" @@ -654,9 +772,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
Sets buffer size for reading client request body.\nIn case the request body is larger than the buffer,\nthe whole body or only its part is written to a\ntemporary file.\nBy default, buffer size is equal to two memory pages.\nThis is 8K on x86, other 32-bit platforms, and x86-64.\nIt is usually 16K on other 64-bit platforms.
\n" @@ -669,9 +790,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `clean` | `off`" ], + "syntax_html": [ + "on | clean | off
Determines whether nginx should save the entire client request body\ninto a file.\nThis directive can be used during debugging, or when using the\n$request_body_file\nvariable, or the\n$r->request_body_file\nmethod of the module\nngx_http_perl_module.
When set to the value on, temporary files are not\nremoved after request processing.
The value clean will cause the temporary files\nleft after request processing to be removed.
on | off
Determines whether nginx should save the entire client request body\nin a single buffer.\nThe directive is recommended when using the\n$request_body\nvariable, to save the number of copy operations involved.
path [level1 [level2 [level3]]]
Defines a directory for storing temporary files holding client request bodies.\nUp to three-level subdirectory hierarchy can be used under the specified\ndirectory.\nFor example, in the following configuration
\n\nclient_body_temp_path /spool/nginx/client_temp 1 2;\na path to a temporary file might look like this:
\n\n/spool/nginx/client_temp/7/45/00000123457\ntime
Defines a timeout for reading client request body.\nThe timeout is set only for a period between two successive read operations,\nnot for the transmission of the whole request body.\nIf a client does not transmit anything within this time, the\nrequest is terminated with the\n408 (Request Time-out)\nerror.
\n" @@ -728,9 +861,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
Sets buffer size for reading client request header.\nFor most requests, a buffer of 1K bytes is enough.\nHowever, if a request includes long cookies, or comes from a WAP client,\nit may not fit into 1K.\nIf a request line or a request header field does not fit into\nthis buffer then larger buffers, configured by the\nlarge_client_header_buffers directive,\nare allocated.
If the directive is specified on the server level,\nthe value from the default server can be used.\nDetails are provided in the\n“Virtual server selection” section.
time
Defines a timeout for reading client request header.\nIf a client does not transmit the entire header within this time, the\nrequest is terminated with the\n408 (Request Time-out)\nerror.
\n" @@ -757,9 +896,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
Sets the maximum allowed size of the client request body.\nIf the size in a request exceeds the configured value, the\n413 (Request Entity Too Large)\nerror is returned to the client.\nPlease be aware that\nbrowsers cannot correctly display\nthis error.\nSetting size to 0 disables checking of client\nrequest body size.
size
Allows accurate tuning of per-connection memory allocations.\nThis directive has minimal impact on performance\nand should not generally be used.\nBy default, the size is equal to\n256 bytes on 32-bit platforms and 512 bytes on 64-bit platforms.
\n\n\n\n" @@ -786,9 +931,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`mime-type`*" ], + "syntax_html": [ + "Prior to version 1.9.8, the default value was 256 on all platforms.
\n
mime-type
Defines the default MIME type of a response.\nMapping of file name extensions to MIME types can be set\nwith the types directive.
size | off
Enables the use of\nthe O_DIRECT flag (FreeBSD, Linux),\nthe F_NOCACHE flag (macOS),\nor the directio() function (Solaris),\nwhen reading files that are larger than or equal to\nthe specified size.\nThe directive automatically disables (0.7.15) the use of\nsendfile\nfor a given request.\nIt can be useful for serving large files:
directio 4m;\nor when using aio on Linux.
size
Sets the alignment for\ndirectio.\nIn most cases, a 512-byte alignment is enough.\nHowever, when using XFS under Linux, it needs to be increased to 4K.
off
on | if_not_owner [from=part]
Determines how symbolic links should be treated when opening files:
\n\noff
Symbolic links in the pathname are allowed and not checked.\nThis is the default behavior.
on
If any component of the pathname is a symbolic link,\naccess to a file is denied.
if_not_owner
Access to a file is denied if any component of the pathname\nis a symbolic link, and the link and object that the link\npoints to have different owners.
from=part
When checking symbolic links\n(parameters on and if_not_owner),\nall components of the pathname are normally checked.\nChecking of symbolic links in the initial part of the pathname\nmay be avoided by specifying additionally the\nfrom=part parameter.\nIn this case, symbolic links are checked only from\nthe pathname component that follows the specified initial part.\nIf the value is not an initial part of the pathname checked, the whole\npathname is checked as if this parameter was not specified at all.\nIf the value matches the whole file name,\nsymbolic links are not checked.\nThe parameter value can contain variables.
Example:
\n\ndisable_symlinks on from=$document_root;\nThis directive is only available on systems that have the\nopenat() and fstatat() interfaces.\nSuch systems include modern versions of FreeBSD, Linux, and Solaris.
Parameters on and if_not_owner\nadd a processing overhead.
\n\n" @@ -848,9 +1006,12 @@ "location", "if in location" ], - "syntax": [ + "syntax_md": [ "*`code`* ... [`=`[*`response`*]] *`uri`*" ], + "syntax_html": [ + "On systems that do not support opening of directories only for search,\nto use these parameters it is required that worker processes\nhave read permissions for all directories being checked.
\n\nThe\nngx_http_autoindex_module,\nngx_http_random_index_module,\nand ngx_http_dav_module\nmodules currently ignore this directive.
\n
code … [=[response]] uri
Defines the URI that will be shown for the specified errors.\nA uri value can contain variables.
Example:
\n\nerror_page 404 /404.html;\nerror_page 500 502 503 504 /50x.html;\nThis causes an internal redirect to the specified uri\nwith the client request method changed to “GET”\n(for all methods other than\n“GET” and “HEAD”).
Furthermore, it is possible to change the response code to another\nusing the “=*response*” syntax, for example:
error_page 404 =200 /empty.gif;\nIf an error response is processed by a proxied server\nor a FastCGI/uwsgi/SCGI/gRPC server,\nand the server may return different response codes (e.g., 200, 302, 401\nor 404), it is possible to respond with the code it returns:
\n\nerror_page 404 = /404.php;\nIf there is no need to change URI and method during internal redirection\nit is possible to pass error processing into a named location:
\n\nlocation / {\n error_page 404 = @fallback;\n}\n\nlocation @fallback {\n proxy_pass http://backend;\n}\n\n\n\nIf
\nuriprocessing leads to an error,\nthe status code of the last occurred error is returned to the client.
It is also possible to use URL redirects for error processing:
\n\nerror_page 403 http://example.com/forbidden.html;\nerror_page 404 =301 http://example.com/notfound.html;\nIn this case, by default, the response code 302 is returned to the client.\nIt can only be changed to one of the redirect status\ncodes (301, 302, 303, 307, and 308).
\n\n\n\n\nThe code 307 was not treated as a redirect until versions 1.1.16 and 1.0.13.
\n\nThe code 308 was not treated as a redirect until version 1.13.0.
\n
These directives are inherited from the previous configuration level\nif and only if there are no error_page directives\ndefined on the current level.
on | off
Enables or disables automatic generation of the “ETag”\nresponse header field for static resources.
\n" @@ -876,9 +1040,12 @@ "contexts": [ "main" ], - "syntax": [ + "syntax_md": [ " `{...}`" ], + "syntax_html": [ + "{...}
Provides the configuration file context in which the HTTP server directives\nare specified.
\n" @@ -891,9 +1058,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`off` | `exact` | `before`" ], + "syntax_html": [ + "off | exact | before
Specifies how to compare modification time of a response\nwith the time in the\n“If-Modified-Since”\nrequest header field:
\n\noff
the response is always considered modified (0.7.34);
exact
exact match;
before
modification time of the response is\nless than or equal to the time in the “If-Modified-Since”\nrequest header field.
on | off
Controls whether header fields with invalid names should be ignored.\nValid names are composed of English letters, digits, hyphens, and possibly\nunderscores (as controlled by the underscores_in_headers\ndirective).
If the directive is specified on the server level,\nthe value from the default server can be used.\nDetails are provided in the\n“Virtual server selection” section.
none | browser …
Disables keep-alive connections with misbehaving browsers.\nThe browser parameters specify which\nbrowsers will be affected.\nThe value msie6 disables keep-alive connections\nwith old versions of MSIE, once a POST request is received.\nThe value safari disables keep-alive connections\nwith Safari and Safari-like browsers on macOS and macOS-like\noperating systems.\nThe value none enables keep-alive connections\nwith all browsers.
\n\n" @@ -948,9 +1127,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "Prior to version 1.1.18, the value
\nsafarimatched\nall Safari and Safari-like browsers on all operating systems, and\nkeep-alive connections with them were disabled by default.
number
Sets the maximum number of requests that can be\nserved through one keep-alive connection.\nAfter the maximum number of requests are made, the connection is closed.
\n\nClosing connections periodically is necessary to free\nper-connection memory allocations.\nTherefore, using too high maximum number of requests\ncould result in excessive memory usage and not recommended.
\n\n\n\n" @@ -963,9 +1145,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "Prior to version 1.19.10, the default value was 100.
\n
time
Limits the maximum time during which\nrequests can be processed through one keep-alive connection.\nAfter this time is reached, the connection is closed\nfollowing the subsequent request processing.
\n" @@ -978,9 +1163,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`timeout`* [*`header_timeout`*]" ], + "syntax_html": [ + "timeout [header_timeout]
The first parameter sets a timeout during which a keep-alive\nclient connection will stay open on the server side.\nThe zero value disables keep-alive client connections.\nThe optional second parameter sets a value in the\n“Keep-Alive: timeout=”\nresponse header field.\nTwo parameters may differ.
\n\nThe\n“Keep-Alive: timeout=”\nheader field is recognized by Mozilla and Konqueror.\nMSIE closes keep-alive connections by itself in about 60 seconds.
\n" @@ -992,9 +1180,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`number`* *`size`*" ], + "syntax_html": [ + "number size
Sets the maximum number and size of\nbuffers used for reading large client request header.\nA request line cannot exceed the size of one buffer, or the\n414 (Request-URI Too Large)\nerror is returned to the client.\nA request header field cannot exceed the size of one buffer as well, or the\n400 (Bad Request)\nerror is returned to the client.\nBuffers are allocated only on demand.\nBy default, the buffer size is equal to 8K bytes.\nIf after the end of request processing a connection is transitioned\ninto the keep-alive state, these buffers are released.
If the directive is specified on the server level,\nthe value from the default server can be used.\nDetails are provided in the\n“Virtual server selection” section.
method … {...}
Limits allowed HTTP methods inside a location.\nThe method parameter can be one of the following:\nGET,\nHEAD,\nPOST,\nPUT,\nDELETE,\nMKCOL,\nCOPY,\nMOVE,\nOPTIONS,\nPROPFIND,\nPROPPATCH,\nLOCK,\nUNLOCK,\nor\nPATCH.\nAllowing the GET method makes the\nHEAD method also allowed.\nAccess to other methods can be limited using the\nngx_http_access_module,\nngx_http_auth_basic_module,\nand\nngx_http_auth_jwt_module\n(1.13.10)\nmodules directives:
limit_except GET {\n allow 192.168.1.0/32;\n deny all;\n}\nPlease note that this will limit access to all methods\nexcept GET and HEAD.
\n" @@ -1021,9 +1215,12 @@ "location", "if in location" ], - "syntax": [ + "syntax_md": [ "*`rate`*" ], + "syntax_html": [ + "rate
Limits the rate of response transmission to a client.\nThe rate is specified in bytes per second.\nThe zero value disables rate limiting.
The limit is set per a request, and so if a client simultaneously opens\ntwo connections, the overall rate will be twice as much\nas the specified limit.
\n\nParameter value can contain variables (1.17.0).\nIt may be useful in cases where rate should be limited\ndepending on a certain condition:
\n\nmap $slow $rate {\n 1 4k;\n 2 8k;\n}\n\nlimit_rate $rate;\nRate limit can also be set in the\n$limit_rate variable,\nhowever, since version 1.17.0, this method is not recommended:
server {\n\n if ($slow) {\n set $limit_rate 4k;\n }\n\n ...\n}\nRate limit can also be set in the\n“X-Accel-Limit-Rate” header field of a proxied server response.\nThis capability can be disabled using the\nproxy_ignore_headers,\nfastcgi_ignore_headers,\nuwsgi_ignore_headers,\nand\nscgi_ignore_headers\ndirectives.
size
Sets the initial amount after which the further transmission\nof a response to a client will be rate limited.\nParameter value can contain variables (1.17.0).
\n\nExample:
\n\nlocation /flv/ {\n flv;\n limit_rate_after 500k;\n limit_rate 50k;\n}\noff | on | always
Controls how nginx closes client connections.
\n\nThe default value “on” instructs nginx to\nwait for and\nprocess additional data from a client\nbefore fully closing a connection, but only\nif heuristics suggests that a client may be sending more data.
The value “always” will cause nginx to unconditionally\nwait for and process additional client data.
The value “off” tells nginx to never wait for\nmore data and close the connection immediately.\nThis behavior breaks the protocol and should not be used under normal\ncircumstances.
To control closing\nHTTP/2 connections,\nthe directive must be specified on the server level (1.19.1).
time
When lingering_close is in effect,\nthis directive specifies the maximum time during which nginx\nwill process (read and ignore) additional data coming from a client.\nAfter that, the connection will be closed, even if there will be\nmore data.
time
When lingering_close is in effect, this directive specifies\nthe maximum waiting time for more client data to arrive.\nIf data are not received during this time, the connection is closed.\nOtherwise, the data are read and ignored, and nginx starts waiting\nfor more data again.\nThe “wait-read-ignore” cycle is repeated, but no longer than specified by the\nlingering_time directive.
address[:port] [default_server] [ssl] [http2 | quic] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]]
port [default_server] [ssl] [http2 | quic] [proxy_protocol] [setfib=number] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]]
unix:path [default_server] [ssl] [http2 | quic] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [accept_filter=filter] [deferred] [bind] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]]
Sets the address and port for IP,\nor the path for a UNIX-domain socket on which\nthe server will accept requests.\nBoth address and port,\nor only address or only port can be specified.\nAn address may also be a hostname, for example:
listen 127.0.0.1:8000;\nlisten 127.0.0.1;\nlisten 8000;\nlisten *:8000;\nlisten localhost:8000;\nIPv6 addresses (0.7.36) are specified in square brackets:
\n\nlisten [::]:8000;\nlisten [::1];\nUNIX-domain sockets (0.8.21) are specified with the “unix:”\nprefix:
listen unix:/var/run/nginx.sock;\nIf only address is given, the port 80 is used.
If the directive is not present then either *:80 is used\nif nginx runs with the superuser privileges, or *:8000\notherwise.
The default_server parameter, if present,\nwill cause the server to become the default server for the specified\naddress:port pair.\nIf none of the directives have the default_server\nparameter then the first server with the\naddress:port pair will be\nthe default server for this pair.
\n\n\nIn versions prior to 0.8.21 this parameter is named simply\n
\ndefault.
The ssl parameter (0.7.14) allows specifying that all\nconnections accepted on this port should work in SSL mode.\nThis allows for a more compact configuration for the server that\nhandles both HTTP and HTTPS requests.
The http2 parameter (1.9.5) configures the port to accept\nHTTP/2 connections.\nNormally, for this to work the ssl parameter should be\nspecified as well, but nginx can also be configured to accept HTTP/2\nconnections without SSL.
\n\n\nThe parameter is deprecated,\nthe http2 directive\nshould be used instead.
\n
The quic parameter (1.25.0) configures the port to accept\nQUIC connections.
The proxy_protocol parameter (1.5.12)\nallows specifying that all connections accepted on this port should use the\nPROXY protocol.
\n\n\nThe PROXY protocol version 2 is supported since version 1.13.11.
\n
The listen directive\ncan have several additional parameters specific to socket-related system calls.\nThese parameters can be specified in any\nlisten directive, but only once for a given\naddress:port pair.
\n\n\nIn versions prior to 0.8.21, they could only be\nspecified in the
\nlistendirective together with the\ndefaultparameter.
setfib=number
this parameter (0.8.44) sets the associated routing table, FIB\n(the SO_SETFIB option) for the listening socket.\nThis currently works only on FreeBSD.
fastopen=number
enables\n“TCP Fast Open”\nfor the listening socket (1.5.8) and\nlimits\nthe maximum length for the queue of connections that have not yet completed\nthe three-way handshake.
\n\n\n\nDo not enable this feature unless the server can handle\nreceiving the\n same SYN packet with data more than once.
\n
backlog=number
sets the backlog parameter in the\nlisten() call that limits\nthe maximum length for the queue of pending connections.\nBy default,\nbacklog is set to -1 on FreeBSD, DragonFly BSD, and macOS,\nand to 511 on other platforms.
rcvbuf=size
sets the receive buffer size\n(the SO_RCVBUF option) for the listening socket.
sndbuf=size
sets the send buffer size\n(the SO_SNDBUF option) for the listening socket.
accept_filter=filter
sets the name of accept filter\n(the SO_ACCEPTFILTER option) for the listening socket\nthat filters incoming connections before passing them to\naccept().\nThis works only on FreeBSD and NetBSD 5.0+.\nPossible values are\ndataready\nand\nhttpready.
deferred
instructs to use a deferred accept()\n(the TCP_DEFER_ACCEPT socket option) on Linux.
bind
instructs to make a separate bind() call for a given\naddress:port pair.\nThis is useful because if there are several listen\ndirectives with the same port but different addresses, and one of the\nlisten directives listens on all addresses\nfor the given port (*:port), nginx\nwill bind() only to *:port.\nIt should be noted that the getsockname() system call will be\nmade in this case to determine the address that accepted the connection.\nIf the setfib,\nfastopen,\nbacklog, rcvbuf,\nsndbuf, accept_filter,\ndeferred, ipv6only,\nreuseport,\nor so_keepalive parameters\nare used then for a given\naddress:port pair\na separate bind() call will always be made.
ipv6only=on|off
this parameter (0.7.42) determines\n(via the IPV6_V6ONLY socket option)\nwhether an IPv6 socket listening on a wildcard address [::]\nwill accept only IPv6 connections or both IPv6 and IPv4 connections.\nThis parameter is turned on by default.\nIt can only be set once on start.
\n\nPrior to version 1.3.4,\nif this parameter was omitted then the operating system’s settings were\nin effect for the socket.
\n
reuseport
this parameter (1.9.1) instructs to create an individual listening socket\nfor each worker process\n(using the\nSO_REUSEPORT socket option on Linux 3.9+ and DragonFly BSD,\nor SO_REUSEPORT_LB on FreeBSD 12+), allowing a kernel\nto distribute incoming connections between worker processes.\nThis currently works only on Linux 3.9+, DragonFly BSD,\nand FreeBSD 12+ (1.15.1).
\n\nInappropriate use of this option may have its security\nimplications.
\n
so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]
this parameter (1.1.11) configures the “TCP keepalive” behavior\nfor the listening socket.\nIf this parameter is omitted then the operating system’s settings will be\nin effect for the socket.\nIf it is set to the value “on”, the\nSO_KEEPALIVE option is turned on for the socket.\nIf it is set to the value “off”, the\nSO_KEEPALIVE option is turned off for the socket.\nSome operating systems support setting of TCP keepalive parameters on\na per-socket basis using the TCP_KEEPIDLE,\nTCP_KEEPINTVL, and TCP_KEEPCNT socket options.\nOn such systems (currently, Linux 2.4+, NetBSD 5+, and\nFreeBSD 9.0-STABLE), they can be configured\nusing the keepidle, keepintvl, and\nkeepcnt parameters.\nOne or two parameters may be omitted, in which case the system default setting\nfor the corresponding socket option will be in effect.\nFor example,
so_keepalive=30m::10\nwill set the idle timeout (TCP_KEEPIDLE) to 30 minutes,\nleave the probe interval (TCP_KEEPINTVL) at its system default,\nand set the probes count (TCP_KEEPCNT) to 10 probes.
Example:
\n\nlisten 127.0.0.1 default_server accept_filter=dataready backlog=1024;\n[ = | ~ | ~* | ^~ ] uri {...}
@name {...}
Sets configuration depending on a request URI.
\n\nThe matching is performed against a normalized URI,\nafter decoding the text encoded in the “%XX” form,\nresolving references to relative path components “.”\nand “..”, and possible\ncompression of two or more\nadjacent slashes into a single slash.
A location can either be defined by a prefix string, or by a regular expression.\nRegular expressions are specified with the preceding\n“~*” modifier (for case-insensitive matching), or the\n“~” modifier (for case-sensitive matching).\nTo find location matching a given request, nginx first checks\nlocations defined using the prefix strings (prefix locations).\nAmong them, the location with the longest matching\nprefix is selected and remembered.\nThen regular expressions are checked, in the order of their appearance\nin the configuration file.\nThe search of regular expressions terminates on the first match,\nand the corresponding configuration is used.\nIf no match with a regular expression is found then the\nconfiguration of the prefix location remembered earlier is used.
location blocks can be nested, with some exceptions\nmentioned below.
For case-insensitive operating systems such as macOS and Cygwin,\nmatching with prefix strings ignores a case (0.7.7).\nHowever, comparison is limited to one-byte locales.
\n\nRegular expressions can contain captures (0.7.40) that can later\nbe used in other directives.
\n\nIf the longest matching prefix location has the “^~” modifier\nthen regular expressions are not checked.
Also, using the “=” modifier it is possible to define\nan exact match of URI and location.\nIf an exact match is found, the search terminates.\nFor example, if a “/” request happens frequently,\ndefining “location = /” will speed up the processing\nof these requests, as search terminates right after the first\ncomparison.\nSuch a location cannot obviously contain nested locations.
\n\n\nIn versions from 0.7.1 to 0.8.41, if a request matched the prefix\nlocation without the “
\n=” and “^~”\nmodifiers, the search also terminated and regular expressions were\nnot checked.
Let’s illustrate the above by an example:
\n\nlocation = / {\n [ configuration A ]\n}\n\nlocation / {\n [ configuration B ]\n}\n\nlocation /documents/ {\n [ configuration C ]\n}\n\nlocation ^~ /images/ {\n [ configuration D ]\n}\n\nlocation ~* \\.(gif|jpg|jpeg)$ {\n [ configuration E ]\n}\nThe “/” request will match configuration A,\nthe “/index.html” request will match configuration B,\nthe “/documents/document.html” request will match\nconfiguration C,\nthe “/images/1.gif” request will match configuration D, and\nthe “/documents/1.jpg” request will match configuration E.
The “@” prefix defines a named location.\nSuch a location is not used for a regular request processing, but instead\nused for request redirection.\nThey cannot be nested, and cannot contain nested locations.
If a location is defined by a prefix string that ends with the slash character,\nand requests are processed by one of\nproxy_pass,\nfastcgi_pass,\nuwsgi_pass,\nscgi_pass,\nmemcached_pass, or\ngrpc_pass,\nthen the special processing is performed.\nIn response to a request with URI equal to this string,\nbut without the trailing slash,\na permanent redirect with the code 301 will be returned to the requested URI\nwith the slash appended.\nIf this is not desired, an exact match of the URI and location could be\ndefined like this:
location /user/ {\n proxy_pass http://user.example.com;\n}\n\nlocation = /user {\n proxy_pass http://login.example.com;\n}\non | off
Enables or disables logging of errors about not found files into\nerror_log.
on | off
Enables or disables logging of subrequests into\naccess_log.
number
Limits the maximum allowed number of ranges in byte-range requests.\nRequests that exceed the limit are processed as if there were no\nbyte ranges specified.\nBy default, the number of ranges is not limited.\nThe zero value disables the byte-range support completely.
\n" @@ -1171,9 +1398,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables compression of two or more adjacent slashes\nin a URI into a single slash.
\n\nNote that compression is essential for the correct matching of prefix string\nand regular expression locations.\nWithout it, the “//scripts/one.php” request would not match
location /scripts/ {\n ...\n}\nand might be processed as a static file.\nSo it gets converted to “/scripts/one.php”.
Turning the compression off can become necessary if a URI\ncontains base64-encoded names, since base64 uses the “/”\ncharacter internally.\nHowever, for security considerations, it is better to avoid turning\nthe compression off.
If the directive is specified on the server level,\nthe value from the default server can be used.\nDetails are provided in the\n“Virtual server selection” section.
on | off
Enables or disables adding comments to responses for MSIE clients with status\ngreater than 400 to increase the response size to 512 bytes.
\n" @@ -1201,9 +1434,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables issuing refreshes instead of redirects for MSIE clients.
\n" @@ -1216,10 +1452,14 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`off`", "`max`=*`N`* [`inactive`=*`time`*]" ], + "syntax_html": [ + "off
max=N [inactive=time]
Configures a cache that can store:
\n\nopen_file_cache_errors\n> directive.The directive has the following parameters:
\n\nmax
sets the maximum number of elements in the cache;\non cache overflow the least recently used (LRU) elements are removed;
inactive
defines a time after which an element is removed from the cache\nif it has not been accessed during this time;\nby default, it is 60 seconds;
off
disables the cache.
Example:
\n\nopen_file_cache max=1000 inactive=20s;\nopen_file_cache_valid 30s;\nopen_file_cache_min_uses 2;\nopen_file_cache_errors on;\non | off
Enables or disables caching of file lookup errors by\nopen_file_cache.
number
Sets the minimum number of file accesses during\nthe period configured by the inactive parameter\nof the open_file_cache directive, required for a file\ndescriptor to remain open in the cache.
time
Sets a time after which\nopen_file_cache\nelements should be validated.
number size
Sets the number and size of the\nbuffers used for reading a response from a disk.
\n\n" @@ -1292,9 +1544,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "Prior to version 1.9.5, the default value was 1 32k.
\n
on | off
Enables or disables specifying the port in\nabsolute redirects issued by nginx.
\n\nThe use of the primary server name in redirects is controlled by\nthe server_name_in_redirect directive.
size
If possible, the transmission of client data will be postponed until\nnginx has at least size bytes of data to send.\nThe zero value disables postponing data transmission.
size
Sets the amount of pre-reading for the kernel when working with file.
\n\nOn Linux, the\nposix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)\nsystem call is used, and so the size parameter is ignored.
On FreeBSD, the\nfcntl(O_READAHEAD,\nsize)\nsystem call, supported since FreeBSD 9.0-CURRENT, is used.\nFreeBSD 7 has to be\npatched.
on | off
Enables or disables doing several redirects using the\nerror_page\ndirective.\nThe number of such redirects is limited.
size
Allows accurate tuning of per-request memory allocations.\nThis directive has minimal impact on performance\nand should not generally be used.
\n" @@ -1366,9 +1633,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables resetting timed out connections\nand connections\nclosed\nwith the non-standard code 444 (1.15.2).\nThe reset is performed as follows.\nBefore closing a socket, the\nSO_LINGER\noption is set on it with a timeout value of 0.\nWhen the socket is closed, TCP RST is sent to the client, and all memory\noccupied by this socket is released.\nThis helps avoid keeping an already closed socket with filled buffers\nin a FIN_WAIT1 state for a long time.
It should be noted that timed out keep-alive connections are\nclosed normally.
\n" @@ -1381,9 +1651,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`address`* ... [`valid`=*`time`*] [`ipv4`=`on`|`off`] [`ipv6`=`on`|`off`] [`status_zone`=*`zone`*]" ], + "syntax_html": [ + "address … [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone]
Configures name servers used to resolve names of upstream servers\ninto addresses, for example:
\n\nresolver 127.0.0.1 [::1]:5353;\nThe address can be specified as a domain name or IP address,\nwith an optional port (1.3.1, 1.2.2).\nIf port is not specified, the port 53 is used.\nName servers are queried in a round-robin fashion.
\n\n\n\n\nBefore version 1.1.7, only a single name server could be configured.\nSpecifying name servers using IPv6 addresses is supported\nstarting from versions 1.3.1 and 1.2.2.
\n
By default, nginx will look up both IPv4 and IPv6 addresses while resolving.\nIf looking up of IPv4 or IPv6 addresses is not desired,\nthe ipv4=off (1.23.1) or\nthe ipv6=off parameter can be specified.
\n\n\nResolving of names into IPv6 addresses is supported\nstarting from version 1.5.8.
\n
By default, nginx caches answers using the TTL value of a response.\nAn optional valid parameter allows overriding it:
resolver 127.0.0.1 [::1]:5353 valid=30s;\n\n\n\nBefore version 1.1.9, tuning of caching time was not possible,\nand nginx always cached answers for the duration of 5 minutes.
\n\nTo prevent DNS spoofing, it is recommended\nconfiguring DNS servers in a properly secured trusted local network.
\n
The optional status_zone parameter (1.17.1)\nenables\ncollection\nof DNS server statistics of requests and responses\nin the specified zone.\nThe parameter is available as part of our\ncommercial subscription.
time
Sets a timeout for name resolution, for example:
\n\nresolver_timeout 5s;\npath
Sets the root directory for requests.\nFor example, with the following configuration
\n\nlocation /i/ {\n root /data/w3;\n}\nThe /data/w3/i/top.gif file will be sent in response to\nthe “/i/top.gif” request.
The path value can contain variables,\nexcept $document_root and $realpath_root.
A path to the file is constructed by merely adding a URI to the value\nof the root directive.\nIf a URI has to be modified, the\nalias directive should be used.
all | any
Allows access if all (all) or at least one\n(any) of the\nngx_http_access_module,\nngx_http_auth_basic_module,\nngx_http_auth_request_module,\nor\nngx_http_auth_jwt_module\nmodules allow access.
Example:
\n\nlocation / {\n satisfy any;\n\n allow 192.168.1.0/32;\n deny all;\n\n auth_basic "closed site";\n auth_basic_user_file conf/htpasswd;\n}\nsize
If the directive is set to a non-zero value, nginx will try to minimize\nthe number of send operations on client sockets by using either\nNOTE_LOWAT flag of the\nkqueue method\nor the SO_SNDLOWAT socket option.\nIn both cases the specified size is used.
This directive is ignored on Linux, Solaris, and Windows.
\n" @@ -1457,9 +1742,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Sets a timeout for transmitting a response to the client.\nThe timeout is set only between two successive write operations,\nnot for the transmission of the whole response.\nIf the client does not receive anything within this time,\nthe connection is closed.
\n" @@ -1473,9 +1761,12 @@ "location", "if in location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables the use of\nsendfile().
Starting from nginx 0.8.12 and FreeBSD 5.2.1,\naio can be used to pre-load data\nfor sendfile():
location /video/ {\n sendfile on;\n tcp_nopush on;\n aio on;\n}\nIn this configuration, sendfile() is called with\nthe SF_NODISKIO flag which causes it not to block on disk I/O,\nbut, instead, report back that the data are not in memory.\nnginx then initiates an asynchronous data load by reading one byte.\nOn the first read, the FreeBSD kernel loads the first 128K bytes\nof a file into memory, although next reads will only load data in 16K chunks.\nThis can be changed using the\nread_ahead directive.
\n\n" @@ -1488,9 +1779,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "Before version 1.7.11, pre-loading could be enabled with\n
\naio sendfile;.
size
Limits the amount of data that can be\ntransferred in a single sendfile() call.\nWithout the limit, one fast connection may seize the worker process entirely.
\n\n" @@ -1501,9 +1795,12 @@ "contexts": [ "http" ], - "syntax": [ + "syntax_md": [ " `{...}`" ], + "syntax_html": [ + "Prior to version 1.21.4, by default there was no limit.
\n
{...}
Sets configuration for a virtual server.\nThere is no clear separation between IP-based (based on the IP address)\nand name-based (based on the “Host” request header field)\nvirtual servers.\nInstead, the listen directives describe all\naddresses and ports that should accept connections for the server, and the\nserver_name directive lists all server names.\nExample configurations are provided in the\n“How nginx processes a request” document.
name …
Sets names of a virtual server, for example:
\n\nserver {\n server_name example.com www.example.com;\n}\nThe first name becomes the primary server name.
\n\nServer names can include an asterisk (“*”)\nreplacing the first or last part of a name:
server {\n server_name example.com *.example.com www.example.*;\n}\nSuch names are called wildcard names.
\n\nThe first two of the names mentioned above can be combined in one:
\n\nserver {\n server_name .example.com;\n}\nIt is also possible to use regular expressions in server names,\npreceding the name with a tilde (“~”):
server {\n server_name www.example.com ~^www\\d+\\.example\\.com$;\n}\nRegular expressions can contain captures (0.7.40) that can later\nbe used in other directives:
\n\nserver {\n server_name ~^(www\\.)?(.+)$;\n\n location / {\n root /sites/$2;\n }\n}\n\nserver {\n server_name _;\n\n location / {\n root /sites/default;\n }\n}\nNamed captures in regular expressions create variables (0.8.25)\nthat can later be used in other directives:
\n\nserver {\n server_name ~^(www\\.)?(?<domain>.+)$;\n\n location / {\n root /sites/$domain;\n }\n}\n\nserver {\n server_name _;\n\n location / {\n root /sites/default;\n }\n}\nIf the directive’s parameter is set to “$hostname” (0.9.4), the\nmachine’s hostname is inserted.
It is also possible to specify an empty server name (0.7.11):
\n\nserver {\n server_name www.example.com "";\n}\nIt allows this server to process requests without the “Host”\nheader field — instead of the default server — for the given address:port pair.\nThis is the default setting.
\n\n\n\n\nBefore 0.8.48, the machine’s hostname was used by default.
\n
During searching for a virtual server by name,\nif the name matches more than one of the specified variants,\n(e.g. both a wildcard name and regular expression match), the first matching\nvariant will be chosen, in the following order of priority:
\n\n*.example.com”mail.*”Detailed description of server names is provided in a separate\nServer names document.
\n" @@ -1529,9 +1829,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables the use of the primary server name, specified by the\nserver_name directive,\nin absolute redirects issued by nginx.\nWhen the use of the primary server name is disabled, the name from the\n“Host” request header field is used.\nIf this field is not present, the IP address of the server is used.
The use of a port in redirects is controlled by\nthe port_in_redirect directive.
size
Sets the bucket size for the server names hash tables.\nThe default value depends on the size of the processor’s cache line.\nThe details of setting up hash tables are provided in a separate\ndocument.
\n" @@ -1555,9 +1861,12 @@ "contexts": [ "http" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
Sets the maximum size of the server names hash tables.\nThe details of setting up hash tables are provided in a separate\ndocument.
on | off | build | string
Enables or disables emitting nginx version on error pages and in the\n“Server” response header field.
\n\nThe build parameter (1.11.10) enables emitting\na build name\nalong with nginx version.
Additionally, as part of our\ncommercial subscription,\nstarting from version 1.9.13\nthe signature on error pages and\nthe “Server” response header field value\ncan be set explicitly using the string with variables.\nAn empty string disables the emission of the “Server” field.
size
Sets the size of the buffer used for\nstoring the response body of a subrequest.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.\nIt can be made smaller, however.
The directive is applicable only for subrequests\nwith response bodies saved into memory.\nFor example, such subrequests are created by\nSSI.
\n" @@ -1600,9 +1915,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables the use of the TCP_NODELAY option.\nThe option is enabled when a connection is transitioned into the\nkeep-alive state.\nAdditionally, it is enabled on SSL connections,\nfor unbuffered proxying,\nand for WebSocket proxying.
on | off
Enables or disables the use of\nthe TCP_NOPUSH socket option on FreeBSD\nor the TCP_CORK socket option on Linux.\nThe options are enabled only when sendfile is used.\nEnabling the option allows
file … uri
file … =code
Checks the existence of files in the specified order and uses\nthe first found file for request processing; the processing\nis performed in the current context.\nThe path to a file is constructed from the\nfile parameter\naccording to the\nroot and alias directives.\nIt is possible to check directory’s existence by specifying\na slash at the end of a name, e.g. “$uri/”.\nIf none of the files were found, an internal redirect to the\nuri specified in the last parameter is made.\nFor example:
location /images/ {\n try_files $uri /images/default.gif;\n}\n\nlocation = /images/default.gif {\n expires 30s;\n}\nThe last parameter can also point to a named location,\nas shown in examples below.\nStarting from version 0.7.51, the last parameter can also be a\ncode:
location / {\n try_files $uri $uri/index.html $uri.html =404;\n}\nExample in proxying Mongrel:
\n\nlocation / {\n try_files /system/maintenance.html\n $uri $uri/index.html $uri.html\n @mongrel;\n}\n\nlocation @mongrel {\n proxy_pass http://mongrel;\n}\nExample for Drupal/FastCGI:
\n\nlocation / {\n try_files $uri $uri/ @drupal;\n}\n\nlocation ~ \\.php$ {\n try_files $uri @drupal;\n\n fastcgi_pass ...;\n\n fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;\n fastcgi_param SCRIPT_NAME $fastcgi_script_name;\n fastcgi_param QUERY_STRING $args;\n\n ... other fastcgi_param's\n}\n\nlocation @drupal {\n fastcgi_pass ...;\n\n fastcgi_param SCRIPT_FILENAME /path/to/index.php;\n fastcgi_param SCRIPT_NAME /index.php;\n fastcgi_param QUERY_STRING q=$uri&$args;\n\n ... other fastcgi_param's\n}\nIn the following example,
\n\nlocation / {\n try_files $uri $uri/ @drupal;\n}\nthe try_files directive is equivalent to
location / {\n error_page 404 = @drupal;\n log_not_found off;\n}\nAnd here,
\n\nlocation ~ \\.php$ {\n try_files $uri @drupal;\n\n fastcgi_pass ...;\n\n fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;\n\n ...\n}\ntry_files checks the existence of the PHP file\nbefore passing the request to the FastCGI server.
Example for Wordpress and Joomla:
\n\nlocation / {\n try_files $uri $uri/ @wordpress;\n}\n\nlocation ~ \\.php$ {\n try_files $uri @wordpress;\n\n fastcgi_pass ...;\n\n fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;\n ... other fastcgi_param's\n}\n\nlocation @wordpress {\n fastcgi_pass ...;\n\n fastcgi_param SCRIPT_FILENAME /path/to/index.php;\n ... other fastcgi_param's\n}\n{...}
Maps file name extensions to MIME types of responses.\nExtensions are case-insensitive.\nSeveral extensions can be mapped to one type, for example:
\n\ntypes {\n application/octet-stream bin exe dll;\n application/octet-stream deb;\n application/octet-stream dmg;\n}\nA sufficiently full mapping table is distributed with nginx in the\nconf/mime.types file.
To make a particular location emit the\n“application/octet-stream”\nMIME type for all requests, the following configuration can be used:
location /download/ {\n types { }\n default_type application/octet-stream;\n}\nsize
Sets the bucket size for the types hash tables.\nThe details of setting up hash tables are provided in a separate\ndocument.
\n\n\n\n" @@ -1675,9 +2006,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "Prior to version 1.5.13,\nthe default value depended on the size of the processor’s cache line.
\n
size
Sets the maximum size of the types hash tables.\nThe details of setting up hash tables are provided in a separate\ndocument.
on | off
Enables or disables the use of underscores in client request header fields.\nWhen the use of underscores is disabled, request header fields whose names\ncontain underscores are\nmarked as invalid and become subject to the\nignore_invalid_headers directive.
If the directive is specified on the server level,\nthe value from the default server can be used.\nDetails are provided in the\n“Virtual server selection” section.
size
Sets the bucket size for the variables hash table.\nThe details of setting up hash tables are provided in a separate\ndocument.
\n" @@ -1715,9 +2055,12 @@ "contexts": [ "http" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
Sets the maximum size of the variables hash table.\nThe details of setting up hash tables are provided in a separate\ndocument.
\n\n" @@ -1736,9 +2079,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "Prior to version 1.5.13, the default value was 512.
\n
on | off
The WebDAV specification only allows creating files in already\nexisting directories.\nThis directive allows creating all needed intermediate directories.
\n" @@ -1751,9 +2097,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`users`*:*`permissions`* ..." ], + "syntax_html": [ + "users:permissions …
Sets access permissions for newly created files and directories, e.g.:
\n\ndav_access user:rw group:rw all:r;\nIf any group or all access permissions\nare specified then user permissions may be omitted:
dav_access group:rw all:r;\noff | method …
Allows the specified HTTP and WebDAV methods.\nThe parameter off denies all methods processed\nby this module.\nThe following methods are supported:\nPUT, DELETE, MKCOL,\nCOPY, and MOVE.
A file uploaded with the PUT method is first written to a temporary file,\nand then the file is renamed.\nStarting from version 0.8.9, temporary files and the persistent store\ncan be put on different file systems.\nHowever, be aware that in this case a file is copied\nacross two file systems instead of the cheap renaming operation.\nIt is thus recommended that for any given location both saved files and a\ndirectory holding temporary files, set by the\nclient_body_temp_path\ndirective, are put on the same file system.
When creating a file with the PUT method, it is possible to specify\nthe modification date by passing it in the “Date”\nheader field.
\n" @@ -1781,9 +2133,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
Allows the DELETE method to remove files provided that\nthe number of elements in a request path is not less than the specified\nnumber.\nFor example, the directive
\n\nmin_delete_depth 4;\nallows removing files on requests
\n\n/users/00/00/name\n/users/00/00/name/pic.jpg\n/users/00/00/page.html\nand denies the removal of
\n\n/users/00/00\nsize
Sets the size of the buffer used for\nreading the .f4x index file.
address [transparent] | off
Makes outgoing connections to a FastCGI server originate\nfrom the specified local IP address with an optional port (1.11.2).\nParameter value can contain variables (1.3.12).\nThe special value off (1.3.12) cancels the effect\nof the fastcgi_bind directive\ninherited from the previous configuration level, which allows the\nsystem to auto-assign the local IP address and port.
The transparent parameter (1.11.0) allows\noutgoing connections to a FastCGI server originate\nfrom a non-local IP address,\nfor example, from a real IP address of a client:
fastcgi_bind $remote_addr transparent;\nIn order for this parameter to work,\nit is usually necessary to run nginx worker processes with the\nsuperuser privileges.\nOn Linux it is not required (1.13.8) as if\nthe transparent parameter is specified, worker processes\ninherit the CAP_NET_RAW capability from the master process.\nIt is also necessary to configure kernel routing table\nto intercept network traffic from the FastCGI server.
size
Sets the size of the buffer used for reading the first part\nof the response received from the FastCGI server.\nThis part usually contains a small response header.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.\nIt can be made smaller, however.
on | off
Enables or disables buffering of responses from the FastCGI server.
\n\nWhen buffering is enabled, nginx receives a response from the FastCGI server\nas soon as possible, saving it into the buffers set by the\nfastcgi_buffer_size and fastcgi_buffers directives.\nIf the whole response does not fit into memory, a part of it can be saved\nto a temporary file on the disk.\nWriting to temporary files is controlled by the\nfastcgi_max_temp_file_size and\nfastcgi_temp_file_write_size directives.
When buffering is disabled, the response is passed to a client synchronously,\nimmediately as it is received.\nnginx will not try to read the whole response from the FastCGI server.\nThe maximum size of the data that nginx can receive from the server\nat a time is set by the fastcgi_buffer_size directive.
Buffering can also be enabled or disabled by passing\n“yes” or “no” in the\n“X-Accel-Buffering” response header field.\nThis capability can be disabled using the\nfastcgi_ignore_headers directive.
number size
Sets the number and size of the\nbuffers used for reading a response from the FastCGI server,\nfor a single connection.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.
size
When buffering of responses from the FastCGI\nserver is enabled, limits the total size of buffers that\ncan be busy sending a response to the client while the response is not\nyet fully read.\nIn the meantime, the rest of the buffers can be used for reading the response\nand, if needed, buffering part of the response to a temporary file.\nBy default, size is limited by the size of two buffers set by the\nfastcgi_buffer_size and fastcgi_buffers directives.
zone | off
Defines a shared memory zone used for caching.\nThe same zone can be used in several places.\nParameter value can contain variables (1.7.9).\nThe off parameter disables caching inherited\nfrom the previous configuration level.
on | off
Allows starting a background subrequest\nto update an expired cache item,\nwhile a stale cached response is returned to the client.\nNote that it is necessary to\nallow\nthe usage of a stale cached response when it is being updated.
\n" @@ -1960,9 +2345,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`string`* ..." ], + "syntax_html": [ + "string …
Defines conditions under which the response will not be taken from a cache.\nIf at least one value of the string parameters is not empty and is not\nequal to “0” then the response will not be taken from the cache:
\n\nfastcgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;\nfastcgi_cache_bypass $http_pragma $http_authorization;\nCan be used along with the fastcgi_no_cache directive.
string
Defines a key for caching, for example
\n\nfastcgi_cache_key localhost:9000$request_uri;\non | off
When enabled, only one request at a time will be allowed to populate\na new cache element identified according to the fastcgi_cache_key\ndirective by passing a request to a FastCGI server.\nOther requests of the same cache element will either wait\nfor a response to appear in the cache or the cache lock for\nthis element to be released, up to the time set by the\nfastcgi_cache_lock_timeout directive.
time
If the last request passed to the FastCGI server\nfor populating a new cache element\nhas not completed for the specified time,\none more request may be passed to the FastCGI server.
time
Sets a timeout for fastcgi_cache_lock.\nWhen the time expires,\nthe request will be passed to the FastCGI server,\nhowever, the response will not be cached.
\n\n" @@ -2035,9 +2435,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "Before 1.7.8, the response could be cached.
\n
number
Sets an offset in bytes for byte-range requests.\nIf the range is beyond the offset,\nthe range request will be passed to the FastCGI server\nand the response will not be cached.
\n" @@ -2050,9 +2453,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`GET` | `HEAD` | `POST` ..." ], + "syntax_html": [ + "GET | HEAD | POST …
If the client request method is listed in this directive then\nthe response will be cached.\n“GET” and “HEAD” methods are always\nadded to the list, though it is recommended to specify them explicitly.\nSee also the fastcgi_no_cache directive.
number
Sets the number of requests after which the response\nwill be cached.
path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [min_free=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time]
Sets the path and other parameters of a cache.\nCache data are stored in files.\nBoth the key and file name in a cache are a result of\napplying the MD5 function to the proxied URL.
\n\nThe levels parameter defines hierarchy levels of a cache:\nfrom 1 to 3, each level accepts values 1 or 2.\nFor example, in the following configuration
fastcgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;\nfile names in a cache will look like this:
\n\n/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c\nA cached response is first written to a temporary file,\nand then the file is renamed.\nStarting from version 0.8.9, temporary files and the cache can be put on\ndifferent file systems.\nHowever, be aware that in this case a file is copied\nacross two file systems instead of the cheap renaming operation.\nIt is thus recommended that for any given location both cache and a directory\nholding temporary files\nare put on the same file system.\nA directory for temporary files is set based on\nthe use_temp_path parameter (1.7.10).\nIf this parameter is omitted or set to the value on,\nthe directory set by the fastcgi_temp_path directive\nfor the given location will be used.\nIf the value is set to off,\ntemporary files will be put directly in the cache directory.
In addition, all active keys and information about data are stored\nin a shared memory zone, whose name and size\nare configured by the keys_zone parameter.\nOne megabyte zone can store about 8 thousand keys.
\n\n\nAs part of\ncommercial subscription,\nthe shared memory zone also stores extended\ncache information,\nthus, it is required to specify a larger zone size for the same number of keys.\nFor example,\none megabyte zone can store about 4 thousand keys.
\n
Cached data that are not accessed during the time specified by the\ninactive parameter get removed from the cache\nregardless of their freshness.\nBy default, inactive is set to 10 minutes.
The special “cache manager” process monitors the maximum cache size set\nby the max_size parameter,\nand the minimum amount of free space set\nby the min_free (1.19.1) parameter\non the file system with cache.\nWhen the size is exceeded or there is not enough free space,\nit removes the least recently used data.\nThe data is removed in iterations configured by\nmanager_files,\nmanager_threshold, and\nmanager_sleep parameters (1.11.5).\nDuring one iteration no more than manager_files items\nare deleted (by default, 100).\nThe duration of one iteration is limited by the\nmanager_threshold parameter (by default, 200 milliseconds).\nBetween iterations, a pause configured by the manager_sleep\nparameter (by default, 50 milliseconds) is made.
A minute after the start the special “cache loader” process is activated.\nIt loads information about previously cached data stored on file system\ninto a cache zone.\nThe loading is also done in iterations.\nDuring one iteration no more than loader_files items\nare loaded (by default, 100).\nBesides, the duration of one iteration is limited by the\nloader_threshold parameter (by default, 200 milliseconds).\nBetween iterations, a pause configured by the loader_sleep\nparameter (by default, 50 milliseconds) is made.
Additionally,\nthe following parameters are available as part of our\ncommercial subscription:
\n\npurger=on|off
Instructs whether cache entries that match a\nwildcard key\nwill be removed from the disk by the cache purger (1.7.12).\nSetting the parameter to on\n(default is off)\nwill activate the “cache purger” process that\npermanently iterates through all cache entries\nand deletes the entries that match the wildcard key.
purger_files=number
Sets the number of items that will be scanned during one iteration (1.7.12).\nBy default, purger_files is set to 10.
purger_threshold=number
Sets the duration of one iteration (1.7.12).\nBy default, purger_threshold is set to 50 milliseconds.
purger_sleep=number
Sets a pause between iterations (1.7.12).\nBy default, purger_sleep is set to 50 milliseconds.
\n\n" @@ -2093,9 +2505,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "string ..." ], + "syntax_html": [ + "In versions 1.7.3, 1.7.7, and 1.11.10 cache header format has been changed.\nPreviously cached responses will be considered invalid\nafter upgrading to a newer nginx version.
\n
string …
\n" + ], "isBlock": false, "description_md": "Defines conditions under which the request will be considered a cache\npurge request.\nIf at least one value of the string parameters is not empty and is not equal\nto “0” then the cache entry with a corresponding\n[cache key](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_cache_key) is removed.\nThe result of successful operation is indicated by returning\nthe 204 (No Content) response.\n\nIf the [cache key](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_cache_key) of a purge request ends\nwith an asterisk (“`*`”), all cache entries matching the\nwildcard key will be removed from the cache.\nHowever, these entries will remain on the disk until they are deleted\nfor either [inactivity](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_cache_path),\nor processed by the [cache purger](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#purger) (1.7.12),\nor a client attempts to access them.\n\nExample configuration:\n```\nfastcgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;\n\nmap $request_method $purge_method {\n PURGE 1;\n default 0;\n}\n\nserver {\n ...\n location / {\n fastcgi_pass backend;\n fastcgi_cache cache_zone;\n fastcgi_cache_key $uri;\n fastcgi_cache_purge $purge_method;\n }\n}\n```\n> This functionality is available as part of our\n> [commercial subscription](https://nginx.com/products/).", "description_html": "Defines conditions under which the request will be considered a cache\npurge request.\nIf at least one value of the string parameters is not empty and is not equal\nto “0” then the cache entry with a corresponding\ncache key is removed.\nThe result of successful operation is indicated by returning\nthe 204 (No Content) response.
\n\nIf the cache key of a purge request ends\nwith an asterisk (“*”), all cache entries matching the\nwildcard key will be removed from the cache.\nHowever, these entries will remain on the disk until they are deleted\nfor either inactivity,\nor processed by the cache purger (1.7.12),\nor a client attempts to access them.
Example configuration:
\n\nfastcgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;\n\nmap $request_method $purge_method {\n PURGE 1;\n default 0;\n}\n\nserver {\n ...\n location / {\n fastcgi_pass backend;\n fastcgi_cache cache_zone;\n fastcgi_cache_key $uri;\n fastcgi_cache_purge $purge_method;\n }\n}\n\n\n" @@ -2108,9 +2523,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "This functionality is available as part of our\ncommercial subscription.
\n
on | off
Enables revalidation of expired cache items using conditional requests with\nthe “If-Modified-Since” and “If-None-Match”\nheader fields.
\n" @@ -2123,9 +2541,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`error` | `timeout` | `invalid_header` | `updating` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `off` ..." ], + "syntax_html": [ + "error | timeout | invalid_header | updating | http_500 | http_503 | http_403 | http_404 | http_429 | off …
Determines in which cases a stale cached response can be used\nwhen an error occurs during communication with the FastCGI server.\nThe directive’s parameters match the parameters of the\nfastcgi_next_upstream directive.
The error parameter also permits\nusing a stale cached response if a FastCGI server to process a request\ncannot be selected.
Additionally, the updating parameter permits\nusing a stale cached response if it is currently being updated.\nThis allows minimizing the number of accesses to FastCGI servers\nwhen updating cached data.
Using a stale cached response\ncan also be enabled directly in the response header\nfor a specified number of seconds after the response became stale (1.11.10).\nThis has lower priority than using the directive parameters.
\n\nTo minimize the number of accesses to FastCGI servers when\npopulating a new cache element, the fastcgi_cache_lock\ndirective can be used.
[code …] time
Sets caching time for different response codes.\nFor example, the following directives
\n\nfastcgi_cache_valid 200 302 10m;\nfastcgi_cache_valid 404 1m;\nset 10 minutes of caching for responses with codes 200 and 302\nand 1 minute for responses with code 404.
\n\nIf only caching time is specified
fastcgi_cache_valid 5m;\nthen only 200, 301, and 302 responses are cached.
\n\nIn addition, the any parameter can be specified\nto cache any responses:
fastcgi_cache_valid 200 302 10m;\nfastcgi_cache_valid 301 1h;\nfastcgi_cache_valid any 1m;\nParameters of caching can also be set directly\nin the response header.\nThis has higher priority than setting of caching time using the directive.
\n\n@ prefix, it sets an absolute\ntime in seconds since Epoch, up to which the response may be cached.*”, such a\nresponse will not be cached (1.7.7).\nIf the header includes the “Vary” field\nwith another value, such a response will be cached\ntaking into account the corresponding request header fields (1.7.7).Processing of one or more of these response header fields can be disabled\nusing the fastcgi_ignore_headers directive.
string
Sets a string to search for in the error stream of a response\nreceived from a FastCGI server.\nIf the string is found then it is considered that the FastCGI\nserver has returned an invalid response.\nThis allows handling application errors in nginx, for example:
location /php/ {\n fastcgi_pass backend:9000;\n ...\n fastcgi_catch_stderr "PHP Fatal error";\n fastcgi_next_upstream error timeout invalid_header;\n}\ntime
Defines a timeout for establishing a connection with a FastCGI server.\nIt should be noted that this timeout cannot usually exceed 75 seconds.
\n" @@ -2183,9 +2613,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables byte-range support\nfor both cached and uncached responses from the FastCGI server\nregardless of the “Accept-Ranges” field in these responses.
\n" @@ -2198,9 +2631,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`field`*" ], + "syntax_html": [ + "field
By default,\nnginx does not pass the header fields “Status” and\n“X-Accel-…” from the response of a FastCGI\nserver to a client.\nThe fastcgi_hide_header directive sets additional fields\nthat will not be passed.\nIf, on the contrary, the passing of fields needs to be permitted,\nthe fastcgi_pass_header directive can be used.
on | off
Determines whether the connection with a FastCGI server should be\nclosed when a client closes the connection without waiting\nfor a response.
\n" @@ -2228,9 +2667,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`field`* ..." ], + "syntax_html": [ + "field …
Disables processing of certain response header fields from the FastCGI server.\nThe following fields can be ignored: “X-Accel-Redirect”,\n“X-Accel-Expires”, “X-Accel-Limit-Rate” (1.1.6),\n“X-Accel-Buffering” (1.1.6),\n“X-Accel-Charset” (1.1.6), “Expires”,\n“Cache-Control”, “Set-Cookie” (0.8.44),\nand “Vary” (1.7.7).
\n\nIf not disabled, processing of these header fields has the following\neffect:
\n\ncharset\nof a response.name
Sets a file name that will be appended after a URI that ends with\na slash, in the value of the $fastcgi_script_name variable.\nFor example, with these settings
fastcgi_index index.php;\nfastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;\nand the “/page.php” request,\nthe SCRIPT_FILENAME parameter will be equal to\n“/home/www/scripts/php/page.php”,\nand with the “/” request it will be equal to\n“/home/www/scripts/php/index.php”.
on | off
Determines whether FastCGI server responses with codes greater than or equal\nto 300 should be passed to a client\nor be intercepted and redirected to nginx for processing\nwith the error_page directive.
on | off
By default, a FastCGI server will close a connection right after\nsending the response.\nHowever, when this directive is set to the value on,\nnginx will instruct a FastCGI server to keep connections open.\nThis is necessary, in particular, for\nkeepalive\nconnections to FastCGI servers to function.
rate
Limits the speed of reading the response from the FastCGI server.\nThe rate is specified in bytes per second.\nThe zero value disables rate limiting.\nThe limit is set per a request, and so if nginx simultaneously opens\ntwo connections to the FastCFI server,\nthe overall rate will be twice as much as the specified limit.\nThe limitation works only if\nbuffering of responses from the FastCGI\nserver is enabled.
size
When buffering of responses from the FastCGI\nserver is enabled, and the whole response does not fit into the buffers\nset by the fastcgi_buffer_size and fastcgi_buffers\ndirectives, a part of the response can be saved to a temporary file.\nThis directive sets the maximum size of the temporary file.\nThe size of data written to the temporary file at a time is set\nby the fastcgi_temp_file_write_size directive.
The zero value disables buffering of responses to temporary files.
\n\n\n\n" @@ -2318,9 +2775,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`error` | `timeout` | `invalid_header` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `non_idempotent` | `off` ..." ], + "syntax_html": [ + "This restriction does not apply to responses\nthat will be cached\nor stored on disk.
\n
error | timeout | invalid_header | http_500 | http_503 | http_403 | http_404 | http_429 | non_idempotent | off …
Specifies in which cases a request should be passed to the next server:
\n\nerror
an error occurred while establishing a connection with the\nserver, passing a request to it, or reading the response header;
timeout
a timeout has occurred while establishing a connection with the\nserver, passing a request to it, or reading the response header;
invalid_header
a server returned an empty or invalid response;
http_500
a server returned a response with the code 500;
http_503
a server returned a response with the code 503;
http_403
a server returned a response with the code 403;
http_404
a server returned a response with the code 404;
http_429
a server returned a response with the code 429 (1.11.13);
non_idempotent
normally, requests with a\nnon-idempotent\nmethod\n(POST, LOCK, PATCH)\nare not passed to the next server\nif a request has been sent to an upstream server (1.9.13);\nenabling this option explicitly allows retrying such requests;
off
disables passing a request to the next server.
One should bear in mind that passing a request to the next server is\nonly possible if nothing has been sent to a client yet.\nThat is, if an error or timeout occurs in the middle of the\ntransferring of a response, fixing this is impossible.
\n\nThe directive also defines what is considered an\nunsuccessful attempt of communication with a server.\nThe cases of error, timeout and\ninvalid_header are always considered unsuccessful attempts,\neven if they are not specified in the directive.\nThe cases of http_500, http_503,\nand http_429 are\nconsidered unsuccessful attempts only if they are specified in the directive.\nThe cases of http_403 and http_404\nare never considered unsuccessful attempts.
Passing a request to the next server can be limited by\nthe number of tries\nand by time.
\n" @@ -2333,9 +2793,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Limits the time during which a request can be passed to the\nnext server.\nThe 0 value turns off this limitation.
number
Limits the number of possible tries for passing a request to the\nnext server.\nThe 0 value turns off this limitation.
string …
Defines conditions under which the response will not be saved to a cache.\nIf at least one value of the string parameters is not empty and is not\nequal to “0” then the response will not be saved:
\n\nfastcgi_no_cache $cookie_nocache $arg_nocache$arg_comment;\nfastcgi_no_cache $http_pragma $http_authorization;\nCan be used along with the fastcgi_cache_bypass directive.
parameter value [if_not_empty]
Sets a parameter that should be passed to the FastCGI server.\nThe value can contain text, variables, and their combination.\nThese directives are inherited from the previous configuration level\nif and only if there are no fastcgi_param directives\ndefined on the current level.
The following example shows the minimum required settings for PHP:
\n\nfastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;\nfastcgi_param QUERY_STRING $query_string;\nThe SCRIPT_FILENAME parameter is used in PHP for\ndetermining the script name, and the QUERY_STRING\nparameter is used to pass request parameters.
For scripts that process POST requests, the\nfollowing three parameters are also required:
fastcgi_param REQUEST_METHOD $request_method;\nfastcgi_param CONTENT_TYPE $content_type;\nfastcgi_param CONTENT_LENGTH $content_length;\nIf PHP was built with the --enable-force-cgi-redirect\nconfiguration parameter, the REDIRECT_STATUS parameter\nshould also be passed with the value “200”:
fastcgi_param REDIRECT_STATUS 200;\nIf the directive is specified with if_not_empty (1.1.11) then\nsuch a parameter will be passed to the server only if its value is not empty:
fastcgi_param HTTPS $https if_not_empty;\naddress
Sets the address of a FastCGI server.\nThe address can be specified as a domain name or IP address,\nand a port:
\n\nfastcgi_pass localhost:9000;\nor as a UNIX-domain socket path:
\n\nfastcgi_pass unix:/tmp/fastcgi.socket;\nIf a domain name resolves to several addresses, all of them will be\nused in a round-robin fashion.\nIn addition, an address can be specified as a\nserver group.
\n\nParameter value can contain variables.\nIn this case, if an address is specified as a domain name,\nthe name is searched among the described\nserver groups,\nand, if not found, is determined using a\nresolver.
field
Permits passing otherwise disabled header\nfields from a FastCGI server to a client.
\n" @@ -2422,9 +2900,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Indicates whether the original request body is passed\nto the FastCGI server.\nSee also the fastcgi_pass_request_headers directive.
on | off
Indicates whether the header fields of the original request are passed\nto the FastCGI server.\nSee also the fastcgi_pass_request_body directive.
time
Defines a timeout for reading a response from the FastCGI server.\nThe timeout is set only between two successive read operations,\nnot for the transmission of the whole response.\nIf the FastCGI server does not transmit anything within this time,\nthe connection is closed.
\n" @@ -2467,9 +2954,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables buffering of a client request body.
\n\nWhen buffering is enabled, the entire request body is\nread\nfrom the client before sending the request to a FastCGI server.
\n\nWhen buffering is disabled, the request body is sent to the FastCGI server\nimmediately as it is received.\nIn this case, the request cannot be passed to the\nnext server\nif nginx already started sending the request body.
\n" @@ -2482,9 +2972,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
If the directive is set to a non-zero value, nginx will try to\nminimize the number\nof send operations on outgoing connections to a FastCGI server by using either\nNOTE_LOWAT flag of the\nkqueue method,\nor the SO_SNDLOWAT socket option,\nwith the specified size.
This directive is ignored on Linux, Solaris, and Windows.
\n" @@ -2497,9 +2990,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Sets a timeout for transmitting a request to the FastCGI server.\nThe timeout is set only between two successive write operations,\nnot for the transmission of the whole request.\nIf the FastCGI server does not receive anything within this time,\nthe connection is closed.
\n" @@ -2512,9 +3008,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Configures the “TCP keepalive” behavior\nfor outgoing connections to a FastCGI server.\nBy default, the operating system’s settings are in effect for the socket.\nIf the directive is set to the value “on”, the\nSO_KEEPALIVE socket option is turned on for the socket.
regex
Defines a regular expression that captures a value for the\n$fastcgi_path_info variable.\nThe regular expression should have two captures: the first becomes\na value of the $fastcgi_script_name variable, the second\nbecomes a value of the $fastcgi_path_info variable.\nFor example, with these settings
location ~ ^(.+\\.php)(.*)$ {\n fastcgi_split_path_info ^(.+\\.php)(.*)$;\n fastcgi_param SCRIPT_FILENAME /path/to/php$fastcgi_script_name;\n fastcgi_param PATH_INFO $fastcgi_path_info;\nand the “/show.php/article/0001” request,\nthe SCRIPT_FILENAME parameter will be equal to\n“/path/to/php/show.php”, and the\nPATH_INFO parameter will be equal to\n“/article/0001”.
on | off | string
Enables saving of files to a disk.\nThe on parameter saves files with paths\ncorresponding to the directives\nalias or\nroot.\nThe off parameter disables saving of files.\nIn addition, the file name can be set explicitly using the\nstring with variables:
fastcgi_store /data/www$original_uri;\nThe modification time of files is set according to the received\n“Last-Modified” response header field.\nThe response is first written to a temporary file,\nand then the file is renamed.\nStarting from version 0.8.9, temporary files and the persistent store\ncan be put on different file systems.\nHowever, be aware that in this case a file is copied\nacross two file systems instead of the cheap renaming operation.\nIt is thus recommended that for any given location both saved files and a\ndirectory holding temporary files, set by the fastcgi_temp_path\ndirective, are put on the same file system.
This directive can be used to create local copies of static unchangeable\nfiles, e.g.:
\n\nlocation /images/ {\n root /data/www;\n error_page 404 = /fetch$uri;\n}\n\nlocation /fetch/ {\n internal;\n\n fastcgi_pass backend:9000;\n ...\n\n fastcgi_store on;\n fastcgi_store_access user:rw group:rw all:r;\n fastcgi_temp_path /data/temp;\n\n alias /data/www/;\n}\nusers:permissions …
Sets access permissions for newly created files and directories, e.g.:
\n\nfastcgi_store_access user:rw group:rw all:r;\nIf any group or all access permissions\nare specified then user permissions may be omitted:
fastcgi_store_access group:rw all:r;\nsize
Limits the size of data written to a temporary file\nat a time, when buffering of responses from the FastCGI server\nto temporary files is enabled.\nBy default, size is limited by two buffers set by the\nfastcgi_buffer_size and fastcgi_buffers directives.\nThe maximum size of a temporary file is set by the\nfastcgi_max_temp_file_size directive.
path [level1 [level2 [level3]]]
Defines a directory for storing temporary files\nwith data received from FastCGI servers.\nUp to three-level subdirectory hierarchy can be used underneath the specified\ndirectory.\nFor example, in the following configuration
\n\nfastcgi_temp_path /spool/nginx/fastcgi_temp 1 2;\na temporary file might look like this:
\n\n/spool/nginx/fastcgi_temp/7/45/00000123457\nSee also the use_temp_path parameter of the\nfastcgi_cache_path directive.
[$address] $variable {...}
Describes the dependency of values of the specified variable\non the client IP address.\nBy default, the address is taken from the $remote_addr variable,\nbut it can also be taken from another variable (0.7.27), for example:
geo $arg_remote_addr $geo {\n ...;\n}\n\n\n\nSince variables are evaluated only when used, the mere existence\nof even a large number of declared “
\ngeo” variables\ndoes not cause any extra costs for request processing.
If the value of a variable does not represent a valid IP address\nthen the “255.255.255.255” address is used.
Addresses are specified either as prefixes in CIDR notation\n(including individual addresses) or as ranges (0.7.23).
\n\n\n\n\nIPv6 prefixes are supported starting from versions 1.3.10 and 1.2.7.
\n
The following special parameters are also supported:
\n\ndelete
deletes the specified network (0.7.23).
default
a value set to the variable if the client address does not\nmatch any of the specified addresses.\nWhen addresses are specified in CIDR notation,\n“0.0.0.0/0” and “::/0”\ncan be used instead of default.\nWhen default is not specified, the default\nvalue will be an empty string.
include
includes a file with addresses and values.\nThere can be several inclusions.
proxy
defines trusted addresses (0.8.7, 0.7.63).\nWhen a request comes from a trusted address,\nan address from the “X-Forwarded-For” request\nheader field will be used instead.\nIn contrast to the regular addresses, trusted addresses are\nchecked sequentially.
\n\n\n\nTrusted IPv6 addresses are supported starting from versions 1.3.0 and 1.2.1.
\n
proxy_recursive
enables recursive address search (1.3.0, 1.2.1).\nIf recursive search is disabled then instead of the original client\naddress that matches one of the trusted addresses, the last\naddress sent in “X-Forwarded-For” will be used.\nIf recursive search is enabled then instead of the original client\naddress that matches one of the trusted addresses, the last\nnon-trusted address sent in “X-Forwarded-For” will be used.
ranges
indicates that addresses are specified as ranges (0.7.23).\nThis parameter should be the first.\nTo speed up loading of a geo base, addresses should be put in ascending order.
Example:
\n\ngeo $country {\n default ZZ;\n include conf/geo.conf;\n delete 127.0.0.0/16;\n proxy 192.168.100.0/24;\n proxy 2001:0db8::/32;\n\n 127.0.0.0/24 US;\n 127.0.0.1/32 RU;\n 10.1.0.0/16 RU;\n 192.168.1.0/24 UK;\n}\nThe conf/geo.conf file could contain the following lines:
10.2.0.0/16 RU;\n192.168.2.0/24 RU;\nA value of the most specific match is used.\nFor example, for the 127.0.0.1 address the value “RU”\nwill be chosen, not “US”.
Example with ranges:
\n\ngeo $country {\n ranges;\n default ZZ;\n 127.0.0.0-127.0.0.0 US;\n 127.0.0.1-127.0.0.1 RU;\n 127.0.0.1-127.0.0.255 US;\n 10.1.0.0-10.1.255.255 RU;\n 192.168.1.0-192.168.1.255 UK;\n}\nfile
Specifies a database used to determine the country\ndepending on the client IP address.\nThe following variables are available when using this database:
\n\n$geoip_country_code
two-letter country code, for example,\n“RU”, “US”.
$geoip_country_code3
three-letter country code, for example,\n“RUS”, “USA”.
$geoip_country_name
country name, for example,\n“Russian Federation”, “United States”.
file
Specifies a database used to determine the country, region, and city\ndepending on the client IP address.\nThe following variables are available when using this database:
\n\n$geoip_area_code
telephone area code (US only).
\n\n\n\nThis variable may contain outdated information since\nthe corresponding database field is deprecated.
\n
$geoip_city_continent_code
two-letter continent code, for example,\n“EU”, “NA”.
$geoip_city_country_code
two-letter country code, for example,\n“RU”, “US”.
$geoip_city_country_code3
three-letter country code, for example,\n“RUS”, “USA”.
$geoip_city_country_name
country name, for example,\n“Russian Federation”, “United States”.
$geoip_dma_code
DMA region code in US (also known as “metro code”), according to the\ngeotargeting\nin Google AdWords API.
$geoip_latitude
latitude.
$geoip_longitude
longitude.
$geoip_region
two-symbol country region code (region, territory, state, province, federal land\nand the like), for example,\n“48”, “DC”.
$geoip_region_name
country region name (region, territory, state, province, federal land\nand the like), for example,\n“Moscow City”, “District of Columbia”.
$geoip_city
city name, for example,\n“Moscow”, “Washington”.
$geoip_postal_code
postal code.
file
Specifies a database used to determine the organization\ndepending on the client IP address.\nThe following variable is available when using this database:
\n\n$geoip_org
organization name, for example, “The University of Melbourne”.
address | CIDR
Defines trusted addresses.\nWhen a request comes from a trusted address,\nan address from the “X-Forwarded-For” request\nheader field will be used instead.
\n" @@ -2694,9 +3226,12 @@ "contexts": [ "http" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
If recursive search is disabled then instead of the original client\naddress that matches one of the trusted addresses, the last\naddress sent in “X-Forwarded-For” will be used.\nIf recursive search is enabled then instead of the original client\naddress that matches one of the trusted addresses, the last\nnon-trusted address sent in “X-Forwarded-For” will be used.
\n" @@ -2715,9 +3250,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`address`* [`transparent `] | `off`" ], + "syntax_html": [ + "address [transparent] | off
Makes outgoing connections to a gRPC server originate\nfrom the specified local IP address with an optional port.\nParameter value can contain variables.\nThe special value off cancels the effect\nof the grpc_bind directive\ninherited from the previous configuration level, which allows the\nsystem to auto-assign the local IP address and port.
The transparent parameter allows\noutgoing connections to a gRPC server originate\nfrom a non-local IP address,\nfor example, from a real IP address of a client:
grpc_bind $remote_addr transparent;\nIn order for this parameter to work,\nit is usually necessary to run nginx worker processes with the\nsuperuser privileges.\nOn Linux it is not required as if\nthe transparent parameter is specified, worker processes\ninherit the CAP_NET_RAW capability from the master process.\nIt is also necessary to configure kernel routing table\nto intercept network traffic from the gRPC server.
size
Sets the size of the buffer used for reading the response\nreceived from the gRPC server.\nThe response is passed to the client synchronously, as soon as it is received.
time
Defines a timeout for establishing a connection with a gRPC server.\nIt should be noted that this timeout cannot usually exceed 75 seconds.
\n" @@ -2760,9 +3304,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`field`*" ], + "syntax_html": [ + "field
By default,\nnginx does not pass the header fields “Date”,\n“Server”, and\n“X-Accel-…” from the response of a gRPC\nserver to a client.\nThe grpc_hide_header directive sets additional fields\nthat will not be passed.\nIf, on the contrary, the passing of fields needs to be permitted,\nthe grpc_pass_header directive can be used.
field …
Disables processing of certain response header fields from the gRPC server.\nThe following fields can be ignored: “X-Accel-Redirect”\nand “X-Accel-Charset”.
\n\nIf not disabled, processing of these header fields has the following\neffect:
\n\ncharset\nof a response.on | off
Determines whether gRPC server responses with codes greater than or equal\nto 300 should be passed to a client\nor be intercepted and redirected to nginx for processing\nwith the error_page directive.
error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off …
Specifies in which cases a request should be passed to the next server:
\n\nerror
an error occurred while establishing a connection with the\nserver, passing a request to it, or reading the response header;
timeout
a timeout has occurred while establishing a connection with the\nserver, passing a request to it, or reading the response header;
invalid_header
a server returned an empty or invalid response;
http_500
a server returned a response with the code 500;
http_502
a server returned a response with the code 502;
http_503
a server returned a response with the code 503;
http_504
a server returned a response with the code 504;
http_403
a server returned a response with the code 403;
http_404
a server returned a response with the code 404;
http_429
a server returned a response with the code 429;
non_idempotent
normally, requests with a\nnon-idempotent\nmethod\n(POST, LOCK, PATCH)\nare not passed to the next server\nif a request has been sent to an upstream server;\nenabling this option explicitly allows retrying such requests;
off
disables passing a request to the next server.
One should bear in mind that passing a request to the next server is\nonly possible if nothing has been sent to a client yet.\nThat is, if an error or timeout occurs in the middle of the\ntransferring of a response, fixing this is impossible.
\n\nThe directive also defines what is considered an\nunsuccessful attempt of communication with a server.\nThe cases of error, timeout and\ninvalid_header are always considered unsuccessful attempts,\neven if they are not specified in the directive.\nThe cases of http_500, http_502,\nhttp_503, http_504,\nand http_429 are\nconsidered unsuccessful attempts only if they are specified in the directive.\nThe cases of http_403 and http_404\nare never considered unsuccessful attempts.
Passing a request to the next server can be limited by\nthe number of tries\nand by time.
\n" @@ -2820,9 +3376,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Limits the time during which a request can be passed to the\nnext server.\nThe 0 value turns off this limitation.
number
Limits the number of possible tries for passing a request to the\nnext server.\nThe 0 value turns off this limitation.
address
Sets the gRPC server address.\nThe address can be specified as a domain name or IP address,\nand a port:
\n\ngrpc_pass localhost:9000;\nor as a UNIX-domain socket path:
\n\ngrpc_pass unix:/tmp/grpc.socket;\nAlternatively, the “grpc://” scheme can be used:
grpc_pass grpc://127.0.0.1:9000;\nTo use gRPC over SSL, the “grpcs://” scheme should be used:
grpc_pass grpcs://127.0.0.1:443;\nIf a domain name resolves to several addresses, all of them will be\nused in a round-robin fashion.\nIn addition, an address can be specified as a\nserver group.
\n\nParameter value can contain variables (1.17.8).\nIn this case, if an address is specified as a domain name,\nthe name is searched among the described\nserver groups,\nand, if not found, is determined using a\nresolver.
field
Permits passing otherwise disabled header\nfields from a gRPC server to a client.
\n" @@ -2879,9 +3447,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Defines a timeout for reading a response from the gRPC server.\nThe timeout is set only between two successive read operations,\nnot for the transmission of the whole response.\nIf the gRPC server does not transmit anything within this time,\nthe connection is closed.
\n" @@ -2894,9 +3465,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Sets a timeout for transmitting a request to the gRPC server.\nThe timeout is set only between two successive write operations,\nnot for the transmission of the whole request.\nIf the gRPC server does not receive anything within this time,\nthe connection is closed.
\n" @@ -2909,9 +3483,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`field`* *`value`*" ], + "syntax_html": [ + "field value
Allows redefining or appending fields to the request header\npassed to the gRPC server.\nThe value can contain text, variables, and their combinations.\nThese directives are inherited from the previous configuration level\nif and only if there are no grpc_set_header directives\ndefined on the current level.
If the value of a header field is an empty string then this\nfield will not be passed to a gRPC server:
\n\ngrpc_set_header Accept-Encoding "";\non | off
Configures the “TCP keepalive” behavior\nfor outgoing connections to a gRPC server.\nBy default, the operating system’s settings are in effect for the socket.\nIf the directive is set to the value “on”, the\nSO_KEEPALIVE socket option is turned on for the socket.
file
Specifies a file with the certificate in the PEM format\nused for authentication to a gRPC SSL server.
Since version 1.21.0, variables can be used in the file name.
file
Specifies a file with the secret key in the PEM format\nused for authentication to a gRPC SSL server.
The value\nengine:name:id\ncan be specified instead of the file,\nwhich loads a secret key with a specified id\nfrom the OpenSSL engine name.
Since version 1.21.0, variables can be used in the file name.
ciphers
Specifies the enabled ciphers for requests to a gRPC SSL server.\nThe ciphers are specified in the format understood by the OpenSSL library.
\n\nThe full list can be viewed using the\n“openssl ciphers” command.
name value
Sets arbitrary OpenSSL configuration\ncommands\nwhen establishing a connection with the gRPC SSL server.
\n\n\n\n\nThe directive is supported when using OpenSSL 1.0.2 or higher.
\n
Several grpc_ssl_conf_command directives\ncan be specified on the same level.\nThese directives are inherited from the previous configuration level\nif and only if there are\nno grpc_ssl_conf_command directives\ndefined on the current level.
\n\n" @@ -2999,9 +3591,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "Note that configuring OpenSSL directly\nmight result in unexpected behavior.
\n
file
Specifies a file with revoked certificates (CRL)\nin the PEM format used to verify\nthe certificate of the gRPC SSL server.
name
Allows overriding the server name used to\nverify\nthe certificate of the gRPC SSL server and to be\npassed through SNI\nwhen establishing a connection with the gRPC SSL server.
\n\nBy default, the host part from grpc_pass is used.
file
Specifies a file with passphrases for\nsecret keys\nwhere each passphrase is specified on a separate line.\nPassphrases are tried in turn when loading the key.
[SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]
Enables the specified protocols for requests to a gRPC SSL server.
\n\n\n\n" @@ -3059,9 +3663,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "The
\nTLSv1.3parameter is used by default\nsince 1.23.4.
on | off
Enables or disables passing of the server name through\nTLS Server Name Indication extension (SNI, RFC 6066)\nwhen establishing a connection with the gRPC SSL server.
\n" @@ -3074,9 +3681,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Determines whether SSL sessions can be reused when working with\nthe gRPC server.\nIf the errors\n“SSL3_GET_FINISHED:digest check failed”\nappear in the logs, try disabling session reuse.
file
Specifies a file with trusted CA certificates in the PEM format\nused to verify\nthe certificate of the gRPC SSL server.
on | off
Enables or disables verification of the gRPC SSL server certificate.
\n" @@ -3119,9 +3735,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
Sets the verification depth in the gRPC SSL server certificates chain.
\n" @@ -3140,9 +3759,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables decompression of gzipped responses\nfor clients that lack gzip support.\nIf enabled, the following directives are also taken into account\nwhen determining if clients support gzip:\ngzip_http_version,\ngzip_proxied, and\ngzip_disable.\nSee also the gzip_vary directive.
number size
Sets the number and size of buffers\nused to decompress a response.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.
on | off
Enables or disables gzipping of responses.
\n" @@ -3192,9 +3820,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`number`* *`size`*" ], + "syntax_html": [ + "number size
Sets the number and size of buffers\nused to compress a response.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.
\n\n" @@ -3207,9 +3838,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`level`*" ], + "syntax_html": [ + "Until version 0.7.28, four 4K or 8K buffers were used by default.
\n
level
Sets a gzip compression level of a response.\nAcceptable values are in the range from 1 to 9.
regex …
Disables gzipping of responses for requests with\n“User-Agent” header fields matching\nany of the specified regular expressions.
\n\nThe special mask “msie6” (0.7.12) corresponds to\nthe regular expression “MSIE [4-6]\\.”, but works faster.\nStarting from version 0.8.11, “MSIE 6.0; ... SV1”\nis excluded from this mask.
1.0 | 1.1
Sets the minimum HTTP version of a request required to compress a response.
\n" @@ -3252,9 +3892,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`length`*" ], + "syntax_html": [ + "length
Sets the minimum length of a response that will be gzipped.\nThe length is determined only from the “Content-Length”\nresponse header field.
\n" @@ -3267,9 +3910,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`off` | `expired` | `no-cache` | `no-store` | `private` | `no_last_modified` | `no_etag` | `auth` | `any` ..." ], + "syntax_html": [ + "off | expired | no-cache | no-store | private | no_last_modified | no_etag | auth | any …
Enables or disables gzipping of responses for proxied\nrequests depending on the request and response.\nThe fact that the request is proxied is determined by\nthe presence of the “Via” request header field.\nThe directive accepts multiple parameters:
\n\noff
disables compression for all proxied requests,\nignoring other parameters;
expired
enables compression if a response header includes the\n“Expires” field with a value that disables caching;
no-cache
enables compression if a response header includes the\n“Cache-Control” field with the\n“no-cache” parameter;
no-store
enables compression if a response header includes the\n“Cache-Control” field with the\n“no-store” parameter;
private
enables compression if a response header includes the\n“Cache-Control” field with the\n“private” parameter;
no_last_modified
enables compression if a response header does not include the\n“Last-Modified” field;
no_etag
enables compression if a response header does not include the\n“ETag” field;
auth
enables compression if a request header includes the\n“Authorization” field;
any
enables compression for all proxied requests.
mime-type …
Enables gzipping of responses for the specified MIME types in addition\nto “text/html”.\nThe special value “*” matches any MIME type (0.8.29).\nResponses with the “text/html” type are always compressed.
on | off
Enables or disables inserting the “Vary: Accept-Encoding”\nresponse header field if the directives\ngzip,\ngzip_static, or\ngunzip\nare active.
on | off | always
Enables (“on”) or disables (“off”)\nchecking the existence of precompressed files.\nThe following directives are also taken into account:\ngzip_http_version,\ngzip_proxied,\ngzip_disable,\nand gzip_vary.
With the “always” value (1.3.6), gzipped file is used\nin all cases, without checking if the client supports it.\nIt is useful if there are no uncompressed files on the disk anyway\nor the ngx_http_gunzip_module\nis used.
The files can be compressed using the gzip command,\nor any other compatible one.\nIt is recommended that the modification date and time of original and\ncompressed files be the same.
name value [always]
Adds the specified field to a response header provided that\nthe response code equals 200, 201 (1.3.10), 204, 206, 301, 302, 303, 304,\n307 (1.1.16, 1.0.13), or 308 (1.13.0).\nParameter value can contain variables.
\n\nThere could be several add_header directives.\nThese directives are inherited from the previous configuration level\nif and only if there are no add_header directives\ndefined on the current level.
If the always parameter is specified (1.7.5),\nthe header field will be added regardless of the response code.
name value [always]
Adds the specified field to the end of a response provided that\nthe response code equals 200, 201, 206, 301, 302, 303, 307, or 308.\nParameter value can contain variables.
\n\nThere could be several add_trailer directives.\nThese directives are inherited from the previous configuration level\nif and only if there are no add_trailer directives\ndefined on the current level.
If the always parameter is specified\nthe specified field will be added regardless of the response code.
[modified] time
epoch | max | off
Enables or disables adding or modifying the “Expires”\nand “Cache-Control” response header fields provided that\nthe response code equals 200, 201 (1.3.10), 204, 206, 301, 302, 303, 304,\n307 (1.1.16, 1.0.13), or 308 (1.13.0).\nThe parameter can be a positive or negative\ntime.
\n\nThe time in the “Expires” field is computed as a sum of the\ncurrent time and time specified in the directive.\nIf the modified parameter is used (0.7.0, 0.6.32)\nthen the time is computed as a sum of the file’s modification time and\nthe time specified in the directive.
In addition, it is possible to specify a time of day using\nthe “@” prefix (0.7.9, 0.6.34):
expires @15h30m;\nThe contents of the “Cache-Control” field depends\non the sign of the specified time:
\n\nt is a time specified in the directive, in seconds.The epoch parameter sets “Expires”\nto the value “Thu, 01 Jan 1970 00:00:01 GMT”,\nand “Cache-Control” to “no-cache”.
The max parameter sets “Expires”\nto the value “Thu, 31 Dec 2037 23:55:55 GMT”,\nand “Cache-Control” to 10 years.
The off parameter disables adding or modifying the\n“Expires” and “Cache-Control” response\nheader fields.
The last parameter value can contain variables (1.7.9):
\n\nmap $sent_http_content_type $expires {\n default off;\n application/pdf 42d;\n ~image/ max;\n}\n\nexpires $expires;\nnumber size
Sets the maximum number and size of buffers\nthat are used for reading and writing data frames.
on | off
Adds arguments from a playlist request to URIs of fragments.\nThis may be useful for performing client authorization at the moment of\nrequesting a fragment, or when protecting an HLS stream with the\nngx_http_secure_link_module\nmodule.
\n\nFor example, if a client requests a playlist\nhttp://example.com/hls/test.mp4.m3u8?a=1&b=2,\nthe arguments a=1 and b=2\nwill be added to URIs of fragments after the arguments\nstart and end:
#EXTM3U\n#EXT-X-VERSION:3\n#EXT-X-TARGETDURATION:15\n#EXT-X-PLAYLIST-TYPE:VOD\n\n#EXTINF:9.333,\ntest.mp4.ts?start=0.000&end=9.333&a=1&b=2\n#EXTINF:7.167,\ntest.mp4.ts?start=9.333&end=16.500&a=1&b=2\n#EXTINF:5.416,\ntest.mp4.ts?start=16.500&end=21.916&a=1&b=2\n#EXTINF:5.500,\ntest.mp4.ts?start=21.916&end=27.416&a=1&b=2\n#EXTINF:15.167,\ntest.mp4.ts?start=27.416&end=42.583&a=1&b=2\n#EXTINF:9.626,\ntest.mp4.ts?start=42.583&end=52.209&a=1&b=2\n\n#EXT-X-ENDLIST\nIf an HLS stream is protected with the\nngx_http_secure_link_module\nmodule, $uri should not be used in the\nsecure_link_md5\nexpression because this will cause errors when requesting the fragments.\nBase URI should be used\ninstead of $uri\n($hls_uri in the example):
http {\n ...\n\n map $uri $hls_uri {\n ~^(?<base_uri>.*).m3u8$ $base_uri;\n ~^(?<base_uri>.*).ts$ $base_uri;\n default $uri;\n }\n\n server {\n ...\n\n location /hls/ {\n hls;\n hls_forward_args on;\n\n alias /var/videos/;\n\n secure_link $arg_md5,$arg_expires;\n secure_link_md5 "$secure_link_expires$hls_uri$remote_addr secret";\n\n if ($secure_link = "") {\n return 403;\n }\n\n if ($secure_link = "0") {\n return 410;\n }\n }\n }\n}\ntime
Defines the default fragment length for playlist URIs requested without the\n“len” argument.
size
Sets the initial size of the buffer used for\nprocessing MP4 and MOV files.
size
During metadata processing, a larger buffer may become necessary.\nIts size cannot exceed the specified size,\nor else nginx will return the server error\n500 (Internal Server Error),\nand log the following message:
"/some/movie/file.mp4" mp4 moov atom is too large:\n12583268, you may want to increase hls_mp4_max_buffer_size\noff
test
size
rotate 90 | 180 | 270
resize width height
crop width height
Sets the type of transformation to perform on images:
\n\noff
turns off module processing in a surrounding location.
test
ensures that responses are images in either JPEG, GIF, PNG, or WebP format.\nOtherwise, the\n415 (Unsupported Media Type)\nerror is returned.
size
outputs information about images in a JSON format, e.g.:
\n\n{ "img" : { "width": 100, "height": 100, "type": "gif" } }\nIn case of an error, the output is as follows:
\n\n{}\nrotate\n90|180|270
rotates images counter-clockwise by the specified number of degrees.\nParameter value can contain variables.\nThis mode can be used either alone or along with the\nresize and crop transformations.
resize\nwidth\nheight
proportionally reduces an image to the specified sizes.\nTo reduce by only one dimension, another dimension can be specified as\n“-”.\nIn case of an error, the server will return code\n415 (Unsupported Media Type).\nParameter values can contain variables.\nWhen used along with the rotate parameter,\nthe rotation happens after reduction.
crop\nwidth\nheight
proportionally reduces an image to the larger side size\nand crops extraneous edges by another side.\nTo reduce by only one dimension, another dimension can be specified as\n“-”.\nIn case of an error, the server will return code\n415 (Unsupported Media Type).\nParameter values can contain variables.\nWhen used along with the rotate parameter,\nthe rotation happens before reduction.
size
Sets the maximum size of the buffer used for reading images.\nWhen the size is exceeded the server returns error\n415 (Unsupported Media Type).
\n" @@ -3521,9 +4215,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
If enabled, final images will be interlaced.\nFor JPEG, final images will be in “progressive JPEG” format.
\n" @@ -3536,9 +4233,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`quality`*" ], + "syntax_html": [ + "quality
Sets the desired quality of the transformed JPEG images.\nAcceptable values are in the range from 1 to 100.\nLesser values usually imply both lower image quality and less data to transfer.\nThe maximum recommended value is 95.\nParameter value can contain variables.
percent
Increases sharpness of the final image.\nThe sharpness percentage can exceed 100.\nThe zero value disables sharpening.\nParameter value can contain variables.
\n" @@ -3566,9 +4269,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on`|`off`" ], + "syntax_html": [ + "on|off
Defines whether transparency should be preserved when transforming\nGIF images or PNG images with colors specified by a palette.\nThe loss of transparency results in images of a better quality.\nThe alpha channel transparency in PNG is always preserved.
\n" @@ -3581,9 +4287,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`quality`*" ], + "syntax_html": [ + "quality
Sets the desired quality of the transformed WebP images.\nAcceptable values are in the range from 1 to 100.\nLesser values usually imply both lower image quality and less data to transfer.\nParameter value can contain variables.
file …
Defines files that will be used as an index.\nThe file name can contain variables.\nFiles are checked in the specified order.\nThe last element of the list can be a file with an absolute path.\nExample:
index index.$geo.html index.0.html /index.html;\nIt should be noted that using an index file causes an internal redirect,\nand the request can be processed in a different location.\nFor example, with the following configuration:
\n\nlocation = / {\n index index.html;\n}\n\nlocation / {\n ...\n}\na “/” request will actually be processed in the\nsecond location as “/index.html”.
uri
Sets the URI for internal redirection of the request.\nIt is also possible to use a\nnamed location\ninstead of the URI.\nThe uri value can contain variables.\nIf the uri value is empty,\nthen the redirect will not be made.
function | module.function [buffer_type=string | buffer]
Sets an njs function as a response body filter.\nThe filter function is called for each data chunk of a response body\nwith the following arguments:
\n\nr
the HTTP request object
data
the incoming data chunk,\nmay be a string or Buffer\ndepending on the buffer_type value,\nby default is a string.
flags
an object with the following properties:
\n\nlast
a boolean value, true if data is a last buffer.
The filter function can pass its own modified version\nof the input data chunk to the next body filter by calling\nr.sendBuffer().\nFor example, to transform all the lowercase letters in the response body:
function filter(r, data, flags) {\n r.sendBuffer(data.toLowerCase(), flags);\n}\nTo stop filtering (following data chunks will be passed to client\nwithout calling js_body_filter),\nr.done()\ncan be used.
If the filter function changes the length of the response body, then\nit is required to clear out the “Content-Length” response header\n(if any) in\njs_header_filter\nto enforce chunked transfer encoding.
\n\n" @@ -3658,9 +4376,12 @@ "if in location", "limit_except" ], - "syntax": [ + "syntax_md": [ "*`function`* | *`module.function`*" ], + "syntax_html": [ + "As the
\n\njs_body_filterhandler\nreturns its result immediately, it supports\nonly synchronous operations.\nThus, asynchronous operations such as\nr.subrequest()\nor\nsetTimeout()\nare not supported.The directive can be specified inside the\nif block\nsince 0.7.7.
\n
function | module.function
Sets an njs function as a location content handler.\nSince 0.4.0,\na module function can be referenced.
\n\n\n\n" @@ -3673,9 +4394,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "The directive can be specified inside the\nif block\nsince 0.7.7.
\n
size
Sets the size of the buffer used for reading and writing\nwith Fetch API.
ciphers
Specifies the enabled ciphers for HTTPS requests\nwith Fetch API.\nThe ciphers are specified in the format understood by the\nOpenSSL library.
\n\nThe full list can be viewed using the\n“openssl ciphers” command.
size
Sets the maximum size of the response received\nwith Fetch API.
[TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]
Enables the specified protocols for HTTPS requests\nwith Fetch API.
\n" @@ -3733,9 +4466,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Defines a timeout for reading and writing\nfor Fetch API.\nThe timeout is set only between two successive read/write operations,\nnot for the whole response.\nIf no data is transmitted within this time, the connection is closed.
\n" @@ -3748,9 +4484,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "file
Specifies a file with trusted CA certificates in the PEM format\nused to\nverify\nthe HTTPS certificate\nwith Fetch API.
on | off
Enables or disables verification of the HTTPS server certificate\nwith Fetch API.
\n" @@ -3778,9 +4520,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
Sets the verification depth in the HTTPS server certificates chain\nwith Fetch API.
\n" @@ -3793,9 +4538,12 @@ "if in location", "limit_except" ], - "syntax": [ + "syntax_md": [ "*`function`* | *`module.function`*" ], + "syntax_html": [ + "function | module.function
Sets an njs function as a response header filter.\nThe directive allows changing arbitrary header fields of a response header.
\n\n\n\n" @@ -3808,9 +4556,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`module.js`* | *`export_name from module.js`*" ], + "syntax_html": [ + "As the
\n\njs_header_filterhandler\nreturns its result immediately, it supports\nonly synchronous operations.\nThus, asynchronous operations such as\nr.subrequest()\nor\nsetTimeout()\nare not supported.The directive can be specified inside the\nif block\nsince 0.7.7.
\n
module.js | export_name from module.js
Imports a module that implements location and variable handlers in njs.\nThe export_name is used as a namespace\nto access module functions.\nIf the export_name is not specified,\nthe module name will be used as a namespace.
js_import http.js;\nHere, the module name http is used as a namespace\nwhile accessing exports.\nIf the imported module exports foo(),\nhttp.foo is used to refer to it.
Several js_import directives can be specified.
\n\n" @@ -3821,9 +4572,12 @@ "contexts": [ "http" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "The directive can be specified on the\n
\nserverandlocationlevel\nsince 0.7.7.
file
Specifies a file that implements location and variable handlers in njs:
\n\nnginx.conf:\njs_include http.js;\nlocation /version {\n js_content version;\n}\n\nhttp.js:\nfunction version(r) {\n r.return(200, njs.version);\n}\nThe directive was made obsolete in version\n0.4.0\nand was removed in version\n0.7.1.\nThe js_import directive should be used instead.
path
Sets an additional path for njs modules.
\n\n\n\n" @@ -3851,9 +4608,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`name.json`* | *`name`* from *`file.json`*" ], + "syntax_html": [ + "The directive can be specified on the\n
\nserverandlocationlevel\nsince 0.7.7.
name.json | name from file.json
Preloads an\nimmutable object\nat configure time.\nThe name is used a name of the global variable\nthough which the object is available in njs code.\nIf the name is not specified,\nthe file name will be used instead.
js_preload_object map.json;\nHere, the map is used as a name\nwhile accessing the preloaded object.
Several js_preload_object directives can be specified.
$variable function | module.function
Sets an njs function\nfor the specified variable.\nSince 0.4.0,\na module function can be referenced.
The function is called when\nthe variable is referenced for the first time for a given request.\nThe exact moment depends on a\nphase\nat which the variable is referenced.\nThis can be used to perform some logic\nnot related to variable evaluation.\nFor example, if the variable is referenced only in the\nlog_format directive,\nits handler will not be executed until the log phase.\nThis handler can be used to do some cleanup\nright before the request is freed.
\n\n" @@ -3879,9 +4642,12 @@ "contexts": [ "http" ], - "syntax": [ + "syntax_md": [ "`zone`=*`name`*:*`size`* [`timeout`=*`time`*] [`type`=`string`|`number`] [`evict`]" ], + "syntax_html": [ + "As the
\n\njs_sethandler\nreturns its result immediately, it supports\nonly synchronous operations.\nThus, asynchronous operations such as\nr.subrequest()\nor\nsetTimeout()\nare not supported.The directive can be specified on the\n
\nserverandlocationlevel\nsince 0.7.7.
zone=name:size [timeout=time] [type=string|number] [evict]
Sets the name and size of the shared memory zone\nthat keeps the key-value dictionary\nshared between worker processes.
By default the shared dictionary uses a string as a key and a value.\nThe optional type parameter\nallows redefining the value type to number.
The optional timeout parameter sets\nthe time after which all shared dictionary entries are removed from the zone.
The optional evict parameter removes the oldest\nkey-value pair when the zone storage is exhausted.
Examples:
\n\nexample.conf:\n # Creates a 1Mb dictionary with string values,\n # removes key-value pairs after 60 seconds of inactivity:\n js_shared_dict_zone zone=foo:1M timeout=60s;\n\n # Creates a 512Kb dictionary with string values,\n # forcibly removes oldest key-value pairs when the zone is exhausted:\n js_shared_dict_zone zone=bar:512K timeout=30s evict;\n\n # Creates a 32Kb permanent dictionary with number values:\n js_shared_dict_zone zone=num:32k type=number;\n\nexample.js:\n function get(r) {\n r.return(200, ngx.shared.foo.get(r.args.key));\n }\n\n function set(r) {\n r.return(200, ngx.shared.foo.set(r.args.key, r.args.value));\n }\n\n function del(r) {\n r.return(200, ngx.shared.bar.delete(r.args.key));\n }\n\n function increment(r) {\n r.return(200, ngx.shared.num.incr(r.args.key, 2));\n }\n$variable [value]
Declares\na writable\nvariable.\nThe value can contain text, variables, and their combination.\nThe variable is not overwritten after a redirect\nunlike variables created with the\nset directive.
\n\n" @@ -3913,9 +4682,12 @@ "contexts": [ "http" ], - "syntax": [ + "syntax_md": [ "*`key`* *`$variable`* `zone`=*`name`*" ], + "syntax_html": [ + "The directive can be specified on the\n
\nserverandlocationlevel\nsince 0.7.7.
key $variable zone=name
Creates a new $variable whose value\nis looked up by the key in the key-value database.\nMatching rules are defined by the\ntype parameter of the\nkeyval_zone directive.\nThe database is stored in a shared memory zone\nspecified by the zone parameter.
zone=name:size [state=file] [timeout=time] [type=string|ip|prefix] [sync]
Sets the name and size of the shared memory zone\nthat keeps the key-value database.\nKey-value pairs are managed by the\nAPI.
The optional state parameter specifies a file\nthat keeps the current state of the key-value database in the JSON format\nand makes it persistent across nginx restarts.\nChanging the file content directly should be avoided.
Examples:
\n\nkeyval_zone zone=one:32k state=/var/lib/nginx/state/one.keyval; # path for Linux\nkeyval_zone zone=one:32k state=/var/db/nginx/state/one.keyval; # path for FreeBSD\nThe optional timeout parameter (1.15.0) sets\nthe time after which key-value pairs are removed from the zone.
The optional type parameter (1.17.1) activates\nan extra index optimized for matching the key of a certain type\nand defines matching rules when evaluating\na keyval $variable.
\n\n\nThe index is stored in the same shared memory zone\nand thus requires additional storage.
\n
type=string
default, no index is enabled;\nvariable lookup is performed using exact match\nof the record key and a search key
type=ip
the search key is the textual representation of IPv4 or IPv6 address\nor CIDR range;\nto match a record key, the search key must belong to a subnet\nspecified by a record key or exactly match an IP address
type=prefix
variable lookup is performed using prefix match\nof a record key and a search key (1.17.5);\nto match a record key, the record key must be a prefix of the search key
The optional sync parameter (1.15.0) enables\nsynchronization\nof the shared memory zone.\nThe synchronization requires the\ntimeout parameter to be set.
\n\n" @@ -3947,9 +4722,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`zone`* *`number`*" ], + "syntax_html": [ + "If the synchronization is enabled, removal of key-value pairs (no matter\none\nor\nall)\nwill be performed only on a target cluster node.\nThe same key-value pairs on other cluster nodes\nwill be removed upon
\ntimeout.
zone number
Sets the shared memory zone\nand the maximum allowed number of connections for a given key value.\nWhen this limit is exceeded, the server will return the\nerror\nin reply to a request.\nFor example, the directives
\n\nlimit_conn_zone $binary_remote_addr zone=addr:10m;\n\nserver {\n location /download/ {\n limit_conn addr 1;\n }\nallow only one connection per an IP address at a time.
\n\n\n\n\nIn HTTP/2 and HTTP/3,\neach concurrent request is considered a separate connection.
\n
There could be several limit_conn directives.\nFor example, the following configuration will limit the number\nof connections to the server per a client IP and, at the same time,\nthe total number of connections to the virtual server:
limit_conn_zone $binary_remote_addr zone=perip:10m;\nlimit_conn_zone $server_name zone=perserver:10m;\n\nserver {\n ...\n limit_conn perip 10;\n limit_conn perserver 100;\n}\nThese directives are inherited from the previous configuration level\nif and only if there are no limit_conn directives\ndefined on the current level.
on | off
Enables the dry run mode.\nIn this mode, the number of connections is not limited, however,\nin the shared memory zone, the number of excessive connections is accounted\nas usual.
\n" @@ -3977,9 +4758,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`info` | `notice` | `warn` | `error`" ], + "syntax_html": [ + "info | notice | warn | error
Sets the desired logging level for cases when the server\nlimits the number of connections.
\n" @@ -3992,9 +4776,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`code`*" ], + "syntax_html": [ + "code
Sets the status code to return in response to rejected requests.
\n" @@ -4005,9 +4792,12 @@ "contexts": [ "http" ], - "syntax": [ + "syntax_md": [ "*`key`* `zone`=*`name`*:*`size`*" ], + "syntax_html": [ + "key zone=name:size
Sets parameters for a shared memory zone\nthat will keep states for various keys.\nIn particular, the state includes the current number of connections.\nThe key can contain text, variables, and their combination.\nRequests with an empty key value are not accounted.
\n\n\nPrior to version 1.7.6, a
\nkeycould contain exactly one variable.
Usage example:
\n\nlimit_conn_zone $binary_remote_addr zone=addr:10m;\nHere, a client IP address serves as a key.\nNote that instead of $remote_addr, the\n$binary_remote_addr variable is used here.\nThe $remote_addr variable’s size can\nvary from 7 to 15 bytes.\nThe stored state occupies either\n32 or 64 bytes of memory on 32-bit platforms and always 64\nbytes on 64-bit platforms.\nThe $binary_remote_addr variable’s size\nis always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses.\nThe stored state always occupies 32 or 64 bytes\non 32-bit platforms and 64 bytes on 64-bit platforms.\nOne megabyte zone can keep about 32 thousand 32-byte states\nor about 16 thousand 64-byte states.\nIf the zone storage is exhausted, the server will return the\nerror\nto all further requests.
\n\n" @@ -4018,9 +4808,12 @@ "contexts": [ "http" ], - "syntax": [ + "syntax_md": [ "*`name`* *`$variable`* *`size`*" ], + "syntax_html": [ + "Additionally, as part of our\ncommercial subscription,\nthe\nstatus information\nfor each such shared memory zone can be\nobtained or\nreset\nwith the API since 1.17.7.
\n
name $variable size
This directive was made obsolete in version 1.1.8\nand was removed in version 1.7.6.\nAn equivalent limit_conn_zone directive\nwith a changed syntax should be used instead:
\n\n" @@ -4039,9 +4832,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`zone`=*`name`* [`burst`=*`number`*] [`nodelay` | `delay`=*`number`*]" ], + "syntax_html": [ + "\n
limit_conn_zone\n$variable\nzone=name:size;
zone=name [burst=number] [nodelay | delay=number]
Sets the shared memory zone\nand the maximum burst size of requests.\nIf the requests rate exceeds the rate configured for a zone,\ntheir processing is delayed such that requests are processed\nat a defined rate.\nExcessive requests are delayed until their number exceeds the\nmaximum burst size\nin which case the request is terminated with an\nerror.\nBy default, the maximum burst size is equal to zero.\nFor example, the directives
\n\nlimit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;\n\nserver {\n location /search/ {\n limit_req zone=one burst=5;\n }\nallow not more than 1 request per second at an average,\nwith bursts not exceeding 5 requests.
\n\nIf delaying of excessive requests while requests are being limited is not\ndesired, the parameter nodelay should be used:
limit_req zone=one burst=5 nodelay;\nThe delay parameter (1.15.7) specifies a limit\nat which excessive requests become delayed.\nDefault value is zero, i.e. all excessive requests are delayed.
There could be several limit_req directives.\nFor example, the following configuration will limit the processing rate\nof requests coming from a single IP address and, at the same time,\nthe request processing rate by the virtual server:
limit_req_zone $binary_remote_addr zone=perip:10m rate=1r/s;\nlimit_req_zone $server_name zone=perserver:10m rate=10r/s;\n\nserver {\n ...\n limit_req zone=perip burst=5 nodelay;\n limit_req zone=perserver burst=10;\n}\nThese directives are inherited from the previous configuration level\nif and only if there are no limit_req directives\ndefined on the current level.
on | off
Enables the dry run mode.\nIn this mode, requests processing rate is not limited, however,\nin the shared memory zone, the number of excessive requests is accounted\nas usual.
\n" @@ -4069,9 +4868,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`info` | `notice` | `warn` | `error`" ], + "syntax_html": [ + "info | notice | warn | error
Sets the desired logging level\nfor cases when the server refuses to process requests\ndue to rate exceeding,\nor delays request processing.\nLogging level for delays is one point less than for refusals; for example,\nif “limit_req_log_level notice” is specified,\ndelays are logged with the info level.
code
Sets the status code to return in response to rejected requests.
\n" @@ -4097,9 +4902,12 @@ "contexts": [ "http" ], - "syntax": [ + "syntax_md": [ "*`key`* `zone`=*`name`*:*`size`* `rate`=*`rate`* [`sync`]" ], + "syntax_html": [ + "key zone=name:size rate=rate [sync]
Sets parameters for a shared memory zone\nthat will keep states for various keys.\nIn particular, the state stores the current number of excessive requests.\nThe key can contain text, variables, and their combination.\nRequests with an empty key value are not accounted.
\n\n\nPrior to version 1.7.6, a
\nkeycould contain exactly one variable.
Usage example:
\n\nlimit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;\nHere, the states are kept in a 10 megabyte zone “one”, and an\naverage request processing rate for this zone cannot exceed\n1 request per second.
\n\nA client IP address serves as a key.\nNote that instead of $remote_addr, the\n$binary_remote_addr variable is used here.\nThe $binary_remote_addr variable’s size\nis always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses.\nThe stored state always occupies\n64 bytes on 32-bit platforms and 128 bytes on 64-bit platforms.\nOne megabyte zone can keep about 16 thousand 64-byte states\nor about 8 thousand 128-byte states.
If the zone storage is exhausted, the least recently used state is removed.\nIf even after that a new state cannot be created, the request is terminated with\nan error.
\n\nThe rate is specified in requests per second (r/s).\nIf a rate of less than one request per second is desired,\nit is specified in request per minute (r/m).\nFor example, half-request per second is 30r/m.
\n\nThe sync parameter (1.15.3) enables\nsynchronization\nof the shared memory zone.
\n\n" @@ -4120,10 +4928,14 @@ "if in location", "limit_except" ], - "syntax": [ + "syntax_md": [ "*`path`* [*`format`* [`buffer`=*`size`*] [`gzip[=]`] [`flush`=*`time`*] [`if`=*`condition`*]]", "`off`" ], + "syntax_html": [ + "The
\n\nsyncparameter is available as part of our\ncommercial subscription.Additionally, as part of our\ncommercial subscription,\nthe\nstatus information\nfor each such shared memory zone can be\nobtained or\nreset\nwith the API since 1.17.7.
\n
path [format [buffer=size] [gzip[=]] [flush=time] [if=condition]]
off
Sets the path, format, and configuration for a buffered log write.\nSeveral logs can be specified on the same configuration level.\nLogging to syslog\ncan be configured by specifying\nthe “syslog:” prefix in the first parameter.\nThe special value off cancels all\naccess_log directives on the current level.\nIf the format is not specified then the predefined\n“combined” format is used.
If either the buffer or gzip\n(1.3.10, 1.2.7)\nparameter is used, writes to log will be buffered.
\n\n\nThe buffer size must not exceed the size of an atomic write to a disk file.\nFor FreeBSD this size is unlimited.
\n
When buffering is enabled, the data will be written to the file:
\n\nflush\nparameter (1.3.10, 1.2.7);If the gzip parameter is used, then the buffered data will\nbe compressed before writing to the file.\nThe compression level can be set between 1 (fastest, less compression)\nand 9 (slowest, best compression).\nBy default, the buffer size is equal to 64K bytes, and the compression level\nis set to 1.\nSince the data is compressed in atomic blocks, the log file can be decompressed\nor read by “zcat” at any time.
Example:
\n\naccess_log /path/to/log.gz combined gzip flush=5m;\n\n\n\nFor gzip compression to work, nginx must be built with the zlib library.
\n
The file path can contain variables (0.7.6+),\nbut such logs have some constraints:
\n\nuser\nwhose credentials are used by worker processes should\nhave permissions to create files in a directory with\nsuch logs;open_log_file_cache\ndirective’s valid parameterroot\nand access_log on the same configuration level:\n\n\nserver {\n root /spool/vhost/data/$host;\n access_log /spool/vhost/logs/$host;\n ...\nThe if parameter (1.7.0) enables conditional logging.\nA request will not be logged if the condition evaluates to “0”\nor an empty string.\nIn the following example, the requests with response codes 2xx and 3xx\nwill not be logged:
map $status $loggable {\n ~^[23] 0;\n default 1;\n}\n\naccess_log /path/to/access.log combined if=$loggable;\nname [escape=default|json|none] string …
Specifies log format.
\n\nThe escape parameter (1.11.8) allows setting\njson or default characters escaping\nin variables, by default, default escaping is used.\nThe none value (1.13.10) disables escaping.
For default escaping,\ncharacters “"”, “\\”,\nand other characters with values less than 32 (0.7.0) or above 126 (1.1.6)\nare escaped as “\\xXX”.\nIf the variable value is not found,\na hyphen (“-”) will be logged.
For json escaping,\nall characters not allowed\nin JSON strings\nwill be escaped:\ncharacters “"” and\n“\\” are escaped as\n“\\"” and “\\\\”,\ncharacters with values less than 32 are escaped as\n“\\n”,\n“\\r”,\n“\\t”,\n“\\b”,\n“\\f”, or\n“\\u00XX”.
The log format can contain common variables, and variables that\nexist only at the time of a log write:
\n\n$bytes_sent
the number of bytes sent to a client
$connection
connection serial number
$connection_requests
the current number of requests made through a connection (1.1.18)
$msec
time in seconds with a milliseconds resolution at the time of the log write
$pipe
“p” if request was pipelined, “.”\notherwise
$request_length
request length (including request line, header, and request body)
$request_time
request processing time in seconds with a milliseconds resolution;\ntime elapsed between the first bytes were read from the client and\nthe log write after the last bytes were sent to the client
$status
response status
$time_iso8601
local time in the ISO 8601 standard format
$time_local
local time in the Common Log Format
\n\n\nIn the modern nginx versions variables\n$status\n(1.3.2, 1.2.2),\n$bytes_sent\n(1.3.8, 1.2.5),\n$connection\n(1.3.8, 1.2.5),\n$connection_requests\n(1.3.8, 1.2.5),\n$msec\n(1.3.9, 1.2.6),\n$request_time\n(1.3.9, 1.2.6),\n$pipe\n(1.3.12, 1.2.7),\n$request_length\n(1.3.12, 1.2.7),\n$time_iso8601\n(1.3.12, 1.2.7),\nand\n$time_local\n(1.3.12, 1.2.7)\nare also available as common variables.
\n
Header lines sent to a client have the prefix\n“sent_http_”, for example,\n$sent_http_content_range.
The configuration always includes the predefined\n“combined” format:
log_format combined '$remote_addr - $remote_user [$time_local] '\n '"$request" $status $body_bytes_sent '\n '"$http_referer" "$http_user_agent"';\nmax=N [inactive=time] [min_uses=N] [valid=time]
off
Defines a cache that stores the file descriptors of frequently used logs\nwhose names contain variables.\nThe directive has the following parameters:
\n\nmax
sets the maximum number of descriptors in a cache;\nif the cache becomes full the least recently used (LRU)\ndescriptors are closed
inactive
sets the time after which the cached descriptor is closed\nif there were no access during this time;\nby default, 10 seconds
min_uses
sets the minimum number of file uses during the time\ndefined by the inactive parameter\nto let the descriptor stay open in a cache;\nby default, 1
valid
sets the time after which it should be checked that the file\nstill exists with the same name; by default, 60 seconds
off
disables caching
Usage example:
\n\nopen_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;\nstring $variable {...}
Creates a new variable whose value\ndepends on values of one or more of the source variables\nspecified in the first parameter.
\n\n\n\n\nBefore version 0.9.0 only a single variable could be\nspecified in the first parameter.
\n\nSince variables are evaluated only when they are used, the mere declaration\neven of a large number of “
\nmap” variables\ndoes not add any extra costs to request processing.
Parameters inside the map block specify a mapping\nbetween source and resulting values.
Source values are specified as strings or regular expressions (0.9.6).
\n\nStrings are matched ignoring the case.
\n\nA regular expression should either start from the “~”\nsymbol for a case-sensitive matching, or from the “~*”\nsymbols (1.0.4) for case-insensitive matching.\nA regular expression can contain named and positional captures\nthat can later be used in other directives along with the\nresulting variable.
If a source value matches one of the names of special parameters\ndescribed below, it should be prefixed with the “\\” symbol.
The resulting value can contain text,\nvariable (0.9.0), and their combination (1.11.0).
\n\nThe following special parameters are also supported:
\n\ndefault value
sets the resulting value if the source value matches none\nof the specified variants.\nWhen default is not specified, the default\nresulting value will be an empty string.
hostnames
indicates that source values can be hostnames with a prefix or suffix mask:
\n\n*.example.com 1;\nexample.* 1;\nThe following two records
\n\nexample.com 1;\n*.example.com 1;\ncan be combined:
\n\n.example.com 1;\nThis parameter should be specified before the list of values.
include file
includes a file with values.\nThere can be several inclusions.
volatile
indicates that the variable is not cacheable (1.11.7).
If the source value matches more than one of the specified variants,\ne.g. both a mask and a regular expression match, the first matching\nvariant will be chosen, in the following order of priority:
\n\n*.example.com”mail.*”size
Sets the bucket size for the map variables hash tables.\nDefault value depends on the processor’s cache line size.\nThe details of setting up hash tables are provided in a separate\ndocument.
size
Sets the maximum size of the map variables\nhash tables.\nThe details of setting up hash tables are provided in a separate\ndocument.
address [transparent] | off
Makes outgoing connections to a memcached server originate\nfrom the specified local IP address with an optional port (1.11.2).\nParameter value can contain variables (1.3.12).\nThe special value off (1.3.12) cancels the effect\nof the memcached_bind directive\ninherited from the previous configuration level, which allows the\nsystem to auto-assign the local IP address and port.
The transparent parameter (1.11.0) allows\noutgoing connections to a memcached server originate\nfrom a non-local IP address,\nfor example, from a real IP address of a client:
memcached_bind $remote_addr transparent;\nIn order for this parameter to work,\nit is usually necessary to run nginx worker processes with the\nsuperuser privileges.\nOn Linux it is not required (1.13.8) as if\nthe transparent parameter is specified, worker processes\ninherit the CAP_NET_RAW capability from the master process.\nIt is also necessary to configure kernel routing table\nto intercept network traffic from the memcached server.
size
Sets the size of the buffer used for reading the response\nreceived from the memcached server.\nThe response is passed to the client synchronously, as soon as it is received.
time
Defines a timeout for establishing a connection with a memcached server.\nIt should be noted that this timeout cannot usually exceed 75 seconds.
\n" @@ -4261,9 +5098,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`flag`*" ], + "syntax_html": [ + "flag
Enables the test for the flag presence in the memcached\nserver response and sets the “Content-Encoding”\nresponse header field to “gzip”\nif the flag is set.
error | timeout | invalid_response | not_found | off …
Specifies in which cases a request should be passed to the next server:
\n\nerror
an error occurred while establishing a connection with the\nserver, passing a request to it, or reading the response header;
timeout
a timeout has occurred while establishing a connection with the\nserver, passing a request to it, or reading the response header;
invalid_response
a server returned an empty or invalid response;
not_found
a response was not found on the server;
off
disables passing a request to the next server.
One should bear in mind that passing a request to the next server is\nonly possible if nothing has been sent to a client yet.\nThat is, if an error or timeout occurs in the middle of the\ntransferring of a response, fixing this is impossible.
\n\nThe directive also defines what is considered an\nunsuccessful attempt of communication with a server.\nThe cases of error, timeout and\ninvalid_response are always considered unsuccessful attempts,\neven if they are not specified in the directive.\nThe case of not_found\nis never considered an unsuccessful attempt.
Passing a request to the next server can be limited by\nthe number of tries\nand by time.
\n" @@ -4291,9 +5134,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Limits the time during which a request can be passed to the\nnext server.\nThe 0 value turns off this limitation.
number
Limits the number of possible tries for passing a request to the\nnext server.\nThe 0 value turns off this limitation.
address
Sets the memcached server address.\nThe address can be specified as a domain name or IP address,\nand a port:
\n\nmemcached_pass localhost:11211;\nor as a UNIX-domain socket path:
\n\nmemcached_pass unix:/tmp/memcached.socket;\nIf a domain name resolves to several addresses, all of them will be\nused in a round-robin fashion.\nIn addition, an address can be specified as a\nserver group.
\n" @@ -4335,9 +5187,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Defines a timeout for reading a response from the memcached server.\nThe timeout is set only between two successive read operations,\nnot for the transmission of the whole response.\nIf the memcached server does not transmit anything within this time,\nthe connection is closed.
\n" @@ -4350,9 +5205,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Sets a timeout for transmitting a request to the memcached server.\nThe timeout is set only between two successive write operations,\nnot for the transmission of the whole request.\nIf the memcached server does not receive anything within this time,\nthe connection is closed.
\n" @@ -4365,9 +5223,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Configures the “TCP keepalive” behavior\nfor outgoing connections to a memcached server.\nBy default, the operating system’s settings are in effect for the socket.\nIf the directive is set to the value “on”, the\nSO_KEEPALIVE socket option is turned on for the socket.
uri | off
Sets the URI to which an original request will be mirrored.\nSeveral mirrors can be specified on the same configuration level.
\n" @@ -4401,9 +5265,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Indicates whether the client request body is mirrored.\nWhen enabled, the client request body will be read\nprior to creating mirror subrequests.\nIn this case, unbuffered client request body proxying\nset by the\nproxy_request_buffering,\nfastcgi_request_buffering,\nscgi_request_buffering,\nand\nuwsgi_request_buffering\ndirectives will be disabled.
location / {\n mirror /mirror;\n mirror_request_body off;\n proxy_pass http://backend;\n}\n\nlocation = /mirror {\n internal;\n proxy_pass http://log_backend;\n proxy_pass_request_body off;\n proxy_set_header Content-Length "";\n proxy_set_header X-Original-URI $request_uri;\n}\nsize
Sets the initial size of the buffer used for\nprocessing MP4 files.
size
During metadata processing, a larger buffer may become necessary.\nIts size cannot exceed the specified size,\nor else nginx will return the\n500 (Internal Server Error) server error,\nand log the following message:
"/some/movie/file.mp4" mp4 moov atom is too large:\n12583268, you may want to increase mp4_max_buffer_size\non | off | factor
Limits the rate of response transmission to a client.\nThe rate is limited based on the average bitrate of the\nMP4 file served.\nTo calculate the rate, the bitrate is multiplied by the specified\nfactor.\nThe special value “on” corresponds to the factor of 1.1.\nThe special value “off” disables rate limiting.\nThe limit is set per a request, and so if a client simultaneously opens\ntwo connections, the overall rate will be twice as much\nas the specified limit.
\n\n" @@ -4480,9 +5359,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "This directive is available as part of our\ncommercial subscription.
\n
time
Sets the initial amount of media data (measured in playback time)\nafter which the further transmission of the response to a client\nwill be rate limited.
\n\n\n\n" @@ -4495,9 +5377,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "This directive is available as part of our\ncommercial subscription.
\n
on | off
Forces output video to always start with a key video frame.\nIf the start argument does not point to a key frame,\ninitial frames are hidden using an mp4 edit list.\nEdit lists are supported by major players and browsers such as\nChrome, Safari, QuickTime and ffmpeg,\npartially supported by Firefox.
module::function|‘sub { … }’
Sets a Perl handler for the given location.
\n" @@ -4528,9 +5416,12 @@ "contexts": [ "http" ], - "syntax": [ + "syntax_md": [ "*`path`*" ], + "syntax_html": [ + "path
Sets an additional path for Perl modules.
\n" @@ -4541,9 +5432,12 @@ "contexts": [ "http" ], - "syntax": [ + "syntax_md": [ "*`module`*" ], + "syntax_html": [ + "module
Defines the name of a module that will be loaded during each\nreconfiguration.\nSeveral perl_require directives can be present.
$variable module::function|‘sub { … }’
Installs a Perl handler for the specified variable.
\n" @@ -4575,9 +5472,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`address`* [`transparent`] | `off`" ], + "syntax_html": [ + "address [transparent] | off
Makes outgoing connections to a proxied server originate\nfrom the specified local IP address with an optional port (1.11.2).\nParameter value can contain variables (1.3.12).\nThe special value off (1.3.12) cancels the effect\nof the proxy_bind directive\ninherited from the previous configuration level, which allows the\nsystem to auto-assign the local IP address and port.
The transparent parameter (1.11.0) allows\noutgoing connections to a proxied server originate\nfrom a non-local IP address,\nfor example, from a real IP address of a client:
proxy_bind $remote_addr transparent;\nIn order for this parameter to work,\nit is usually necessary to run nginx worker processes with the\nsuperuser privileges.\nOn Linux it is not required (1.13.8) as if\nthe transparent parameter is specified, worker processes\ninherit the CAP_NET_RAW capability from the master process.\nIt is also necessary to configure kernel routing table\nto intercept network traffic from the proxied server.
size
Sets the size of the buffer used for reading the first part\nof the response received from the proxied server.\nThis part usually contains a small response header.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.\nIt can be made smaller, however.
on | off
Enables or disables buffering of responses from the proxied server.
\n\nWhen buffering is enabled, nginx receives a response from the proxied server\nas soon as possible, saving it into the buffers set by the\nproxy_buffer_size and proxy_buffers directives.\nIf the whole response does not fit into memory, a part of it can be saved\nto a temporary file on the disk.\nWriting to temporary files is controlled by the\nproxy_max_temp_file_size and\nproxy_temp_file_write_size directives.
When buffering is disabled, the response is passed to a client synchronously,\nimmediately as it is received.\nnginx will not try to read the whole response from the proxied server.\nThe maximum size of the data that nginx can receive from the server\nat a time is set by the proxy_buffer_size directive.
Buffering can also be enabled or disabled by passing\n“yes” or “no” in the\n“X-Accel-Buffering” response header field.\nThis capability can be disabled using the\nproxy_ignore_headers directive.
number size
Sets the number and size of the\nbuffers used for reading a response from the proxied server,\nfor a single connection.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.
size
When buffering of responses from the proxied\nserver is enabled, limits the total size of buffers that\ncan be busy sending a response to the client while the response is not\nyet fully read.\nIn the meantime, the rest of the buffers can be used for reading the response\nand, if needed, buffering part of the response to a temporary file.\nBy default, size is limited by the size of two buffers set by the\nproxy_buffer_size and proxy_buffers directives.
zone | off
Defines a shared memory zone used for caching.\nThe same zone can be used in several places.\nParameter value can contain variables (1.7.9).\nThe off parameter disables caching inherited\nfrom the previous configuration level.
on | off
Allows starting a background subrequest\nto update an expired cache item,\nwhile a stale cached response is returned to the client.\nNote that it is necessary to\nallow\nthe usage of a stale cached response when it is being updated.
\n" @@ -4680,9 +5598,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`string`* ..." ], + "syntax_html": [ + "string …
Defines conditions under which the response will not be taken from a cache.\nIf at least one value of the string parameters is not empty and is not\nequal to “0” then the response will not be taken from the cache:
\n\nproxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;\nproxy_cache_bypass $http_pragma $http_authorization;\nCan be used along with the proxy_no_cache directive.
on | off
Enables or disables the conversion of the “HEAD” method\nto “GET” for caching.\nWhen the conversion is disabled, the\ncache key should be configured\nto include the $request_method.
string
Defines a key for caching, for example
\n\nproxy_cache_key "$host$request_uri $cookie_user";\nBy default, the directive’s value is close to the string
\n\nproxy_cache_key $scheme$proxy_host$uri$is_args$args;\non | off
When enabled, only one request at a time will be allowed to populate\na new cache element identified according to the proxy_cache_key\ndirective by passing a request to a proxied server.\nOther requests of the same cache element will either wait\nfor a response to appear in the cache or the cache lock for\nthis element to be released, up to the time set by the\nproxy_cache_lock_timeout directive.
time
If the last request passed to the proxied server\nfor populating a new cache element\nhas not completed for the specified time,\none more request may be passed to the proxied server.
time
Sets a timeout for proxy_cache_lock.\nWhen the time expires,\nthe request will be passed to the proxied server,\nhowever, the response will not be cached.
\n\n" @@ -4770,9 +5706,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "Before 1.7.8, the response could be cached.
\n
number
Sets an offset in bytes for byte-range requests.\nIf the range is beyond the offset,\nthe range request will be passed to the proxied server\nand the response will not be cached.
\n" @@ -4785,9 +5724,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`GET` | `HEAD` | `POST` ..." ], + "syntax_html": [ + "GET | HEAD | POST …
If the client request method is listed in this directive then\nthe response will be cached.\n“GET” and “HEAD” methods are always\nadded to the list, though it is recommended to specify them explicitly.\nSee also the proxy_no_cache directive.
number
Sets the number of requests after which the response\nwill be cached.
path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [min_free=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time]
Sets the path and other parameters of a cache.\nCache data are stored in files.\nThe file name in a cache is a result of\napplying the MD5 function to the\ncache key.\nThe levels parameter defines hierarchy levels of a cache:\nfrom 1 to 3, each level accepts values 1 or 2.\nFor example, in the following configuration
proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;\nfile names in a cache will look like this:
\n\n/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c\nA cached response is first written to a temporary file,\nand then the file is renamed.\nStarting from version 0.8.9, temporary files and the cache can be put on\ndifferent file systems.\nHowever, be aware that in this case a file is copied\nacross two file systems instead of the cheap renaming operation.\nIt is thus recommended that for any given location both cache and a directory\nholding temporary files\nare put on the same file system.\nThe directory for temporary files is set based on\nthe use_temp_path parameter (1.7.10).\nIf this parameter is omitted or set to the value on,\nthe directory set by the proxy_temp_path directive\nfor the given location will be used.\nIf the value is set to off,\ntemporary files will be put directly in the cache directory.
In addition, all active keys and information about data are stored\nin a shared memory zone, whose name and size\nare configured by the keys_zone parameter.\nOne megabyte zone can store about 8 thousand keys.
\n\n\nAs part of\ncommercial subscription,\nthe shared memory zone also stores extended\ncache information,\nthus, it is required to specify a larger zone size for the same number of keys.\nFor example,\none megabyte zone can store about 4 thousand keys.
\n
Cached data that are not accessed during the time specified by the\ninactive parameter get removed from the cache\nregardless of their freshness.\nBy default, inactive is set to 10 minutes.
The special “cache manager” process monitors the maximum cache size set\nby the max_size parameter,\nand the minimum amount of free space set\nby the min_free (1.19.1) parameter\non the file system with cache.\nWhen the size is exceeded or there is not enough free space,\nit removes the least recently used data.\nThe data is removed in iterations configured by\nmanager_files,\nmanager_threshold, and\nmanager_sleep parameters (1.11.5).\nDuring one iteration no more than manager_files items\nare deleted (by default, 100).\nThe duration of one iteration is limited by the\nmanager_threshold parameter (by default, 200 milliseconds).\nBetween iterations, a pause configured by the manager_sleep\nparameter (by default, 50 milliseconds) is made.
A minute after the start the special “cache loader” process is activated.\nIt loads information about previously cached data stored on file system\ninto a cache zone.\nThe loading is also done in iterations.\nDuring one iteration no more than loader_files items\nare loaded (by default, 100).\nBesides, the duration of one iteration is limited by the\nloader_threshold parameter (by default, 200 milliseconds).\nBetween iterations, a pause configured by the loader_sleep\nparameter (by default, 50 milliseconds) is made.
Additionally,\nthe following parameters are available as part of our\ncommercial subscription:
\n\npurger=on|off
Instructs whether cache entries that match a\nwildcard key\nwill be removed from the disk by the cache purger (1.7.12).\nSetting the parameter to on\n(default is off)\nwill activate the “cache purger” process that\npermanently iterates through all cache entries\nand deletes the entries that match the wildcard key.
purger_files=number
Sets the number of items that will be scanned during one iteration (1.7.12).\nBy default, purger_files is set to 10.
purger_threshold=number
Sets the duration of one iteration (1.7.12).\nBy default, purger_threshold is set to 50 milliseconds.
purger_sleep=number
Sets a pause between iterations (1.7.12).\nBy default, purger_sleep is set to 50 milliseconds.
\n\n" @@ -4828,9 +5776,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "string ..." ], + "syntax_html": [ + "In versions 1.7.3, 1.7.7, and 1.11.10 cache header format has been changed.\nPreviously cached responses will be considered invalid\nafter upgrading to a newer nginx version.
\n
string …
\n" + ], "isBlock": false, "description_md": "Defines conditions under which the request will be considered a cache\npurge request.\nIf at least one value of the string parameters is not empty and is not equal\nto “0” then the cache entry with a corresponding\n[cache key](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_key) is removed.\nThe result of successful operation is indicated by returning\nthe 204 (No Content) response.\n\nIf the [cache key](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_key) of a purge request ends\nwith an asterisk (“`*`”), all cache entries matching the\nwildcard key will be removed from the cache.\nHowever, these entries will remain on the disk until they are deleted\nfor either [inactivity](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path),\nor processed by the [cache purger](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#purger) (1.7.12),\nor a client attempts to access them.\n\nExample configuration:\n```\nproxy_cache_path /data/nginx/cache keys_zone=cache_zone:10m;\n\nmap $request_method $purge_method {\n PURGE 1;\n default 0;\n}\n\nserver {\n ...\n location / {\n proxy_pass http://backend;\n proxy_cache cache_zone;\n proxy_cache_key $uri;\n proxy_cache_purge $purge_method;\n }\n}\n```\n> This functionality is available as part of our\n> [commercial subscription](https://nginx.com/products/).", "description_html": "Defines conditions under which the request will be considered a cache\npurge request.\nIf at least one value of the string parameters is not empty and is not equal\nto “0” then the cache entry with a corresponding\ncache key is removed.\nThe result of successful operation is indicated by returning\nthe 204 (No Content) response.
\n\nIf the cache key of a purge request ends\nwith an asterisk (“*”), all cache entries matching the\nwildcard key will be removed from the cache.\nHowever, these entries will remain on the disk until they are deleted\nfor either inactivity,\nor processed by the cache purger (1.7.12),\nor a client attempts to access them.
Example configuration:
\n\nproxy_cache_path /data/nginx/cache keys_zone=cache_zone:10m;\n\nmap $request_method $purge_method {\n PURGE 1;\n default 0;\n}\n\nserver {\n ...\n location / {\n proxy_pass http://backend;\n proxy_cache cache_zone;\n proxy_cache_key $uri;\n proxy_cache_purge $purge_method;\n }\n}\n\n\n" @@ -4843,9 +5794,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "This functionality is available as part of our\ncommercial subscription.
\n
on | off
Enables revalidation of expired cache items using conditional requests with\nthe “If-Modified-Since” and “If-None-Match”\nheader fields.
\n" @@ -4858,9 +5812,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`error` | `timeout` | `invalid_header` | `updating` | `http_500` | `http_502` | `http_503` | `http_504` | `http_403` | `http_404` | `http_429` | `off` ..." ], + "syntax_html": [ + "error | timeout | invalid_header | updating | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | off …
Determines in which cases a stale cached response can be used\nduring communication with the proxied server.\nThe directive’s parameters match the parameters of the\nproxy_next_upstream directive.
The error parameter also permits\nusing a stale cached response if a proxied server to process a request\ncannot be selected.
Additionally, the updating parameter permits\nusing a stale cached response if it is currently being updated.\nThis allows minimizing the number of accesses to proxied servers\nwhen updating cached data.
Using a stale cached response\ncan also be enabled directly in the response header\nfor a specified number of seconds after the response became stale (1.11.10).\nThis has lower priority than using the directive parameters.
\n\nTo minimize the number of accesses to proxied servers when\npopulating a new cache element, the proxy_cache_lock\ndirective can be used.
[code …] time
Sets caching time for different response codes.\nFor example, the following directives
\n\nproxy_cache_valid 200 302 10m;\nproxy_cache_valid 404 1m;\nset 10 minutes of caching for responses with codes 200 and 302\nand 1 minute for responses with code 404.
\n\nIf only caching time is specified
proxy_cache_valid 5m;\nthen only 200, 301, and 302 responses are cached.
\n\nIn addition, the any parameter can be specified\nto cache any responses:
proxy_cache_valid 200 302 10m;\nproxy_cache_valid 301 1h;\nproxy_cache_valid any 1m;\nParameters of caching can also be set directly\nin the response header.\nThis has higher priority than setting of caching time using the directive.
\n\n@ prefix, it sets an absolute\ntime in seconds since Epoch, up to which the response may be cached.*”, such a\nresponse will not be cached (1.7.7).\nIf the header includes the “Vary” field\nwith another value, such a response will be cached\ntaking into account the corresponding request header fields (1.7.7).Processing of one or more of these response header fields can be disabled\nusing the proxy_ignore_headers directive.
time
Defines a timeout for establishing a connection with a proxied server.\nIt should be noted that this timeout cannot usually exceed 75 seconds.
\n" @@ -4903,10 +5866,14 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`off`", "*`domain`* *`replacement`*" ], + "syntax_html": [ + "off
domain replacement
Sets a text that should be changed in the domain\nattribute of the “Set-Cookie” header fields of a\nproxied server response.\nSuppose a proxied server returned the “Set-Cookie”\nheader field with the attribute\n“domain=localhost”.\nThe directive
proxy_cookie_domain localhost example.org;\nwill rewrite this attribute to\n“domain=example.org”.
A dot at the beginning of the domain and\nreplacement strings and the domain\nattribute is ignored.\nMatching is case-insensitive.
The domain and replacement strings\ncan contain variables:
proxy_cookie_domain www.$host $host;\nThe directive can also be specified using regular expressions.\nIn this case, domain should start from\nthe “~” symbol.\nA regular expression can contain named and positional captures,\nand replacement can reference them:
proxy_cookie_domain ~\\.(?P<sl_domain>[-0-9a-z]+\\.[a-z]+)$ $sl_domain;\nSeveral proxy_cookie_domain directives\ncan be specified on the same level:
proxy_cookie_domain localhost example.org;\nproxy_cookie_domain ~\\.([a-z]+\\.[a-z]+)$ $1;\nIf several directives can be applied to the cookie,\nthe first matching directive will be chosen.
\n\nThe off parameter cancels the effect\nof the proxy_cookie_domain directives\ninherited from the previous configuration level.
off | cookie [flag …]
Sets one or more flags for the cookie.\nThe cookie can contain text, variables, and their combinations.\nThe flag\ncan contain text, variables, and their combinations (1.19.8).\nThe\nsecure,\nhttponly,\nsamesite=strict,\nsamesite=lax,\nsamesite=none\nparameters add the corresponding flags.\nThe\nnosecure,\nnohttponly,\nnosamesite\nparameters remove the corresponding flags.
The cookie can also be specified using regular expressions.\nIn this case, cookie should start from\nthe “~” symbol.
Several proxy_cookie_flags directives\ncan be specified on the same configuration level:
proxy_cookie_flags one httponly;\nproxy_cookie_flags ~ nosecure samesite=strict;\nIf several directives can be applied to the cookie,\nthe first matching directive will be chosen.\nIn the example, the httponly flag\nis added to the cookie one,\nfor all other cookies\nthe samesite=strict flag is added and\nthe secure flag is deleted.
The off parameter cancels the effect\nof the proxy_cookie_flags directives\ninherited from the previous configuration level.
off
path replacement
Sets a text that should be changed in the path\nattribute of the “Set-Cookie” header fields of a\nproxied server response.\nSuppose a proxied server returned the “Set-Cookie”\nheader field with the attribute\n“path=/two/some/uri/”.\nThe directive
proxy_cookie_path /two/ /;\nwill rewrite this attribute to\n“path=/some/uri/”.
The path and replacement strings\ncan contain variables:
proxy_cookie_path $uri /some$uri;\nThe directive can also be specified using regular expressions.\nIn this case, path should either start from\nthe “~” symbol for a case-sensitive matching,\nor from the “~*” symbols for case-insensitive\nmatching.\nThe regular expression can contain named and positional captures,\nand replacement can reference them:
proxy_cookie_path ~*^/user/([^/]+) /u/$1;\nSeveral proxy_cookie_path directives\ncan be specified on the same level:
proxy_cookie_path /one/ /;\nproxy_cookie_path / /two/;\nIf several directives can be applied to the cookie,\nthe first matching directive will be chosen.
\n\nThe off parameter cancels the effect\nof the proxy_cookie_path directives\ninherited from the previous configuration level.
on | off
Enables byte-range support\nfor both cached and uncached responses from the proxied server\nregardless of the “Accept-Ranges” field in these responses.
\n" @@ -4965,9 +5942,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
Sets the bucket size for hash tables\nused by the proxy_hide_header and proxy_set_header\ndirectives.\nThe details of setting up hash tables are provided in a separate\ndocument.
size
Sets the maximum size of hash tables\nused by the proxy_hide_header and proxy_set_header\ndirectives.\nThe details of setting up hash tables are provided in a separate\ndocument.
field
By default,\nnginx does not pass the header fields “Date”,\n“Server”, “X-Pad”, and\n“X-Accel-…” from the response of a proxied\nserver to a client.\nThe proxy_hide_header directive sets additional fields\nthat will not be passed.\nIf, on the contrary, the passing of fields needs to be permitted,\nthe proxy_pass_header directive can be used.
1.0 | 1.1
Sets the HTTP protocol version for proxying.\nBy default, version 1.0 is used.\nVersion 1.1 is recommended for use with\nkeepalive\nconnections and\nNTLM authentication.
on | off
Determines whether the connection with a proxied server should be\nclosed when a client closes the connection without waiting\nfor a response.
\n" @@ -5040,9 +6032,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`field`* ..." ], + "syntax_html": [ + "field …
Disables processing of certain response header fields from the proxied server.\nThe following fields can be ignored: “X-Accel-Redirect”,\n“X-Accel-Expires”, “X-Accel-Limit-Rate” (1.1.6),\n“X-Accel-Buffering” (1.1.6),\n“X-Accel-Charset” (1.1.6), “Expires”,\n“Cache-Control”, “Set-Cookie” (0.8.44),\nand “Vary” (1.7.7).
\n\nIf not disabled, processing of these header fields has the following\neffect:
\n\ncharset\nof a response.on | off
Determines whether proxied responses with codes greater than or equal\nto 300 should be passed to a client\nor be intercepted and redirected to nginx for processing\nwith the error_page directive.
rate
Limits the speed of reading the response from the proxied server.\nThe rate is specified in bytes per second.\nThe zero value disables rate limiting.\nThe limit is set per a request, and so if nginx simultaneously opens\ntwo connections to the proxied server,\nthe overall rate will be twice as much as the specified limit.\nThe limitation works only if\nbuffering of responses from the proxied\nserver is enabled.
size
When buffering of responses from the proxied\nserver is enabled, and the whole response does not fit into the buffers\nset by the proxy_buffer_size and proxy_buffers\ndirectives, a part of the response can be saved to a temporary file.\nThis directive sets the maximum size of the temporary file.\nThe size of data written to the temporary file at a time is set\nby the proxy_temp_file_write_size directive.
The zero value disables buffering of responses to temporary files.
\n\n\n\n" @@ -5100,9 +6104,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`method`*" ], + "syntax_html": [ + "This restriction does not apply to responses\nthat will be cached\nor stored on disk.
\n
method
Specifies the HTTP method to use in requests forwarded\nto the proxied server instead of the method from the client request.\nParameter value can contain variables (1.11.6).
error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_403 | http_404 | http_429 | non_idempotent | off …
Specifies in which cases a request should be passed to the next server:
\n\nerror
an error occurred while establishing a connection with the\nserver, passing a request to it, or reading the response header;
timeout
a timeout has occurred while establishing a connection with the\nserver, passing a request to it, or reading the response header;
invalid_header
a server returned an empty or invalid response;
http_500
a server returned a response with the code 500;
http_502
a server returned a response with the code 502;
http_503
a server returned a response with the code 503;
http_504
a server returned a response with the code 504;
http_403
a server returned a response with the code 403;
http_404
a server returned a response with the code 404;
http_429
a server returned a response with the code 429 (1.11.13);
non_idempotent
normally, requests with a\nnon-idempotent\nmethod\n(POST, LOCK, PATCH)\nare not passed to the next server\nif a request has been sent to an upstream server (1.9.13);\nenabling this option explicitly allows retrying such requests;
off
disables passing a request to the next server.
One should bear in mind that passing a request to the next server is\nonly possible if nothing has been sent to a client yet.\nThat is, if an error or timeout occurs in the middle of the\ntransferring of a response, fixing this is impossible.
\n\nThe directive also defines what is considered an\nunsuccessful attempt of communication with a server.\nThe cases of error, timeout and\ninvalid_header are always considered unsuccessful attempts,\neven if they are not specified in the directive.\nThe cases of http_500, http_502,\nhttp_503, http_504,\nand http_429 are\nconsidered unsuccessful attempts only if they are specified in the directive.\nThe cases of http_403 and http_404\nare never considered unsuccessful attempts.
Passing a request to the next server can be limited by\nthe number of tries\nand by time.
\n" @@ -5130,9 +6140,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Limits the time during which a request can be passed to the\nnext server.\nThe 0 value turns off this limitation.
number
Limits the number of possible tries for passing a request to the\nnext server.\nThe 0 value turns off this limitation.
string …
Defines conditions under which the response will not be saved to a cache.\nIf at least one value of the string parameters is not empty and is not\nequal to “0” then the response will not be saved:
\n\nproxy_no_cache $cookie_nocache $arg_nocache$arg_comment;\nproxy_no_cache $http_pragma $http_authorization;\nCan be used along with the proxy_cache_bypass directive.
URL
Sets the protocol and address of a proxied server and an optional URI\nto which a location should be mapped.\nAs a protocol, “http” or “https”\ncan be specified.\nThe address can be specified as a domain name or IP address,\nand an optional port:
proxy_pass http://localhost:8000/uri/;\nor as a UNIX-domain socket path specified after the word\n“unix” and enclosed in colons:
proxy_pass http://unix:/tmp/backend.socket:/uri/;\nIf a domain name resolves to several addresses, all of them will be\nused in a round-robin fashion.\nIn addition, an address can be specified as a\nserver group.
\n\nParameter value can contain variables.\nIn this case, if an address is specified as a domain name,\nthe name is searched among the described server groups,\nand, if not found, is determined using a\nresolver.
A request URI is passed to the server as follows:
\n\nproxy_pass directive is specified with a URI,\nthen when a request is passed to the server, the part of a\nnormalized\nrequest URI matching the location is replaced by a URI\nspecified in the directive:\n\n\nlocation /name/ {\n proxy_pass http://127.0.0.1/remote/;\n}\nproxy_pass is specified without a URI,\nthe request URI is passed to the server in the same form\nas sent by a client when the original request is processed,\nor the full normalized request URI is passed\nwhen processing the changed URI:\n\n\nlocation /some/path/ {\n proxy_pass http://127.0.0.1;\n}\nproxy_pass is specified without a URI,\n> the original request URI might be passed\n> instead of the changed URI in some cases.In some cases, the part of a request URI to be replaced cannot be determined:
\n\nWhen location is specified using a regular expression,\nand also inside named locations.
\n\nIn these cases,\nproxy_pass should be specified without a URI.
When the URI is changed inside a proxied location using the\nrewrite directive,\nand this same configuration will be used to process a request\n(break):
location /name/ {\n rewrite /name/([^/]+) /users?name=$1 break;\n proxy_pass http://127.0.0.1;\n}\nIn this case, the URI specified in the directive is ignored and\nthe full changed request URI is passed to the server.
When variables are used in proxy_pass:
location /name/ {\n proxy_pass http://127.0.0.1$request_uri;\n}\nIn this case, if URI is specified in the directive,\nit is passed to the server as is,\nreplacing the original request URI.
WebSocket proxying requires special\nconfiguration and is supported since version 1.3.13.
\n" @@ -5190,9 +6212,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`field`*" ], + "syntax_html": [ + "field
Permits passing otherwise disabled header\nfields from a proxied server to a client.
\n" @@ -5205,9 +6230,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Indicates whether the original request body is passed\nto the proxied server.
\n\nlocation /x-accel-redirect-here/ {\n proxy_method GET;\n proxy_pass_request_body off;\n proxy_set_header Content-Length "";\n\n proxy_pass ...\n}\nSee also the proxy_set_header and\nproxy_pass_request_headers directives.
on | off
Indicates whether the header fields of the original request are passed\nto the proxied server.
\n\nlocation /x-accel-redirect-here/ {\n proxy_method GET;\n proxy_pass_request_headers off;\n proxy_pass_request_body off;\n\n proxy_pass ...\n}\nSee also the proxy_set_header and\nproxy_pass_request_body directives.
time
Defines a timeout for reading a response from the proxied server.\nThe timeout is set only between two successive read operations,\nnot for the transmission of the whole response.\nIf the proxied server does not transmit anything within this time,\nthe connection is closed.
\n" @@ -5250,11 +6284,16 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`default`", "`off`", "*`redirect`* *`replacement`*" ], + "syntax_html": [ + "default
off
redirect replacement
Sets the text that should be changed in the “Location”\nand “Refresh” header fields of a proxied server response.\nSuppose a proxied server returned the header field\n“Location: http://localhost:8000/two/some/uri/”.\nThe directive
proxy_redirect http://localhost:8000/two/ http://frontend/one/;\nwill rewrite this string to\n“Location: http://frontend/one/some/uri/”.
A server name may be omitted in the replacement string:
proxy_redirect http://localhost:8000/two/ /;\nthen the primary server’s name and port, if different from 80,\nwill be inserted.
\n\nThe default replacement specified by the default parameter\nuses the parameters of the\nlocation and\nproxy_pass directives.\nHence, the two configurations below are equivalent:
location /one/ {\n proxy_pass http://upstream:port/two/;\n proxy_redirect default;\nlocation /one/ {\n proxy_pass http://upstream:port/two/;\n proxy_redirect http://upstream:port/two/ /one/;\nThe default parameter is not permitted if\nproxy_pass is specified using variables.
A replacement string can contain variables:
proxy_redirect http://localhost:8000/ http://$host:$server_port/;\nA redirect can also contain (1.1.11) variables:
proxy_redirect http://$proxy_host:8000/ /;\nThe directive can be specified (1.1.11) using regular expressions.\nIn this case, redirect should either start with\nthe “~” symbol for a case-sensitive matching,\nor with the “~*” symbols for case-insensitive\nmatching.\nThe regular expression can contain named and positional captures,\nand replacement can reference them:
proxy_redirect ~^(http://[^:]+):\\d+(/.+)$ $1$2;\nproxy_redirect ~*/user/([^/]+)/(.+)$ http://$1.example.com/$2;\nSeveral proxy_redirect directives\ncan be specified on the same level:
proxy_redirect default;\nproxy_redirect http://localhost:8000/ /;\nproxy_redirect http://www.example.com/ /;\nIf several directives can be applied to\nthe header fields of a proxied server response,\nthe first matching directive will be chosen.
\n\nThe off parameter cancels the effect\nof the proxy_redirect directives\ninherited from the previous configuration level.
Using this directive, it is also possible to add host names to relative\nredirects issued by a proxied server:
\n\nproxy_redirect / /;\non | off
Enables or disables buffering of a client request body.
\n\nWhen buffering is enabled, the entire request body is\nread\nfrom the client before sending the request to a proxied server.
\n\nWhen buffering is disabled, the request body is sent to the proxied server\nimmediately as it is received.\nIn this case, the request cannot be passed to the\nnext server\nif nginx already started sending the request body.
\n\nWhen HTTP/1.1 chunked transfer encoding is used\nto send the original request body,\nthe request body will be buffered regardless of the directive value unless\nHTTP/1.1 is enabled for proxying.
\n" @@ -5282,9 +6324,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
If the directive is set to a non-zero value, nginx will try to\nminimize the number\nof send operations on outgoing connections to a proxied server by using either\nNOTE_LOWAT flag of the\nkqueue method,\nor the SO_SNDLOWAT socket option,\nwith the specified size.
This directive is ignored on Linux, Solaris, and Windows.
\n" @@ -5297,9 +6342,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Sets a timeout for transmitting a request to the proxied server.\nThe timeout is set only between two successive write operations,\nnot for the transmission of the whole request.\nIf the proxied server does not receive anything within this time,\nthe connection is closed.
\n" @@ -5312,9 +6360,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`value`*" ], + "syntax_html": [ + "value
Allows redefining the request body passed to the proxied server.\nThe value can contain text, variables, and their combination.
field value
Allows redefining or appending fields to the request header\npassed to the proxied server.\nThe value can contain text, variables, and their combinations.\nThese directives are inherited from the previous configuration level\nif and only if there are no proxy_set_header directives\ndefined on the current level.\nBy default, only two fields are redefined:
proxy_set_header Host $proxy_host;\nproxy_set_header Connection close;\nIf caching is enabled, the header fields\n“If-Modified-Since”,\n“If-Unmodified-Since”,\n“If-None-Match”,\n“If-Match”,\n“Range”,\nand\n“If-Range”\nfrom the original request are not passed to the proxied server.
\n\nAn unchanged “Host” request header field can be passed like this:
\n\nproxy_set_header Host $http_host;\nHowever, if this field is not present in a client request header then\nnothing will be passed.\nIn such a case it is better to use the $host variable—its\nvalue equals the server name in the “Host” request header\nfield or the primary server name if this field is not present:
proxy_set_header Host $host;\nIn addition, the server name can be passed together with the port of the\nproxied server:
\n\nproxy_set_header Host $host:$proxy_port;\nIf the value of a header field is an empty string then this\nfield will not be passed to a proxied server:
\n\nproxy_set_header Accept-Encoding "";\non | off
Configures the “TCP keepalive” behavior\nfor outgoing connections to a proxied server.\nBy default, the operating system’s settings are in effect for the socket.\nIf the directive is set to the value “on”, the\nSO_KEEPALIVE socket option is turned on for the socket.
file
Specifies a file with the certificate in the PEM format\nused for authentication to a proxied HTTPS server.
Since version 1.21.0, variables can be used in the file name.
file
Specifies a file with the secret key in the PEM format\nused for authentication to a proxied HTTPS server.
The value\nengine:name:id\ncan be specified instead of the file (1.7.9),\nwhich loads a secret key with a specified id\nfrom the OpenSSL engine name.
Since version 1.21.0, variables can be used in the file name.
ciphers
Specifies the enabled ciphers for requests to a proxied HTTPS server.\nThe ciphers are specified in the format understood by the OpenSSL library.
\n\nThe full list can be viewed using the\n“openssl ciphers” command.
name value
Sets arbitrary OpenSSL configuration\ncommands\nwhen establishing a connection with the proxied HTTPS server.
\n\n\n\n\nThe directive is supported when using OpenSSL 1.0.2 or higher.
\n
Several proxy_ssl_conf_command directives\ncan be specified on the same level.\nThese directives are inherited from the previous configuration level\nif and only if there are\nno proxy_ssl_conf_command directives\ndefined on the current level.
\n\n" @@ -5417,9 +6486,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "Note that configuring OpenSSL directly\nmight result in unexpected behavior.
\n
file
Specifies a file with revoked certificates (CRL)\nin the PEM format used to verify\nthe certificate of the proxied HTTPS server.
name
Allows overriding the server name used to\nverify\nthe certificate of the proxied HTTPS server and to be\npassed through SNI\nwhen establishing a connection with the proxied HTTPS server.
\n\nBy default, the host part of the proxy_pass URL is used.
file
Specifies a file with passphrases for\nsecret keys\nwhere each passphrase is specified on a separate line.\nPassphrases are tried in turn when loading the key.
[SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]
Enables the specified protocols for requests to a proxied HTTPS server.
\n\n\n\n" @@ -5477,9 +6558,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "The
\nTLSv1.3parameter is used by default\nsince 1.23.4.
on | off
Enables or disables passing of the server name through\nTLS Server Name Indication extension (SNI, RFC 6066)\nwhen establishing a connection with the proxied HTTPS server.
\n" @@ -5492,9 +6576,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Determines whether SSL sessions can be reused when working with\nthe proxied server.\nIf the errors\n“SSL3_GET_FINISHED:digest check failed”\nappear in the logs, try disabling session reuse.
file
Specifies a file with trusted CA certificates in the PEM format\nused to verify\nthe certificate of the proxied HTTPS server.
on | off
Enables or disables verification of the proxied HTTPS server certificate.
\n" @@ -5537,9 +6630,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
Sets the verification depth in the proxied HTTPS server certificates chain.
\n" @@ -5552,9 +6648,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off` | *`string`*" ], + "syntax_html": [ + "on | off | string
Enables saving of files to a disk.\nThe on parameter saves files with paths\ncorresponding to the directives\nalias or\nroot.\nThe off parameter disables saving of files.\nIn addition, the file name can be set explicitly using the\nstring with variables:
proxy_store /data/www$original_uri;\nThe modification time of files is set according to the received\n“Last-Modified” response header field.\nThe response is first written to a temporary file,\nand then the file is renamed.\nStarting from version 0.8.9, temporary files and the persistent store\ncan be put on different file systems.\nHowever, be aware that in this case a file is copied\nacross two file systems instead of the cheap renaming operation.\nIt is thus recommended that for any given location both saved files and a\ndirectory holding temporary files, set by the proxy_temp_path\ndirective, are put on the same file system.
This directive can be used to create local copies of static unchangeable\nfiles, e.g.:
\n\nlocation /images/ {\n root /data/www;\n error_page 404 = /fetch$uri;\n}\n\nlocation /fetch/ {\n internal;\n\n proxy_pass http://backend/;\n proxy_store on;\n proxy_store_access user:rw group:rw all:r;\n proxy_temp_path /data/temp;\n\n alias /data/www/;\n}\nor like this:
\n\nlocation /images/ {\n root /data/www;\n error_page 404 = @fetch;\n}\n\nlocation @fetch {\n internal;\n\n proxy_pass http://backend;\n proxy_store on;\n proxy_store_access user:rw group:rw all:r;\n proxy_temp_path /data/temp;\n\n root /data/www;\n}\nusers:permissions …
Sets access permissions for newly created files and directories, e.g.:
\n\nproxy_store_access user:rw group:rw all:r;\nIf any group or all access permissions\nare specified then user permissions may be omitted:
proxy_store_access group:rw all:r;\nsize
Limits the size of data written to a temporary file\nat a time, when buffering of responses from the proxied server\nto temporary files is enabled.\nBy default, size is limited by two buffers set by the\nproxy_buffer_size and proxy_buffers directives.\nThe maximum size of a temporary file is set by the\nproxy_max_temp_file_size directive.
path [level1 [level2 [level3]]]
Defines a directory for storing temporary files\nwith data received from proxied servers.\nUp to three-level subdirectory hierarchy can be used underneath the specified\ndirectory.\nFor example, in the following configuration
\n\nproxy_temp_path /spool/nginx/proxy_temp 1 2;\na temporary file might look like this:
\n\n/spool/nginx/proxy_temp/7/45/00000123457\nSee also the use_temp_path parameter of the\nproxy_cache_path directive.
on | off
Enables or disables module processing in a surrounding location.
\n" @@ -5637,9 +6748,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`address`* | *`CIDR`* | `unix:`" ], + "syntax_html": [ + "address | CIDR | unix:
Defines trusted addresses that are known to send correct\nreplacement addresses.\nIf the special value unix: is specified,\nall UNIX-domain sockets will be trusted.\nTrusted addresses may also be specified using a hostname (1.13.1).
\n\n" @@ -5652,9 +6766,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`field`* | `X-Real-IP` | `X-Forwarded-For` | `proxy_protocol`" ], + "syntax_html": [ + "IPv6 addresses are supported starting from versions 1.3.0 and 1.2.1.
\n
field | X-Real-IP | X-Forwarded-For | proxy_protocol
Defines the request header field\nwhose value will be used to replace the client address.
\n\nThe request header field value that contains an optional port\nis also used to replace the client port (1.11.0).\nThe address and port should be specified according to\nRFC 3986.
\n\nThe proxy_protocol parameter (1.5.12) changes\nthe client address to the one from the PROXY protocol header.\nThe PROXY protocol must be previously enabled by setting the\nproxy_protocol parameter\nin the listen directive.
on | off
If recursive search is disabled, the original client address that\nmatches one of the trusted addresses is replaced by the last\naddress sent in the request header field defined by the\nreal_ip_header directive.\nIf recursive search is enabled, the original client address that\nmatches one of the trusted addresses is replaced by the last\nnon-trusted address sent in the request header field.
size
Sets the bucket size for the valid referers hash tables.\nThe details of setting up hash tables are provided in a separate\ndocument.
\n" @@ -5701,9 +6824,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
Sets the maximum size of the valid referers hash tables.\nThe details of setting up hash tables are provided in a separate\ndocument.
none | blocked | server_names | string …
Specifies the “Referer” request header field values\nthat will cause the embedded $invalid_referer variable to\nbe set to an empty string.\nOtherwise, the variable will be set to “1”.\nSearch for a match is case-insensitive.
Parameters can be as follows:
\n\nnone
the “Referer” field is missing in the request header;
blocked
the “Referer” field is present in the request header,\nbut its value has been deleted by a firewall or proxy server;\nsuch values are strings that do not start with\n“http://” or “https://”;
server_names
the “Referer” request header field contains\none of the server names;
arbitrary string
\n\ndefines a server name and an optional URI prefix.\nA server name can have an “*” at the beginning or end.\nDuring the checking, the server’s port in the “Referer” field\nis ignored;
regular expression
\n\nthe first symbol should be a “~”.\nIt should be noted that an expression will be matched against\nthe text starting after the “http://”\nor “https://”.
Example:
\n\nvalid_referers none blocked server_names\n *.example.com example.* www.example.org/galleries/\n ~\\.google\\.;\n(condition) {...}
The specified condition is evaluated.\nIf true, this module directives specified inside the braces are\nexecuted, and the request is assigned the configuration inside the\nif directive.\nConfigurations inside the if directives are\ninherited from the previous configuration level.
A condition may be any of the following:
\n\n0”;\n> Before version 1.0.1, any string starting with “0”\n> was considered a false value.=” and “!=” operators;~” (for case-sensitive matching) and\n“~*” (for case-insensitive matching) operators.\nRegular expressions can contain captures that are made available for\nlater reuse in the $1..$9 variables.\nNegative operators “!~” and “!~*”\nare also available.\nIf a regular expression includes the “}”\nor “;” characters, the whole expressions should be enclosed\nin single or double quotes.-f” and\n“!-f” operators;-d” and\n“!-d” operators;-e” and “!-e” operators;-x”\nand “!-x” operators.Examples:
\n\nif ($http_user_agent ~ MSIE) {\n rewrite ^(.*)$ /msie/$1 break;\n}\n\nif ($http_cookie ~* "id=([^;]+)(?:;|$)") {\n set $id $1;\n}\n\nif ($request_method = POST) {\n return 405;\n}\n\nif ($slow) {\n limit_rate 10k;\n}\n\nif ($invalid_referer) {\n return 403;\n}\n\n\n" @@ -5765,11 +6900,16 @@ "location", "if" ], - "syntax": [ + "syntax_md": [ "*`code`* [*`text`*]", "*`code`* *`URL`*", "*`URL`*" ], + "syntax_html": [ + "A value of the
\n$invalid_refererembedded variable is set by the\nvalid_referersdirective.
code [text]
code URL
URL
Stops processing and returns the specified code to a client.\nThe non-standard code 444 closes a connection without sending\na response header.
Starting from version 0.8.42, it is possible to specify\neither a redirect URL (for codes 301, 302, 303, 307, and 308)\nor the response body text (for other codes).\nA response body text and redirect URL can contain variables.\nAs a special case, a redirect URL can be specified as a URI\nlocal to this server, in which case the full redirect URL\nis formed according to the request scheme ($scheme) and the\nserver_name_in_redirect and\nport_in_redirect directives.
In addition, a URL for temporary redirect with the code 302\ncan be specified as the sole parameter.\nSuch a parameter should start with the “http://”,\n“https://”, or “$scheme” string.\nA URL can contain variables.
\n\n\nOnly the following codes could be returned before version 0.7.51:\n204, 400, 402 — 406, 408, 410, 411, 413, 416, and 500 — 504.
\n\nThe code 307 was not treated as a redirect until versions 1.1.16 and 1.0.13.
\n\nThe code 308 was not treated as a redirect until version 1.13.0.
\n
See also the error_page directive.
regex replacement [flag]
If the specified regular expression matches a request URI, URI is changed\nas specified in the replacement string.\nThe rewrite directives are executed sequentially\nin order of their appearance in the configuration file.\nIt is possible to terminate further processing of the directives using flags.\nIf a replacement string starts with “http://”,\n“https://”, or “$scheme”,\nthe processing stops and the redirect is returned to a client.
An optional flag parameter can be one of:
last
stops processing the current set of\nngx_http_rewrite_module directives and starts\na search for a new location matching the changed URI;
break
stops processing the current set of\nngx_http_rewrite_module directives\nas with the break directive;
redirect
returns a temporary redirect with the 302 code;\nused if a replacement string does not start with\n“http://”, “https://”,\nor “$scheme”;
permanent
returns a permanent redirect with the 301 code.
The full redirect URL is formed according to the\nrequest scheme ($scheme) and the\nserver_name_in_redirect and\nport_in_redirect directives.
Example:
\n\nserver {\n ...\n rewrite ^(/download/.*)/media/(.*)\\..*$ $1/mp3/$2.mp3 last;\n rewrite ^(/download/.*)/audio/(.*)\\..*$ $1/mp3/$2.ra last;\n return 403;\n ...\n}\nBut if these directives are put inside the “/download/”\nlocation, the last flag should be replaced by\nbreak, or otherwise nginx will make 10 cycles and\nreturn the 500 error:
location /download/ {\n rewrite ^(/download/.*)/media/(.*)\\..*$ $1/mp3/$2.mp3 break;\n rewrite ^(/download/.*)/audio/(.*)\\..*$ $1/mp3/$2.ra break;\n return 403;\n}\nIf a replacement string includes the new request arguments,\nthe previous request arguments are appended after them.\nIf this is undesired, putting a question mark at the end of a replacement\nstring avoids having them appended, for example:
rewrite ^/users/(.*)$ /show?user=$1? last;\nIf a regular expression includes the “}”\nor “;” characters, the whole expressions should be enclosed\nin single or double quotes.
on | off
Enables or disables logging of ngx_http_rewrite_module\nmodule directives processing results\ninto the error_log at\nthe notice level.
$variable value
Sets a value for the specified variable.\nThe value can contain text, variables, and their combination.
on | off
Controls whether warnings about uninitialized variables are logged.
\n" @@ -5850,9 +7002,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`address`* [`transparent`] | `off`" ], + "syntax_html": [ + "address [transparent] | off
Makes outgoing connections to an SCGI server originate\nfrom the specified local IP address with an optional port (1.11.2).\nParameter value can contain variables (1.3.12).\nThe special value off (1.3.12) cancels the effect\nof the scgi_bind directive\ninherited from the previous configuration level, which allows the\nsystem to auto-assign the local IP address and port.
The transparent parameter (1.11.0) allows\noutgoing connections to an SCGI server originate\nfrom a non-local IP address,\nfor example, from a real IP address of a client:
scgi_bind $remote_addr transparent;\nIn order for this parameter to work,\nit is usually necessary to run nginx worker processes with the\nsuperuser privileges.\nOn Linux it is not required (1.13.8) as if\nthe transparent parameter is specified, worker processes\ninherit the CAP_NET_RAW capability from the master process.\nIt is also necessary to configure kernel routing table\nto intercept network traffic from the SCGI server.
size
Sets the size of the buffer used for reading the first part\nof the response received from the SCGI server.\nThis part usually contains a small response header.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.\nIt can be made smaller, however.
on | off
Enables or disables buffering of responses from the SCGI server.
\n\nWhen buffering is enabled, nginx receives a response from the SCGI server\nas soon as possible, saving it into the buffers set by the\nscgi_buffer_size and scgi_buffers directives.\nIf the whole response does not fit into memory, a part of it can be saved\nto a temporary file on the disk.\nWriting to temporary files is controlled by the\nscgi_max_temp_file_size and\nscgi_temp_file_write_size directives.
When buffering is disabled, the response is passed to a client synchronously,\nimmediately as it is received.\nnginx will not try to read the whole response from the SCGI server.\nThe maximum size of the data that nginx can receive from the server\nat a time is set by the scgi_buffer_size directive.
Buffering can also be enabled or disabled by passing\n“yes” or “no” in the\n“X-Accel-Buffering” response header field.\nThis capability can be disabled using the\nscgi_ignore_headers directive.
number size
Sets the number and size of the\nbuffers used for reading a response from the SCGI server,\nfor a single connection.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.
size
When buffering of responses from the SCGI\nserver is enabled, limits the total size of buffers that\ncan be busy sending a response to the client while the response is not\nyet fully read.\nIn the meantime, the rest of the buffers can be used for reading the response\nand, if needed, buffering part of the response to a temporary file.\nBy default, size is limited by the size of two buffers set by the\nscgi_buffer_size and scgi_buffers directives.
zone | off
Defines a shared memory zone used for caching.\nThe same zone can be used in several places.\nParameter value can contain variables (1.7.9).\nThe off parameter disables caching inherited\nfrom the previous configuration level.
on | off
Allows starting a background subrequest\nto update an expired cache item,\nwhile a stale cached response is returned to the client.\nNote that it is necessary to\nallow\nthe usage of a stale cached response when it is being updated.
\n" @@ -5955,9 +7128,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`string`* ..." ], + "syntax_html": [ + "string …
Defines conditions under which the response will not be taken from a cache.\nIf at least one value of the string parameters is not empty and is not\nequal to “0” then the response will not be taken from the cache:
\n\nscgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;\nscgi_cache_bypass $http_pragma $http_authorization;\nCan be used along with the scgi_no_cache directive.
string
Defines a key for caching, for example
\n\nscgi_cache_key localhost:9000$request_uri;\non | off
When enabled, only one request at a time will be allowed to populate\na new cache element identified according to the scgi_cache_key\ndirective by passing a request to an SCGI server.\nOther requests of the same cache element will either wait\nfor a response to appear in the cache or the cache lock for\nthis element to be released, up to the time set by the\nscgi_cache_lock_timeout directive.
time
If the last request passed to the SCGI server\nfor populating a new cache element\nhas not completed for the specified time,\none more request may be passed to the SCGI server.
time
Sets a timeout for scgi_cache_lock.\nWhen the time expires,\nthe request will be passed to the SCGI server,\nhowever, the response will not be cached.
\n\n" @@ -6030,9 +7218,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "Before 1.7.8, the response could be cached.
\n
number
Sets an offset in bytes for byte-range requests.\nIf the range is beyond the offset,\nthe range request will be passed to the SCGI server\nand the response will not be cached.
\n" @@ -6045,9 +7236,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`GET` | `HEAD` | `POST` ..." ], + "syntax_html": [ + "GET | HEAD | POST …
If the client request method is listed in this directive then\nthe response will be cached.\n“GET” and “HEAD” methods are always\nadded to the list, though it is recommended to specify them explicitly.\nSee also the scgi_no_cache directive.
number
Sets the number of requests after which the response\nwill be cached.
path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [min_free=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time]
Sets the path and other parameters of a cache.\nCache data are stored in files.\nThe file name in a cache is a result of\napplying the MD5 function to the\ncache key.\nThe levels parameter defines hierarchy levels of a cache:\nfrom 1 to 3, each level accepts values 1 or 2.\nFor example, in the following configuration
scgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;\nfile names in a cache will look like this:
\n\n/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c\nA cached response is first written to a temporary file,\nand then the file is renamed.\nStarting from version 0.8.9, temporary files and the cache can be put on\ndifferent file systems.\nHowever, be aware that in this case a file is copied\nacross two file systems instead of the cheap renaming operation.\nIt is thus recommended that for any given location both cache and a directory\nholding temporary files\nare put on the same file system.\nA directory for temporary files is set based on\nthe use_temp_path parameter (1.7.10).\nIf this parameter is omitted or set to the value on,\nthe directory set by the scgi_temp_path directive\nfor the given location will be used.\nIf the value is set to off,\ntemporary files will be put directly in the cache directory.
In addition, all active keys and information about data are stored\nin a shared memory zone, whose name and size\nare configured by the keys_zone parameter.\nOne megabyte zone can store about 8 thousand keys.
\n\n\nAs part of\ncommercial subscription,\nthe shared memory zone also stores extended\ncache information,\nthus, it is required to specify a larger zone size for the same number of keys.\nFor example,\none megabyte zone can store about 4 thousand keys.
\n
Cached data that are not accessed during the time specified by the\ninactive parameter get removed from the cache\nregardless of their freshness.\nBy default, inactive is set to 10 minutes.
The special “cache manager” process monitors the maximum cache size set\nby the max_size parameter,\nand the minimum amount of free space set\nby the min_free (1.19.1) parameter\non the file system with cache.\nWhen the size is exceeded or there is not enough free space,\nit removes the least recently used data.\nThe data is removed in iterations configured by\nmanager_files,\nmanager_threshold, and\nmanager_sleep parameters (1.11.5).\nDuring one iteration no more than manager_files items\nare deleted (by default, 100).\nThe duration of one iteration is limited by the\nmanager_threshold parameter (by default, 200 milliseconds).\nBetween iterations, a pause configured by the manager_sleep\nparameter (by default, 50 milliseconds) is made.
A minute after the start the special “cache loader” process is activated.\nIt loads information about previously cached data stored on file system\ninto a cache zone.\nThe loading is also done in iterations.\nDuring one iteration no more than loader_files items\nare loaded (by default, 100).\nBesides, the duration of one iteration is limited by the\nloader_threshold parameter (by default, 200 milliseconds).\nBetween iterations, a pause configured by the loader_sleep\nparameter (by default, 50 milliseconds) is made.
Additionally,\nthe following parameters are available as part of our\ncommercial subscription:
\n\npurger=on|off
Instructs whether cache entries that match a\nwildcard key\nwill be removed from the disk by the cache purger (1.7.12).\nSetting the parameter to on\n(default is off)\nwill activate the “cache purger” process that\npermanently iterates through all cache entries\nand deletes the entries that match the wildcard key.
purger_files=number
Sets the number of items that will be scanned during one iteration (1.7.12).\nBy default, purger_files is set to 10.
purger_threshold=number
Sets the duration of one iteration (1.7.12).\nBy default, purger_threshold is set to 50 milliseconds.
purger_sleep=number
Sets a pause between iterations (1.7.12).\nBy default, purger_sleep is set to 50 milliseconds.
\n\n" @@ -6088,9 +7288,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "string ..." ], + "syntax_html": [ + "In versions 1.7.3, 1.7.7, and 1.11.10 cache header format has been changed.\nPreviously cached responses will be considered invalid\nafter upgrading to a newer nginx version.
\n
string …
\n" + ], "isBlock": false, "description_md": "Defines conditions under which the request will be considered a cache\npurge request.\nIf at least one value of the string parameters is not empty and is not equal\nto “0” then the cache entry with a corresponding\n[cache key](https://nginx.org/en/docs/http/ngx_http_scgi_module.html#scgi_cache_key) is removed.\nThe result of successful operation is indicated by returning\nthe 204 (No Content) response.\n\nIf the [cache key](https://nginx.org/en/docs/http/ngx_http_scgi_module.html#scgi_cache_key) of a purge request ends\nwith an asterisk (“`*`”), all cache entries matching the\nwildcard key will be removed from the cache.\nHowever, these entries will remain on the disk until they are deleted\nfor either [inactivity](https://nginx.org/en/docs/http/ngx_http_scgi_module.html#scgi_cache_path),\nor processed by the [cache purger](https://nginx.org/en/docs/http/ngx_http_scgi_module.html#purger) (1.7.12),\nor a client attempts to access them.\n\nExample configuration:\n```\nscgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;\n\nmap $request_method $purge_method {\n PURGE 1;\n default 0;\n}\n\nserver {\n ...\n location / {\n scgi_pass backend;\n scgi_cache cache_zone;\n scgi_cache_key $uri;\n scgi_cache_purge $purge_method;\n }\n}\n```\n> This functionality is available as part of our\n> [commercial subscription](https://nginx.com/products/).", "description_html": "Defines conditions under which the request will be considered a cache\npurge request.\nIf at least one value of the string parameters is not empty and is not equal\nto “0” then the cache entry with a corresponding\ncache key is removed.\nThe result of successful operation is indicated by returning\nthe 204 (No Content) response.
\n\nIf the cache key of a purge request ends\nwith an asterisk (“*”), all cache entries matching the\nwildcard key will be removed from the cache.\nHowever, these entries will remain on the disk until they are deleted\nfor either inactivity,\nor processed by the cache purger (1.7.12),\nor a client attempts to access them.
Example configuration:
\n\nscgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;\n\nmap $request_method $purge_method {\n PURGE 1;\n default 0;\n}\n\nserver {\n ...\n location / {\n scgi_pass backend;\n scgi_cache cache_zone;\n scgi_cache_key $uri;\n scgi_cache_purge $purge_method;\n }\n}\n\n\n" @@ -6103,9 +7306,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "This functionality is available as part of our\ncommercial subscription.
\n
on | off
Enables revalidation of expired cache items using conditional requests with\nthe “If-Modified-Since” and “If-None-Match”\nheader fields.
\n" @@ -6118,9 +7324,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`error` | `timeout` | `invalid_header` | `updating` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `off` ..." ], + "syntax_html": [ + "error | timeout | invalid_header | updating | http_500 | http_503 | http_403 | http_404 | http_429 | off …
Determines in which cases a stale cached response can be used\nwhen an error occurs during communication with the SCGI server.\nThe directive’s parameters match the parameters of the\nscgi_next_upstream directive.
The error parameter also permits\nusing a stale cached response if an SCGI server to process a request\ncannot be selected.
Additionally, the updating parameter permits\nusing a stale cached response if it is currently being updated.\nThis allows minimizing the number of accesses to SCGI servers\nwhen updating cached data.
Using a stale cached response\ncan also be enabled directly in the response header\nfor a specified number of seconds after the response became stale (1.11.10).\nThis has lower priority than using the directive parameters.
\n\nTo minimize the number of accesses to SCGI servers when\npopulating a new cache element, the scgi_cache_lock\ndirective can be used.
[code …] time
Sets caching time for different response codes.\nFor example, the following directives
\n\nscgi_cache_valid 200 302 10m;\nscgi_cache_valid 404 1m;\nset 10 minutes of caching for responses with codes 200 and 302\nand 1 minute for responses with code 404.
\n\nIf only caching time is specified
scgi_cache_valid 5m;\nthen only 200, 301, and 302 responses are cached.
\n\nIn addition, the any parameter can be specified\nto cache any responses:
scgi_cache_valid 200 302 10m;\nscgi_cache_valid 301 1h;\nscgi_cache_valid any 1m;\nParameters of caching can also be set directly\nin the response header.\nThis has higher priority than setting of caching time using the directive.
\n\n@ prefix, it sets an absolute\ntime in seconds since Epoch, up to which the response may be cached.*”, such a\nresponse will not be cached (1.7.7).\nIf the header includes the “Vary” field\nwith another value, such a response will be cached\ntaking into account the corresponding request header fields (1.7.7).Processing of one or more of these response header fields can be disabled\nusing the scgi_ignore_headers directive.
time
Defines a timeout for establishing a connection with an SCGI server.\nIt should be noted that this timeout cannot usually exceed 75 seconds.
\n" @@ -6163,9 +7378,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables byte-range support\nfor both cached and uncached responses from the SCGI server\nregardless of the “Accept-Ranges” field in these responses.
\n" @@ -6178,9 +7396,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`field`*" ], + "syntax_html": [ + "field
By default,\nnginx does not pass the header fields “Status” and\n“X-Accel-…” from the response of an SCGI\nserver to a client.\nThe scgi_hide_header directive sets additional fields\nthat will not be passed.\nIf, on the contrary, the passing of fields needs to be permitted,\nthe scgi_pass_header directive can be used.
on | off
Determines whether the connection with an SCGI server should be\nclosed when a client closes the connection without waiting\nfor a response.
\n" @@ -6208,9 +7432,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`field`* ..." ], + "syntax_html": [ + "field …
Disables processing of certain response header fields from the SCGI server.\nThe following fields can be ignored: “X-Accel-Redirect”,\n“X-Accel-Expires”, “X-Accel-Limit-Rate” (1.1.6),\n“X-Accel-Buffering” (1.1.6),\n“X-Accel-Charset” (1.1.6), “Expires”,\n“Cache-Control”, “Set-Cookie” (0.8.44),\nand “Vary” (1.7.7).
\n\nIf not disabled, processing of these header fields has the following\neffect:
\n\ncharset\nof a response.on | off
Determines whether an SCGI server responses with codes greater than or equal\nto 300 should be passed to a client\nor be intercepted and redirected to nginx for processing\nwith the error_page directive.
rate
Limits the speed of reading the response from the SCGI server.\nThe rate is specified in bytes per second.\nThe zero value disables rate limiting.\nThe limit is set per a request, and so if nginx simultaneously opens\ntwo connections to the SCGI server,\nthe overall rate will be twice as much as the specified limit.\nThe limitation works only if\nbuffering of responses from the SCGI\nserver is enabled.
size
When buffering of responses from the SCGI\nserver is enabled, and the whole response does not fit into the buffers\nset by the scgi_buffer_size and scgi_buffers\ndirectives, a part of the response can be saved to a temporary file.\nThis directive sets the maximum size of the temporary file.\nThe size of data written to the temporary file at a time is set\nby the scgi_temp_file_write_size directive.
The zero value disables buffering of responses to temporary files.
\n\n\n\n" @@ -6268,9 +7504,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`error` | `timeout` | `invalid_header` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `non_idempotent` | `off` ..." ], + "syntax_html": [ + "This restriction does not apply to responses\nthat will be cached\nor stored on disk.
\n
error | timeout | invalid_header | http_500 | http_503 | http_403 | http_404 | http_429 | non_idempotent | off …
Specifies in which cases a request should be passed to the next server:
\n\nerror
an error occurred while establishing a connection with the\nserver, passing a request to it, or reading the response header;
timeout
a timeout has occurred while establishing a connection with the\nserver, passing a request to it, or reading the response header;
invalid_header
a server returned an empty or invalid response;
http_500
a server returned a response with the code 500;
http_503
a server returned a response with the code 503;
http_403
a server returned a response with the code 403;
http_404
a server returned a response with the code 404;
http_429
a server returned a response with the code 429 (1.11.13);
non_idempotent
normally, requests with a\nnon-idempotent\nmethod\n(POST, LOCK, PATCH)\nare not passed to the next server\nif a request has been sent to an upstream server (1.9.13);\nenabling this option explicitly allows retrying such requests;
off
disables passing a request to the next server.
One should bear in mind that passing a request to the next server is\nonly possible if nothing has been sent to a client yet.\nThat is, if an error or timeout occurs in the middle of the\ntransferring of a response, fixing this is impossible.
\n\nThe directive also defines what is considered an\nunsuccessful attempt of communication with a server.\nThe cases of error, timeout and\ninvalid_header are always considered unsuccessful attempts,\neven if they are not specified in the directive.\nThe cases of http_500, http_503,\nand http_429 are\nconsidered unsuccessful attempts only if they are specified in the directive.\nThe cases of http_403 and http_404\nare never considered unsuccessful attempts.
Passing a request to the next server can be limited by\nthe number of tries\nand by time.
\n" @@ -6283,9 +7522,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Limits the time during which a request can be passed to the\nnext server.\nThe 0 value turns off this limitation.
number
Limits the number of possible tries for passing a request to the\nnext server.\nThe 0 value turns off this limitation.
string …
Defines conditions under which the response will not be saved to a cache.\nIf at least one value of the string parameters is not empty and is not\nequal to “0” then the response will not be saved:
\n\nscgi_no_cache $cookie_nocache $arg_nocache$arg_comment;\nscgi_no_cache $http_pragma $http_authorization;\nCan be used along with the scgi_cache_bypass directive.
parameter value [if_not_empty]
Sets a parameter that should be passed to the SCGI server.\nThe value can contain text, variables, and their combination.\nThese directives are inherited from the previous configuration level\nif and only if there are no scgi_param directives\ndefined on the current level.
Standard\nCGI environment variables\nshould be provided as SCGI headers, see the scgi_params file\nprovided in the distribution:
location / {\n include scgi_params;\n ...\n}\nIf the directive is specified with if_not_empty (1.1.11) then\nsuch a parameter will be passed to the server only if its value is not empty:
scgi_param HTTPS $https if_not_empty;\naddress
Sets the address of an SCGI server.\nThe address can be specified as a domain name or IP address,\nand a port:
\n\nscgi_pass localhost:9000;\nor as a UNIX-domain socket path:
\n\nscgi_pass unix:/tmp/scgi.socket;\nIf a domain name resolves to several addresses, all of them will be\nused in a round-robin fashion.\nIn addition, an address can be specified as a\nserver group.
\n\nParameter value can contain variables.\nIn this case, if an address is specified as a domain name,\nthe name is searched among the described\nserver groups,\nand, if not found, is determined using a\nresolver.
field
Permits passing otherwise disabled header\nfields from an SCGI server to a client.
\n" @@ -6372,9 +7629,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Indicates whether the original request body is passed\nto the SCGI server.\nSee also the scgi_pass_request_headers directive.
on | off
Indicates whether the header fields of the original request are passed\nto the SCGI server.\nSee also the scgi_pass_request_body directive.
time
Defines a timeout for reading a response from the SCGI server.\nThe timeout is set only between two successive read operations,\nnot for the transmission of the whole response.\nIf the SCGI server does not transmit anything within this time,\nthe connection is closed.
\n" @@ -6417,9 +7683,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables buffering of a client request body.
\n\nWhen buffering is enabled, the entire request body is\nread\nfrom the client before sending the request to an SCGI server.
\n\nWhen buffering is disabled, the request body is sent to the SCGI server\nimmediately as it is received.\nIn this case, the request cannot be passed to the\nnext server\nif nginx already started sending the request body.
\n\nWhen HTTP/1.1 chunked transfer encoding is used\nto send the original request body,\nthe request body will be buffered regardless of the directive value.
\n" @@ -6432,9 +7701,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Sets a timeout for transmitting a request to the SCGI server.\nThe timeout is set only between two successive write operations,\nnot for the transmission of the whole request.\nIf the SCGI server does not receive anything within this time,\nthe connection is closed.
\n" @@ -6447,9 +7719,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Configures the “TCP keepalive” behavior\nfor outgoing connections to an SCGI server.\nBy default, the operating system’s settings are in effect for the socket.\nIf the directive is set to the value “on”, the\nSO_KEEPALIVE socket option is turned on for the socket.
on | off | string
Enables saving of files to a disk.\nThe on parameter saves files with paths\ncorresponding to the directives\nalias or\nroot.\nThe off parameter disables saving of files.\nIn addition, the file name can be set explicitly using the\nstring with variables:
scgi_store /data/www$original_uri;\nThe modification time of files is set according to the received\n“Last-Modified” response header field.\nThe response is first written to a temporary file,\nand then the file is renamed.\nStarting from version 0.8.9, temporary files and the persistent store\ncan be put on different file systems.\nHowever, be aware that in this case a file is copied\nacross two file systems instead of the cheap renaming operation.\nIt is thus recommended that for any given location both saved files and a\ndirectory holding temporary files, set by the scgi_temp_path\ndirective, are put on the same file system.
This directive can be used to create local copies of static unchangeable\nfiles, e.g.:
\n\nlocation /images/ {\n root /data/www;\n error_page 404 = /fetch$uri;\n}\n\nlocation /fetch/ {\n internal;\n\n scgi_pass backend:9000;\n ...\n\n scgi_store on;\n scgi_store_access user:rw group:rw all:r;\n scgi_temp_path /data/temp;\n\n alias /data/www/;\n}\nusers:permissions …
Sets access permissions for newly created files and directories, e.g.:
\n\nscgi_store_access user:rw group:rw all:r;\nIf any group or all access permissions\nare specified then user permissions may be omitted:
scgi_store_access group:rw all:r;\nsize
Limits the size of data written to a temporary file\nat a time, when buffering of responses from the SCGI server\nto temporary files is enabled.\nBy default, size is limited by two buffers set by the\nscgi_buffer_size and scgi_buffers directives.\nThe maximum size of a temporary file is set by the\nscgi_max_temp_file_size directive.
path [level1 [level2 [level3]]]
Defines a directory for storing temporary files\nwith data received from SCGI servers.\nUp to three-level subdirectory hierarchy can be used underneath the specified\ndirectory.\nFor example, in the following configuration
\n\nscgi_temp_path /spool/nginx/scgi_temp 1 2;\na temporary file might look like this:
\n\n/spool/nginx/scgi_temp/7/45/00000123457\nSee also the use_temp_path parameter of the\nscgi_cache_path directive.
expression
Defines a string with variables from which the\nchecksum value and lifetime of a link will be extracted.
\n\nVariables used in an expression are usually associated\nwith a request; see example below.
The checksum value extracted from the string is compared with\nthe MD5 hash value of the expression defined by the\nsecure_link_md5 directive.\nIf the checksums are different, the $secure_link variable\nis set to an empty string.\nIf the checksums are the same, the link lifetime is checked.\nIf the link has a limited lifetime and the time has expired,\nthe $secure_link variable is set to “0”.\nOtherwise, it is set to “1”.\nThe MD5 hash value passed in a request is encoded in\nbase64url.
If a link has a limited lifetime, the expiration time\nis set in seconds since Epoch (Thu, 01 Jan 1970 00:00:00 GMT).\nThe value is specified in the expression after the MD5 hash,\nand is separated by a comma.\nThe expiration time passed in a request is available through\nthe $secure_link_expires variable for a use in\nthe secure_link_md5 directive.\nIf the expiration time is not specified, a link has the unlimited\nlifetime.
expression
Defines an expression for which the MD5 hash value will\nbe computed and compared with the value passed in a request.
\n\nThe expression should contain the secured part of a link (resource)\nand a secret ingredient.\nIf the link has a limited lifetime,\nthe expression should also contain $secure_link_expires.
To prevent unauthorized access, the expression may contain some\ninformation about the client, such as its address and browser version.
\n\nExample:
\n\nlocation /s/ {\n secure_link $arg_md5,$arg_expires;\n secure_link_md5 "$secure_link_expires$uri$remote_addr secret";\n\n if ($secure_link = "") {\n return 403;\n }\n\n if ($secure_link = "0") {\n return 410;\n }\n\n ...\n}\nThe\n“/s/link?md5=_e4Nc3iduzkWRm01TBBNYw&expires=2147483647”\nlink\nrestricts access to “/s/link” for the client with the\nIP address 127.0.0.1.\nThe link also has the limited lifetime until January 19, 2038 (GMT).
On UNIX, the md5 request argument value can be obtained as:
echo -n '2147483647/s/link127.0.0.1 secret' | \\\n openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =\nword
Defines a secret word used to check authenticity\nof requested links.
The full URI of a requested link looks as follows:
\n\n/*`prefix`*/*`hash`*/*`link`*\nwhere hash is a hexadecimal representation of the\nMD5 hash computed for the concatenation of the link and secret word,\nand prefix is an arbitrary string without slashes.
If the requested link passes the authenticity check,\nthe $secure_link variable is set to the link\nextracted from the request URI.\nOtherwise, the $secure_link variable\nis set to an empty string.
Example:
\n\nlocation /p/ {\n secure_link_secret secret;\n\n if ($secure_link = "") {\n return 403;\n }\n\n rewrite ^ /secure/$secure_link;\n}\n\nlocation /secure/ {\n internal;\n}\nA request of “/p/5e814704a28d9bc1914ff19fa0c4a00a/link”\nwill be internally redirected to\n“/secure/link”.
On UNIX, the hash value for this example can be obtained as:
\n\necho -n 'linksecret' | openssl md5 -hex\nname | off
Enables the use of the specified session log.\nThe special value off cancels the effect\nof the session_log directives\ninherited from the previous configuration level.
name string …
Specifies the output format of a log.\nThe value of the $body_bytes_sent variable is aggregated across\nall requests in a session.\nThe values of all other variables available for logging correspond to the\nfirst request in a session.
path zone=name:size [format=format] [timeout=time] [id=id] [md5=md5]
Sets the path to a log file and configures the shared memory zone that is used\nto store currently active sessions.
\n\nA session is considered active for as long as the time elapsed since\nthe last request in the session does not exceed the specified\ntimeout (by default, 30 seconds).\nOnce a session is no longer active, it is written to the log.
The id parameter identifies the\nsession to which a request is mapped.\nThe id parameter is set to the hexadecimal representation\nof an MD5 hash (for example, obtained from a cookie using variables).\nIf this parameter is not specified or does not represent the valid\nMD5 hash, nginx computes the MD5 hash from the value of\nthe md5 parameter and creates a new session using this hash.\nBoth the id and md5 parameters\ncan contain variables.
The format parameter sets the custom session log\nformat configured by the session_log_format directive.\nIf format is not specified, the predefined\n“combined” format is used.
size
Sets the size of the slice.\nThe zero value disables splitting responses into slices.\nNote that a too low value may result in excessive memory usage\nand opening a large number of files.
In order for a subrequest to return the required range,\nthe $slice_range variable should be\npassed to\nthe proxied server as the Range request header field.\nIf\ncaching\nis enabled, $slice_range should be added to the\ncache key\nand caching of responses with 206 status code should be\nenabled.
string $variable {...}
Creates a variable for A/B testing, for example:
\n\nsplit_clients "${remote_addr}AAA" $variant {\n 0.5% .one;\n 2.0% .two;\n * "";\n}\nThe value of the original string is hashed using MurmurHash2.\nIn the example given, hash values from 0 to 21474835 (0.5%)\ncorrespond to the\nvalue ".one" of the $variant variable,\nhash values from 21474836 to 107374180 (2%) correspond to\nthe value ".two",\nand hash values from 107374181 to 4294967295 correspond to\nthe value "" (an empty string).
on | off
Enables or disables processing of SSI commands in responses.
\n" @@ -6680,9 +7994,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Allows preserving the “Last-Modified” header field\nfrom the original response during SSI processing\nto facilitate response caching.
\n\nBy default, the header field is removed as contents of the response\nare modified during processing and may contain dynamically generated elements\nor parts that are changed independently of the original response.
\n" @@ -6695,9 +8012,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`size`" ], + "syntax_html": [ + "size
Sets the minimum size for parts of a response stored on disk,\nstarting from which it makes sense to send them using\nsendfile.
on | off
If enabled, suppresses the output of the\n“[an error occurred while processing the directive]”\nstring if an error occurred during SSI processing.
mime-type …
Enables processing of SSI commands in responses with the specified MIME types\nin addition to “text/html”.\nThe special value “*” matches any MIME type (0.8.29).
length
Sets the maximum length of parameter values in SSI commands.
\n" @@ -6760,9 +8089,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
This directive was made obsolete in version 1.15.0\nand was removed in version 1.25.1.\nThe ssl parameter\nof the listen directive\nshould be used instead.
size
Sets the size of the buffer used for sending data.
\n\nBy default, the buffer size is 16k, which corresponds to minimal\noverhead when sending big responses.\nTo minimize Time To First Byte it may be beneficial to use smaller values,\nfor example:
\n\nssl_buffer_size 4k;\nfile
Specifies a file with the certificate in the PEM format\nfor the given virtual server.\nIf intermediate certificates should be specified in addition to a primary\ncertificate, they should be specified in the same file in the following\norder: the primary certificate comes first, then the intermediate certificates.\nA secret key in the PEM format may be placed in the same file.
Since version 1.11.0,\nthis directive can be specified multiple times\nto load certificates of different types, for example, RSA and ECDSA:
\n\nserver {\n listen 443 ssl;\n server_name example.com;\n\n ssl_certificate example.com.rsa.crt;\n ssl_certificate_key example.com.rsa.key;\n\n ssl_certificate example.com.ecdsa.crt;\n ssl_certificate_key example.com.ecdsa.key;\n\n ...\n}\n\n\n\nOnly OpenSSL 1.0.2 or higher supports separate\ncertificate chains\nfor different certificates.\nWith older versions, only one certificate chain can be used.
\n
Since version 1.15.9, variables can be used in the file name\nwhen using OpenSSL 1.0.2 or higher:
ssl_certificate $ssl_server_name.crt;\nssl_certificate_key $ssl_server_name.key;\nNote that using variables implies that\na certificate will be loaded for each SSL handshake,\nand this may have a negative impact on performance.
\n\nThe value\ndata:$variable\ncan be specified instead of the file (1.15.10),\nwhich loads a certificate from a variable\nwithout using intermediate files.\nNote that inappropriate use of this syntax may have its security implications,\nsuch as writing secret key data to\nerror log.
It should be kept in mind that due to the HTTPS protocol limitations\nfor maximum interoperability virtual servers should listen on\ndifferent IP addresses.
\n" @@ -6802,9 +8140,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "file
Specifies a file with the secret key in the PEM format\nfor the given virtual server.
The value\nengine:name:id\ncan be specified instead of the file (1.7.9),\nwhich loads a secret key with a specified id\nfrom the OpenSSL engine name.
The value\ndata:$variable\ncan be specified instead of the file (1.15.10),\nwhich loads a secret key from a variable without using intermediate files.\nNote that inappropriate use of this syntax may have its security implications,\nsuch as writing secret key data to\nerror log.
Since version 1.15.9, variables can be used in the file name\nwhen using OpenSSL 1.0.2 or higher.
ciphers
Specifies the enabled ciphers.\nThe ciphers are specified in the format understood by the\nOpenSSL library, for example:
\n\nssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;\nThe full list can be viewed using the\n“openssl ciphers” command.
\n\n" @@ -6830,9 +8174,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "The previous versions of nginx used\ndifferent\nciphers by default.
\n
file
Specifies a file with trusted CA certificates in the PEM format\nused to verify client certificates and\nOCSP responses if ssl_stapling is enabled.
The list of certificates will be sent to clients.\nIf this is not desired, the ssl_trusted_certificate\ndirective can be used.
name value
Sets arbitrary OpenSSL configuration\ncommands.
\n\n\n\n\nThe directive is supported when using OpenSSL 1.0.2 or higher.
\n
Several ssl_conf_command directives\ncan be specified on the same level:
ssl_conf_command Options PrioritizeChaCha;\nssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;\nThese directives are inherited from the previous configuration level\nif and only if there are no ssl_conf_command directives\ndefined on the current level.
\n\n" @@ -6858,9 +8208,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "Note that configuring OpenSSL directly\nmight result in unexpected behavior.
\n
file
Specifies a file with revoked certificates (CRL)\nin the PEM format used to verify\nclient certificates.
file
Specifies a file with DH parameters for DHE ciphers.
By default no parameters are set,\nand therefore DHE ciphers will not be used.
\n\n\n\n" @@ -6886,9 +8242,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "Prior to version 1.11.0, builtin parameters were used by default.
\n
on | off
Enables or disables TLS 1.3\nearly data.
\n\n\n\n\nRequests sent within early data are subject to\nreplay attacks.\nTo protect against such attacks at the application layer,\nthe $ssl_early_data variable\nshould be used.
\n
proxy_set_header Early-Data $ssl_early_data;\n\n\n" @@ -6900,9 +8259,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`curve`*" ], + "syntax_html": [ + "The directive is supported when using OpenSSL 1.1.1 or higher (1.15.4) and\nBoringSSL.
\n
curve
Specifies a curve for ECDHE ciphers.
When using OpenSSL 1.0.2 or higher,\nit is possible to specify multiple curves (1.11.0), for example:
\n\nssl_ecdh_curve prime256v1:secp384r1;\nThe special value auto (1.11.0) instructs nginx to use\na list built into the OpenSSL library when using OpenSSL 1.0.2 or higher,\nor prime256v1 with older versions.
\n\n" @@ -6914,9 +8276,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off` | `leaf`" ], + "syntax_html": [ + "Prior to version 1.11.0,\nthe
\n\nprime256v1curve was used by default.When using OpenSSL 1.0.2 or higher,\nthis directive sets the list of curves supported by the server.\nThus, in order for ECDSA certificates to work,\nit is important to include the curves used in the certificates.
\n
on | off | leaf
Enables OCSP validation of the client certificate chain.\nThe leaf parameter\nenables validation of the client certificate only.
For the OCSP validation to work,\nthe ssl_verify_client directive should be set to\non or optional.
To resolve the OCSP responder hostname,\nthe resolver directive\nshould also be specified.
Example:
\n\nssl_verify_client on;\nssl_ocsp on;\nresolver 192.0.2.1;\noff | [shared:name:size]
Sets name and size of the cache\nthat stores client certificates status for OCSP validation.\nThe cache is shared between all worker processes.\nA cache with the same name can be used in several virtual servers.
The off parameter prohibits the use of the cache.
url
Overrides the URL of the OCSP responder specified in the\n“Authority Information Access” certificate extension\nfor validation of client certificates.
\n\nOnly “http://” OCSP responders are supported:
ssl_ocsp_responder http://ocsp.example.com/;\nfile
Specifies a file with passphrases for\nsecret keys\nwhere each passphrase is specified on a separate line.\nPassphrases are tried in turn when loading the key.
Example:
\n\nhttp {\n ssl_password_file /etc/keys/global.pass;\n ...\n\n server {\n server_name www1.example.com;\n ssl_certificate_key /etc/keys/first.key;\n }\n\n server {\n server_name www2.example.com;\n\n # named pipe can also be used instead of a file\n ssl_password_file /etc/keys/fifo;\n ssl_certificate_key /etc/keys/second.key;\n }\n}\non | off
Specifies that server ciphers should be preferred over client\nciphers when using the SSLv3 and TLS protocols.
\n" @@ -6984,9 +8361,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "[`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]" ], + "syntax_html": [ + "[SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]
Enables the specified protocols.
\n\n\n\n" @@ -6998,9 +8378,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "The
\n\nTLSv1.1andTLSv1.2parameters\n(1.1.13, 1.0.12) work only when OpenSSL 1.0.1 or higher is used.The
\n\nTLSv1.3parameter (1.13.0) works only when\nOpenSSL 1.1.1 or higher is used.The
\nTLSv1.3parameter is used by default\nsince 1.23.4.
on | off
If enabled, SSL handshakes in\nthe server block will be rejected.
For example, in the following configuration, SSL handshakes with\nserver names other than example.com are rejected:
server {\n listen 443 ssl default_server;\n ssl_reject_handshake on;\n}\n\nserver {\n listen 443 ssl;\n server_name example.com;\n ssl_certificate example.com.crt;\n ssl_certificate_key example.com.key;\n}\noff | none | [builtin[:size]] [shared:name:size]
Sets the types and sizes of caches that store session parameters.\nA cache can be of any of the following types:
\n\noff
the use of a session cache is strictly prohibited:\nnginx explicitly tells a client that sessions may not be reused.
none
the use of a session cache is gently disallowed:\nnginx tells a client that sessions may be reused, but does not\nactually store session parameters in the cache.
builtin
a cache built in OpenSSL; used by one worker process only.\nThe cache size is specified in sessions.\nIf size is not given, it is equal to 20480 sessions.\nUse of the built-in cache can cause memory fragmentation.
shared
a cache shared between all worker processes.\nThe cache size is specified in bytes; one megabyte can store\nabout 4000 sessions.\nEach shared cache should have an arbitrary name.\nA cache with the same name can be used in several virtual servers.\nIt is also used to automatically generate, store, and\nperiodically rotate TLS session ticket keys (1.23.2)\nunless configured explicitly\nusing the ssl_session_ticket_key directive.
Both cache types can be used simultaneously, for example:
\n\nssl_session_cache builtin:1000 shared:SSL:10m;\nbut using only shared cache without the built-in cache should\nbe more efficient.
\n" @@ -7026,9 +8412,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "file
Sets a file with the secret key used to encrypt\nand decrypt TLS session tickets.\nThe directive is necessary if the same key has to be shared between\nmultiple servers.\nBy default, a randomly generated key is used.
If several keys are specified, only the first key is\nused to encrypt TLS session tickets.\nThis allows configuring key rotation, for example:
\n\nssl_session_ticket_key current.key;\nssl_session_ticket_key previous.key;\nThe file must contain 80 or 48 bytes\nof random data and can be created using the following command:
openssl rand 80 > ticket.key\nDepending on the file size either AES256 (for 80-byte keys, 1.11.8)\nor AES128 (for 48-byte keys) is used for encryption.
\n" @@ -7040,9 +8429,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables session resumption through\nTLS session tickets.
\n" @@ -7054,9 +8446,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Specifies a time during which a client may reuse the\nsession parameters.
\n" @@ -7068,9 +8463,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables\nstapling of OCSP responses by the server.\nExample:
\n\nssl_stapling on;\nresolver 192.0.2.1;\nFor the OCSP stapling to work, the certificate of the server certificate\nissuer should be known.\nIf the ssl_certificate file does\nnot contain intermediate certificates,\nthe certificate of the server certificate issuer should be\npresent in the\nssl_trusted_certificate file.
For a resolution of the OCSP responder hostname,\nthe resolver directive\nshould also be specified.
file
When set, the stapled OCSP response will be taken from the\nspecified file instead of querying\nthe OCSP responder specified in the server certificate.
The file should be in the DER format as produced by the\n“openssl ocsp” command.
url
Overrides the URL of the OCSP responder specified in the\n“Authority Information Access” certificate extension.
\n\nOnly “http://” OCSP responders are supported:
ssl_stapling_responder http://ocsp.example.com/;\non | off
Enables or disables verification of OCSP responses by the server.
\n\nFor verification to work, the certificate of the server certificate\nissuer, the root certificate, and all intermediate certificates\nshould be configured as trusted using the\nssl_trusted_certificate directive.
file
Specifies a file with trusted CA certificates in the PEM format\nused to verify client certificates and\nOCSP responses if ssl_stapling is enabled.
In contrast to the certificate set by ssl_client_certificate,\nthe list of these certificates will not be sent to clients.
on | off | optional | optional_no_ca
Enables verification of client certificates.\nThe verification result is stored in the\n$ssl_client_verify variable.
\n\nThe optional parameter (0.8.7+) requests the client\ncertificate and verifies it if the certificate is present.
The optional_no_ca parameter (1.3.8, 1.2.5)\nrequests the client\ncertificate but does not require it to be signed by a trusted CA certificate.\nThis is intended for the use in cases when a service that is external to nginx\nperforms the actual certificate verification.\nThe contents of the certificate is accessible through the\n$ssl_client_cert variable.
number
Sets the verification depth in the client certificates chain.
\n" @@ -7171,7 +8587,10 @@ "contexts": [ "location" ], - "syntax": [ + "syntax_md": [ + "" + ], + "syntax_html": [ "" ], "isBlock": false, @@ -7186,10 +8605,14 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`json`", "`jsonp` [*`callback`*]" ], + "syntax_html": [ + "json
jsonp [callback]
By default, status information is output in the JSON format.
\n\nAlternatively, data may be output as JSONP.\nThe callback parameter specifies the name of a callback function.\nParameter value can contain variables.\nIf parameter is omitted, or the computed value is an empty string,\nthen “ngx_status_jsonp_callback” is used.
zone
Enables collection of virtual\nhttp\nor\nstream\n(1.7.11) server status information in the specified zone.\nSeveral servers may share the same zone.
string replacement
Sets a string to replace and a replacement string.\nThe string to replace is matched ignoring the case.\nThe string to replace (1.9.4) and replacement string can contain variables.\nSeveral sub_filter directives\ncan be specified on the same configuration level (1.9.4).\nThese directives are inherited from the previous configuration level\nif and only if there are no sub_filter directives\ndefined on the current level.
on | off
Allows preserving the “Last-Modified” header field\nfrom the original response during replacement\nto facilitate response caching.
\n\nBy default, the header field is removed as contents of the response\nare modified during processing.
\n" @@ -7271,9 +8706,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Indicates whether to look for each string to replace\nonce or repeatedly.
\n" @@ -7286,9 +8724,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`mime-type`* ..." ], + "syntax_html": [ + "mime-type …
Enables string replacement in responses with the specified MIME types\nin addition to “text/html”.\nThe special value “*” matches any MIME type (0.8.29).
[parameters]
Enables periodic health checks of the servers in a\ngroup\nreferenced in the surrounding location.
\n\nThe following optional parameters are supported:
\n\ninterval=time
sets the interval between two consecutive health checks,\nby default, 5 seconds.
jitter=time
sets the time within which\neach health check will be randomly delayed,\nby default, there is no delay.
fails=number
sets the number of consecutive failed health checks of a particular server\nafter which this server will be considered unhealthy,\nby default, 1.
passes=number
sets the number of consecutive passed health checks of a particular server\nafter which the server will be considered healthy,\nby default, 1.
uri=uri
defines the URI used in health check requests,\nby default, “/”.
mandatory [persistent]
sets the initial “checking” state for a server\nuntil the first health check is completed (1.11.7).\nClient requests are not passed to servers in the “checking” state.\nIf the parameter is not specified,\nthe server will be initially considered healthy.
\n\nThe persistent parameter (1.19.7)\nsets the initial “up” state for a server after reload\nif the server was considered healthy before reload.
match=name
specifies the match block configuring the tests that a\nresponse should pass in order for a health check to pass.\nBy default, the response should have status code 2xx or 3xx.
port=number
defines the port used when connecting to a server\nto perform a health check (1.9.7).\nBy default, equals the\nserver port.
type=grpc\n[grpc_service=name]\n[grpc_status=code]
enables periodic\nhealth checks of a gRPC server\nor a particular gRPC service specified with the optional\ngrpc_service parameter (1.19.5).\nIf the server does not support the gRPC Health Checking Protocol,\nthe optional grpc_status parameter can be used\nto specify non-zero gRPC\nstatus\n(for example,\nstatus code “12” / “UNIMPLEMENTED”)\nthat will be treated as healthy:
health_check mandatory type=grpc grpc_status=12;\nThe type=grpc parameter\nmust be specified after all other directive parameters,\ngrpc_service and grpc_status\nmust follow type=grpc.\nThe parameter is not compatible with\nuri or\nmatch parameters.
keepalive_time=time
enables keepalive\nconnections for health checks and specifies the time during which\nrequests can be processed through one keepalive connection (1.21.7).\nBy default keepalive connections are disabled.
name {...}
Defines the named test set used to verify responses to health check requests.
\n\nThe following items can be tested in a response:
\n\nstatus 200;
status is 200
status ! 500;
status is not 500
status 200 204;
status is 200 or 204
status ! 301 302;
status is neither 301 nor 302
status 200-399;
status is in the range from 200 to 399
status ! 400-599;
status is not in the range from 400 to 599
status 301-303 307;
status is either 301, 302, 303, or 307
header Content-Type = text/html;
header contains “Content-Type”\nwith value text/html
header Content-Type != text/html;
header contains “Content-Type”\nwith value other than text/html
header Connection ~ close;
header contains “Connection”\nwith value matching regular expression close
header Connection !~ close;
header contains “Connection”\nwith value not matching regular expression close
header Host;
header contains “Host”
header ! X-Accel-Redirect;
header lacks “X-Accel-Redirect”
body ~ "Welcome to nginx!";
body matches regular expression “Welcome to nginx!”
body !~ "Welcome to nginx!";
body does not match regular expression “Welcome to nginx!”
require
*`$variable`*\n `...;`\nall specified variables are not empty and not equal to “0” (1.15.9).
If several tests are specified,\nthe response matches only if it matches all tests.
\n\n\n\n\nOnly the first 256k of the response body are examined.
\n
Examples:
\n\n# status is 200, content type is "text/html",\n# and body contains "Welcome to nginx!"\nmatch welcome {\n status 200;\n header Content-Type = text/html;\n body ~ "Welcome to nginx!";\n}\n# status is not one of 301, 302, 303, or 307, and header does not have "Refresh:"\nmatch not_redirect {\n status ! 301-303 307;\n header ! Refresh;\n}\n# status ok and not in maintenance mode\nmatch server_ok {\n status 200-399;\n body !~ "maintenance mode";\n}\n# status is 200 or 204\nmap $upstream_status $good_status {\n 200 1;\n 204 1;\n}\n\nmatch server_ok {\n require $good_status;\n}\nname {...}
Defines a group of servers.\nServers can listen on different ports.\nIn addition, servers listening on TCP and UNIX-domain sockets\ncan be mixed.
\n\nExample:
\n\nupstream backend {\n server backend1.example.com weight=5;\n server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;\n server unix:/tmp/backend3;\n\n server backup1.example.com backup;\n}\nBy default, requests are distributed between the servers using a\nweighted round-robin balancing method.\nIn the above example, each 7 requests will be distributed as follows:\n5 requests go to backend1.example.com\nand one request to each of the second and third servers.\nIf an error occurs during communication with a server, the request will\nbe passed to the next server, and so on until all of the functioning\nservers will be tried.\nIf a successful response could not be obtained from any of the servers,\nthe client will receive the result of the communication with the last server.
address [parameters]
Defines the address and other parameters\nof a server.\nThe address can be specified as a domain name or IP address,\nwith an optional port, or as a UNIX-domain socket path\nspecified after the “unix:” prefix.\nIf a port is not specified, the port 80 is used.\nA domain name that resolves to several IP addresses defines\nmultiple servers at once.
The following parameters can be defined:
\n\nweight=number
sets the weight of the server, by default, 1.
max_conns=number
limits the maximum number of simultaneous active\nconnections to the proxied server (1.11.5).\nDefault value is zero, meaning there is no limit.\nIf the server group does not reside in the shared memory,\nthe limitation works per each worker process.
\n\nIf idle keepalive connections,\nmultiple workers,\nand the shared memory are enabled,\nthe total number of active and idle connections to the proxied server\nmay exceed the
\n\nmax_connsvalue.Since version 1.5.9 and prior to version 1.11.5,\nthis parameter was available as part of our\ncommercial subscription.
\n
max_fails=number
sets the number of unsuccessful attempts to communicate with the server\nthat should happen in the duration set by the fail_timeout\nparameter to consider the server unavailable for a duration also set by the\nfail_timeout parameter.\nBy default, the number of unsuccessful attempts is set to 1.\nThe zero value disables the accounting of attempts.\nWhat is considered an unsuccessful attempt is defined by the\nproxy_next_upstream,\nfastcgi_next_upstream,\nuwsgi_next_upstream,\nscgi_next_upstream,\nmemcached_next_upstream, and\ngrpc_next_upstream\ndirectives.
fail_timeout=time
sets
\n\nBy default, the parameter is set to 10 seconds.
backup
marks the server as a backup server.\nIt will be passed requests when the primary servers are unavailable.
\n\n\n\nThe parameter cannot be used along with the\n
\nhash,ip_hash, andrandom\nload balancing methods.
down
marks the server as permanently unavailable.
Additionally,\nthe following parameters are available as part of our\ncommercial subscription:
\n\nresolve
monitors changes of the IP addresses\nthat correspond to a domain name of the server,\nand automatically modifies the upstream configuration\nwithout the need of restarting nginx (1.5.12).\nThe server group must reside in the shared memory.
\n\nIn order for this parameter to work,\nthe resolver directive\nmust be specified in the\nhttp block\nor in the corresponding upstream block.
route=string
sets the server route name.
service=name
enables resolving of DNS\nSRV\nrecords and sets the service name (1.9.13).\nIn order for this parameter to work, it is necessary to specify\nthe resolve parameter for the server\nand specify a hostname without a port number.
If the service name does not contain a dot (“.”), then\nthe RFC-compliant name\nis constructed\nand the TCP protocol is added to the service prefix.\nFor example, to look up the\n_http._tcp.backend.example.com SRV record,\nit is necessary to specify the directive:
server backend.example.com service=http resolve;\nIf the service name contains one or more dots, then the name is constructed\nby joining the service prefix and the server name.\nFor example, to look up the _http._tcp.backend.example.com\nand server1.backend.example.com SRV records,\nit is necessary to specify the directives:
server backend.example.com service=_http._tcp resolve;\nserver example.com service=server1.backend resolve;\nHighest-priority SRV records\n(records with the same lowest-number priority value)\nare resolved as primary servers,\nthe rest of SRV records are resolved as backup servers.\nIf the backup parameter is specified for the server,\nhigh-priority SRV records are resolved as backup servers,\nthe rest of SRV records are ignored.
slow_start=time
sets the time during which the server will recover its weight\nfrom zero to a nominal value, when unhealthy server becomes\nhealthy,\nor when the server becomes available after a period of time\nit was considered unavailable.\nDefault value is zero, i.e. slow start is disabled.
\n\nThe parameter cannot be used along with the\n
\nhash,ip_hash, andrandom\nload balancing methods.
drain
puts the server into the “draining” mode (1.13.6).\nIn this mode, only requests bound to the server\nwill be proxied to it.
\n\n\n\nPrior to version 1.13.6,\nthe parameter could be changed only with the\nAPI module.
\n
\n\n" @@ -7382,9 +8838,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "*`name`* [*`size`*]" ], + "syntax_html": [ + "If there is only a single server in a group,
\nmax_fails,\nfail_timeoutandslow_startparameters\nare ignored, and such a server will never be considered unavailable.
name [size]
Defines the name and size of the shared\nmemory zone that keeps the group’s configuration and run-time state that are\nshared between worker processes.\nSeveral groups may share the same zone.\nIn this case, it is enough to specify the size only once.
Additionally,\nas part of our commercial subscription,\nsuch groups allow changing the group membership\nor modifying the settings of a particular server\nwithout the need of restarting nginx.\nThe configuration is accessible via the\nAPI module (1.13.3).
\n\n\n\n" @@ -7395,9 +8854,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "Prior to version 1.13.3,\nthe configuration was accessible only via a special location\nhandled by\n
\nupstream_conf.
file
Specifies a file that keeps the state\nof the dynamically configurable group.
Examples:
\n\nstate /var/lib/nginx/state/servers.conf; # path for Linux\nstate /var/db/nginx/state/servers.conf; # path for FreeBSD\nThe state is currently limited to the list of servers with their parameters.\nThe file is read when parsing the configuration and is updated each time\nthe upstream configuration is\nchanged.\nChanging the file content directly should be avoided.\nThe directive cannot be used\nalong with the server directive.
\n\n" @@ -7408,9 +8870,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "*`key`* [`consistent`]" ], + "syntax_html": [ + "Changes made during\nconfiguration reload\nor binary upgrade\ncan be lost.
\n\nThis directive is available as part of our\ncommercial subscription.
\n
key [consistent]
Specifies a load balancing method for a server group\nwhere the client-server mapping is based on the hashed key value.\nThe key can contain text, variables, and their combinations.\nNote that adding or removing a server from the group\nmay result in remapping most of the keys to different servers.\nThe method is compatible with the\nCache::Memcached\nPerl library.
If the consistent parameter is specified,\nthe ketama\nconsistent hashing method will be used instead.\nThe method ensures that only a few keys\nwill be remapped to different servers\nwhen a server is added to or removed from the group.\nThis helps to achieve a higher cache hit ratio for caching servers.\nThe method is compatible with the\nCache::Memcached::Fast\nPerl library with the ketama_points parameter set to 160.
connections
Activates the cache for connections to upstream servers.
\n\nThe connections parameter sets the maximum number of\nidle keepalive connections to upstream servers that are preserved in\nthe cache of each worker process.\nWhen this number is exceeded, the least recently used connections\nare closed.
\n\n\nIt should be particularly noted that the
\n\nkeepalivedirective\ndoes not limit the total number of connections to upstream servers\nthat an nginx worker process can open.\nTheconnectionsparameter should be set to a number small enough\nto let upstream servers process new incoming connections as well.When using load balancing methods other than the default\nround-robin method, it is necessary to activate them before\nthe
\nkeepalivedirective.
Example configuration of memcached upstream with keepalive connections:
\n\nupstream memcached_backend {\n server 127.0.0.1:11211;\n server 10.0.0.2:11211;\n\n keepalive 32;\n}\n\nserver {\n ...\n\n location /memcached/ {\n set $memcached_key $uri;\n memcached_pass memcached_backend;\n }\n\n}\nFor HTTP, the proxy_http_version\ndirective should be set to “1.1”\nand the “Connection” header field should be cleared:
upstream http_backend {\n server 127.0.0.1:8080;\n\n keepalive 16;\n}\n\nserver {\n ...\n\n location /http/ {\n proxy_pass http://http_backend;\n proxy_http_version 1.1;\n proxy_set_header Connection "";\n ...\n }\n}\n\n\n\nAlternatively, HTTP/1.0 persistent connections can be used by passing the\n“Connection: Keep-Alive” header field to an upstream server,\nthough this method is not recommended.
\n
For FastCGI servers, it is required to set\nfastcgi_keep_conn\nfor keepalive connections to work:
upstream fastcgi_backend {\n server 127.0.0.1:9000;\n\n keepalive 8;\n}\n\nserver {\n ...\n\n location /fastcgi/ {\n fastcgi_pass fastcgi_backend;\n fastcgi_keep_conn on;\n ...\n }\n}\n\n\n" @@ -7447,9 +8918,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "SCGI and uwsgi protocols do not have a notion of keepalive connections.
\n
number
Sets the maximum number of requests that can be\nserved through one keepalive connection.\nAfter the maximum number of requests is made, the connection is closed.
\n\nClosing connections periodically is necessary to free\nper-connection memory allocations.\nTherefore, using too high maximum number of requests\ncould result in excessive memory usage and not recommended.
\n\n\n\n" @@ -7460,9 +8934,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "Prior to version 1.19.10, the default value was 100.
\n
time
Limits the maximum time during which\nrequests can be processed through one keepalive connection.\nAfter this time is reached, the connection is closed\nfollowing the subsequent request processing.
\n" @@ -7473,9 +8950,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "*`timeout`*" ], + "syntax_html": [ + "timeout
Sets a timeout during which an idle keepalive\nconnection to an upstream server will stay open.
\n" @@ -7486,7 +8966,10 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ + "" + ], + "syntax_html": [ "" ], "isBlock": false, @@ -7499,7 +8982,10 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ + "" + ], + "syntax_html": [ "" ], "isBlock": false, @@ -7512,9 +8998,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "`header` | `last_byte` [`inflight`]" ], + "syntax_html": [ + "header | last_byte [inflight]
Specifies that a group should use a load balancing method where a request\nis passed to the server with the least average response time and\nleast number of active connections, taking into account weights of servers.\nIf there are several such servers, they are tried in turn using a\nweighted round-robin balancing method.
\n\nIf the header parameter is specified,\ntime to receive the\nresponse header is used.\nIf the last_byte parameter is specified,\ntime to receive the full response\nis used.\nIf the inflight parameter is specified (1.11.6),\nincomplete requests are also taken into account.
\n\n" @@ -7525,9 +9014,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "*`number`* [`timeout`=*`time`*]" ], + "syntax_html": [ + "Prior to version 1.11.6, incomplete requests were taken into account by default.
\n\nThis directive is available as part of our\ncommercial subscription.
\n
number [timeout=time]
If an upstream server cannot be selected immediately\nwhile processing a request,\nthe request will be placed into the queue.\nThe directive specifies the maximum number of requests\nthat can be in the queue at the same time.\nIf the queue is filled up,\nor the server to pass the request to cannot be selected within\nthe time period specified in the timeout parameter,\nthe 502 (Bad Gateway)\nerror will be returned to the client.
The default value of the timeout parameter is 60 seconds.
\n\n" @@ -7538,9 +9030,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "[`two` [*`method`*]]" ], + "syntax_html": [ + "When using load balancer methods other than the default\nround-robin method, it is necessary to activate them before\nthe
\n\nqueuedirective.This directive is available as part of our\ncommercial subscription.
\n
[two [method]]
Specifies that a group should use a load balancing method where a request\nis passed to a randomly selected server, taking into account weights\nof servers.
\n\nThe optional two parameter\ninstructs nginx to randomly select\ntwo\nservers and then choose a server\nusing the specified method.\nThe default method is least_conn\nwhich passes a request to a server\nwith the least number of active connections.
The least_time method passes a request to a server\nwith the least average response time and least number of active connections.\nIf least_time=header is specified, the time to receive the\nresponse header is used.\nIf least_time=last_byte is specified, the time to receive the\nfull response is used.
\n\n" @@ -7551,9 +9046,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "*`address`* ... [`valid`=*`time`*] [`ipv4`=`on`|`off`] [`ipv6`=`on`|`off`] [`status_zone`=*`zone`*]" ], + "syntax_html": [ + "The
\nleast_timemethod is available as a part of our\ncommercial subscription.
address … [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone]
Configures name servers used to resolve names of upstream servers\ninto addresses, for example:
\n\nresolver 127.0.0.1 [::1]:5353;\nThe address can be specified as a domain name or IP address,\nwith an optional port.\nIf port is not specified, the port 53 is used.\nName servers are queried in a round-robin fashion.
\n\nBy default, nginx will look up both IPv4 and IPv6 addresses while resolving.\nIf looking up of IPv4 or IPv6 addresses is not desired,\nthe ipv4=off (1.23.1) or\nthe ipv6=off parameter can be specified.
By default, nginx caches answers using the TTL value of a response.\nAn optional valid parameter allows overriding it:
resolver 127.0.0.1 [::1]:5353 valid=30s;\n\n\n\nTo prevent DNS spoofing, it is recommended\nconfiguring DNS servers in a properly secured trusted local network.
\n
The optional status_zone parameter\nenables\ncollection\nof DNS server statistics of requests and responses\nin the specified zone.
\n\n" @@ -7564,9 +9062,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "This directive is available as part of our\ncommercial subscription.
\n
time
Sets a timeout for name resolution, for example:
\n\nresolver_timeout 5s;\n\n\n" @@ -7577,11 +9078,16 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "`cookie` *`name`* [`expires=`*`time`*] [`domain=`*`domain`*] [`httponly`] [`samesite=``strict`|`lax`|`none`|*`$variable`*] [`secure`] [`path=`*`path`*]", "`route` *`$variable`* ...", "`learn` `create=`*`$variable`* `lookup=`*`$variable`* `zone=`*`name`*:*`size`* [`timeout=`*`time`*] [`header`] [`sync`]" ], + "syntax_html": [ + "This directive is available as part of our\ncommercial subscription.
\n
cookie name [expires=time] [domain=domain] [httponly] [samesite=strict|lax|none|$variable] [secure] [path=path]
route $variable …
learn create=$variable lookup=$variable zone=name:size [timeout=time] [header] [sync]
Enables session affinity, which causes requests from the same client to be\npassed to the same server in a group of servers.\nThree methods are available:
\n\ncookie
When the cookie method is used, information about the\ndesignated server is passed in an HTTP cookie generated by nginx:
upstream backend {\n server backend1.example.com;\n server backend2.example.com;\n\n\n sticky cookie srv_id expires=1h domain=.example.com path=/;\n}\nA request that comes from a client not yet bound to a particular server\nis passed to the server selected by the configured balancing method.\nFurther requests with this cookie will be passed to the designated server.\nIf the designated server cannot process a request, the new server is\nselected as if the client has not been bound yet.
\n\n\n\n\nAs a load balancing method always tries to evenly distribute the load\nconsidering already bound requests,\nthe server with a higher number of active bound requests\nhas less possibility of getting new unbound requests.
\n
The first parameter sets the name of the cookie to be set or inspected.\nThe cookie value is\na hexadecimal representation of the MD5 hash of the IP address and port,\nor of the UNIX-domain socket path.\nHowever, if the “route” parameter of the\nserver directive is specified, the cookie value will be\nthe value of the “route” parameter:
upstream backend {\n server backend1.example.com route=a;\n server backend2.example.com route=b;\n\n\n sticky cookie srv_id expires=1h domain=.example.com path=/;\n}\nIn this case, the value of the “srv_id” cookie will be\neither a or b.
Additional parameters may be as follows:
\n\nexpires=time
Sets the time for which a browser should keep the cookie.\nThe special value max will cause the cookie to expire on\n“31 Dec 2037 23:55:55 GMT”.\nIf the parameter is not specified, it will cause the cookie to expire at\nthe end of a browser session.
domain=domain
Defines the domain for which the cookie is set.\nParameter value can contain variables (1.11.5).
httponly
Adds the HttpOnly attribute to the cookie (1.7.11).
samesite=strict |\nlax | none | $variable
Adds the SameSite (1.19.4) attribute to the cookie\nwith one of the following values:\nStrict,\nLax,\nNone, or\nusing variables (1.23.3).\nIn the latter case, if the variable value is empty,\nthe SameSite attribute will not be added to the cookie,\nif the value is resolved to\nStrict,\nLax, or\nNone,\nthe corresponding value will be assigned,\notherwise the Strict value will be assigned.
secure
Adds the Secure attribute to the cookie (1.7.11).
path=path
Defines the path for which the cookie is set.
If any parameters are omitted, the corresponding cookie fields are not set.
route
When the route method is used, proxied server assigns\nclient a route on receipt of the first request.\nAll subsequent requests from this client will carry routing information\nin a cookie or URI.\nThis information is compared with the “route” parameter\nof the server directive to identify the server to which the\nrequest should be proxied.\nIf the “route” parameter is not specified, the route name\nwill be a hexadecimal representation of the MD5 hash of the IP address and port,\nor of the UNIX-domain socket path.\nIf the designated server cannot process a request, the new server is\nselected by the configured balancing method as if there is no routing\ninformation in the request.
The parameters of the route method specify variables that\nmay contain routing information.\nThe first non-empty variable is used to find the matching server.
Example:
\n\nmap $cookie_jsessionid $route_cookie {\n ~.+\\.(?P<route>\\w+)$ $route;\n}\n\n\nmap $request_uri $route_uri {\n ~jsessionid=.+\\.(?P<route>\\w+)$ $route;\n}\n\n\nupstream backend {\n server backend1.example.com route=a;\n server backend2.example.com route=b;\n\n\n sticky route $route_cookie $route_uri;\n}\nHere, the route is taken from the “JSESSIONID” cookie\nif present in a request.\nOtherwise, the route from the URI is used.
learn
When the learn method (1.7.1) is used, nginx\nanalyzes upstream server responses and learns server-initiated sessions\nusually passed in an HTTP cookie.
upstream backend {\n server backend1.example.com:8080;\n server backend2.example.com:8081;\n\n\n sticky learn\n create=$upstream_cookie_examplecookie\n lookup=$cookie_examplecookie\n zone=client_sessions:1m;\n}\nIn the example, the upstream server creates a session by setting the\ncookie “EXAMPLECOOKIE” in the response.\nFurther requests with this cookie will be passed to the same server.\nIf the server cannot process the request, the new server is\nselected as if the client has not been bound yet.
The parameters create and lookup\nspecify variables that indicate how new sessions are created and existing\nsessions are searched, respectively.\nBoth parameters may be specified more than once, in which case the first\nnon-empty variable is used.
Sessions are stored in a shared memory zone, whose name and\nsize are configured by the zone parameter.\nOne megabyte zone can store about 4000 sessions on the 64-bit platform.\nThe sessions that are not accessed during the time specified by the\ntimeout parameter get removed from the zone.\nBy default, timeout is set to 10 minutes.
The header parameter (1.13.1) allows creating a session\nright after receiving response headers from the upstream server.
The sync parameter (1.13.8) enables\nsynchronization\nof the shared memory zone.
\n\n" @@ -7592,9 +9098,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "*`name`* [`expires=`*`time`*] [`domain=`*`domain`*] [`path=`*`path`*]" ], + "syntax_html": [ + "This directive is available as part of our\ncommercial subscription.
\n
name [expires=time] [domain=domain] [path=path]
This directive is obsolete since version 1.5.7.\nAn equivalent\nsticky directive with a new syntax should be used instead:
\n\n" @@ -7613,9 +9122,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `v1` | `log` | `off`" ], + "syntax_html": [ + "\n
sticky cookiename\n[expires=time]\n[domain=domain]\n[path=path];
on | v1 | log | off
Enables or disables setting cookies and logging the received cookies:
\n\non
enables the setting of version 2 cookies\nand logging of the received cookies;
v1
enables the setting of version 1 cookies\nand logging of the received cookies;
log
disables the setting of cookies,\nbut enables logging of the received cookies;
off
disables the setting of cookies and logging of the received cookies.
name | none
Defines a domain for which the cookie is set.\nThe none parameter disables setting of a domain for the\ncookie.
time | max | off
Sets a time during which a browser should keep the cookie.\nThe parameter max will cause the cookie to expire on\n“31 Dec 2037 23:55:55 GMT”.\nThe parameter off will cause the cookie to expire at\nthe end of a browser session.
off | flag …
If the parameter is not off,\ndefines one or more additional flags for the cookie:\nsecure,\nhttponly,\nsamesite=strict,\nsamesite=lax,\nsamesite=none.
letter | digit | = | off
If the parameter is not off, enables the cookie marking\nmechanism and sets the character used as a mark.\nThis mechanism is used to add or change\nuserid_p3p and/or a cookie expiration time while\npreserving the client identifier.\nA mark can be any letter of the English alphabet (case-sensitive),\ndigit, or the “=” character.
If the mark is set, it is compared with the first padding symbol\nin the base64 representation of the client identifier passed in a cookie.\nIf they do not match, the cookie is resent with the specified mark,\nexpiration time, and “P3P” header.
\n" @@ -7688,9 +9212,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`name`*" ], + "syntax_html": [ + "name
Sets the cookie name.
\n" @@ -7703,9 +9230,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`string`* | `none`" ], + "syntax_html": [ + "string | none
Sets a value for the “P3P” header field that will be\nsent along with the cookie.\nIf the directive is set to the special value none,\nthe “P3P” header will not be sent in a response.
path
Defines a path for which the cookie is set.
\n" @@ -7733,9 +9266,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
If identifiers are issued by multiple servers (services),\neach service should be assigned its own number\nto ensure that client identifiers are unique.\nFor version 1 cookies, the default value is zero.\nFor version 2 cookies, the default value is the number composed from the last\nfour octets of the server’s IP address.
address [transparent] | off
Makes outgoing connections to a uwsgi server originate\nfrom the specified local IP address with an optional port (1.11.2).\nParameter value can contain variables (1.3.12).\nThe special value off (1.3.12) cancels the effect\nof the uwsgi_bind directive\ninherited from the previous configuration level, which allows the\nsystem to auto-assign the local IP address and port.
The transparent parameter (1.11.0) allows\noutgoing connections to a uwsgi server originate\nfrom a non-local IP address,\nfor example, from a real IP address of a client:
uwsgi_bind $remote_addr transparent;\nIn order for this parameter to work,\nit is usually necessary to run nginx worker processes with the\nsuperuser privileges.\nOn Linux it is not required (1.13.8) as if\nthe transparent parameter is specified, worker processes\ninherit the CAP_NET_RAW capability from the master process.\nIt is also necessary to configure kernel routing table\nto intercept network traffic from the uwsgi server.
size
Sets the size of the buffer used for reading the first part\nof the response received from the uwsgi server.\nThis part usually contains a small response header.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.\nIt can be made smaller, however.
on | off
Enables or disables buffering of responses from the uwsgi server.
\n\nWhen buffering is enabled, nginx receives a response from the uwsgi server\nas soon as possible, saving it into the buffers set by the\nuwsgi_buffer_size and uwsgi_buffers directives.\nIf the whole response does not fit into memory, a part of it can be saved\nto a temporary file on the disk.\nWriting to temporary files is controlled by the\nuwsgi_max_temp_file_size and\nuwsgi_temp_file_write_size directives.
When buffering is disabled, the response is passed to a client synchronously,\nimmediately as it is received.\nnginx will not try to read the whole response from the uwsgi server.\nThe maximum size of the data that nginx can receive from the server\nat a time is set by the uwsgi_buffer_size directive.
Buffering can also be enabled or disabled by passing\n“yes” or “no” in the\n“X-Accel-Buffering” response header field.\nThis capability can be disabled using the\nuwsgi_ignore_headers directive.
number size
Sets the number and size of the\nbuffers used for reading a response from the uwsgi server,\nfor a single connection.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.
size
When buffering of responses from the uwsgi\nserver is enabled, limits the total size of buffers that\ncan be busy sending a response to the client while the response is not\nyet fully read.\nIn the meantime, the rest of the buffers can be used for reading the response\nand, if needed, buffering part of the response to a temporary file.\nBy default, size is limited by the size of two buffers set by the\nuwsgi_buffer_size and uwsgi_buffers directives.
zone | off
Defines a shared memory zone used for caching.\nThe same zone can be used in several places.\nParameter value can contain variables (1.7.9).\nThe off parameter disables caching inherited\nfrom the previous configuration level.
on | off
Allows starting a background subrequest\nto update an expired cache item,\nwhile a stale cached response is returned to the client.\nNote that it is necessary to\nallow\nthe usage of a stale cached response when it is being updated.
\n" @@ -7859,9 +9416,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`string`* ..." ], + "syntax_html": [ + "string …
Defines conditions under which the response will not be taken from a cache.\nIf at least one value of the string parameters is not empty and is not\nequal to “0” then the response will not be taken from the cache:
\n\nuwsgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;\nuwsgi_cache_bypass $http_pragma $http_authorization;\nCan be used along with the uwsgi_no_cache directive.
string
Defines a key for caching, for example
\n\nuwsgi_cache_key localhost:9000$request_uri;\non | off
When enabled, only one request at a time will be allowed to populate\na new cache element identified according to the uwsgi_cache_key\ndirective by passing a request to a uwsgi server.\nOther requests of the same cache element will either wait\nfor a response to appear in the cache or the cache lock for\nthis element to be released, up to the time set by the\nuwsgi_cache_lock_timeout directive.
time
If the last request passed to the uwsgi server\nfor populating a new cache element\nhas not completed for the specified time,\none more request may be passed to the uwsgi server.
time
Sets a timeout for uwsgi_cache_lock.\nWhen the time expires,\nthe request will be passed to the uwsgi server,\nhowever, the response will not be cached.
\n\n" @@ -7934,9 +9506,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "Before 1.7.8, the response could be cached.
\n
number
Sets an offset in bytes for byte-range requests.\nIf the range is beyond the offset,\nthe range request will be passed to the uwsgi server\nand the response will not be cached.
\n" @@ -7949,9 +9524,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`GET` | `HEAD` | `POST` ..." ], + "syntax_html": [ + "GET | HEAD | POST …
If the client request method is listed in this directive then\nthe response will be cached.\n“GET” and “HEAD” methods are always\nadded to the list, though it is recommended to specify them explicitly.\nSee also the uwsgi_no_cache directive.
number
Sets the number of requests after which the response\nwill be cached.
path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [min_free=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time]
Sets the path and other parameters of a cache.\nCache data are stored in files.\nThe file name in a cache is a result of\napplying the MD5 function to the\ncache key.\nThe levels parameter defines hierarchy levels of a cache:\nfrom 1 to 3, each level accepts values 1 or 2.\nFor example, in the following configuration
uwsgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;\nfile names in a cache will look like this:
\n\n/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c\nA cached response is first written to a temporary file,\nand then the file is renamed.\nStarting from version 0.8.9, temporary files and the cache can be put on\ndifferent file systems.\nHowever, be aware that in this case a file is copied\nacross two file systems instead of the cheap renaming operation.\nIt is thus recommended that for any given location both cache and a directory\nholding temporary files\nare put on the same file system.\nA directory for temporary files is set based on\nthe use_temp_path parameter (1.7.10).\nIf this parameter is omitted or set to the value on,\nthe directory set by the uwsgi_temp_path directive\nfor the given location will be used.\nIf the value is set to off,\ntemporary files will be put directly in the cache directory.
In addition, all active keys and information about data are stored\nin a shared memory zone, whose name and size\nare configured by the keys_zone parameter.\nOne megabyte zone can store about 8 thousand keys.
\n\n\nAs part of\ncommercial subscription,\nthe shared memory zone also stores extended\ncache information,\nthus, it is required to specify a larger zone size for the same number of keys.\nFor example,\none megabyte zone can store about 4 thousand keys.
\n
Cached data that are not accessed during the time specified by the\ninactive parameter get removed from the cache\nregardless of their freshness.\nBy default, inactive is set to 10 minutes.
The special “cache manager” process monitors the maximum cache size set\nby the max_size parameter,\nand the minimum amount of free space set\nby the min_free (1.19.1) parameter\non the file system with cache.\nWhen the size is exceeded or there is not enough free space,\nit removes the least recently used data.\nThe data is removed in iterations configured by\nmanager_files,\nmanager_threshold, and\nmanager_sleep parameters (1.11.5).\nDuring one iteration no more than manager_files items\nare deleted (by default, 100).\nThe duration of one iteration is limited by the\nmanager_threshold parameter (by default, 200 milliseconds).\nBetween iterations, a pause configured by the manager_sleep\nparameter (by default, 50 milliseconds) is made.
A minute after the start the special “cache loader” process is activated.\nIt loads information about previously cached data stored on file system\ninto a cache zone.\nThe loading is also done in iterations.\nDuring one iteration no more than loader_files items\nare loaded (by default, 100).\nBesides, the duration of one iteration is limited by the\nloader_threshold parameter (by default, 200 milliseconds).\nBetween iterations, a pause configured by the loader_sleep\nparameter (by default, 50 milliseconds) is made.
Additionally,\nthe following parameters are available as part of our\ncommercial subscription:
\n\npurger=on|off
Instructs whether cache entries that match a\nwildcard key\nwill be removed from the disk by the cache purger (1.7.12).\nSetting the parameter to on\n(default is off)\nwill activate the “cache purger” process that\npermanently iterates through all cache entries\nand deletes the entries that match the wildcard key.
purger_files=number
Sets the number of items that will be scanned during one iteration (1.7.12).\nBy default, purger_files is set to 10.
purger_threshold=number
Sets the duration of one iteration (1.7.12).\nBy default, purger_threshold is set to 50 milliseconds.
purger_sleep=number
Sets a pause between iterations (1.7.12).\nBy default, purger_sleep is set to 50 milliseconds.
\n\n" @@ -7992,9 +9576,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "string ..." ], + "syntax_html": [ + "In versions 1.7.3, 1.7.7, and 1.11.10 cache header format has been changed.\nPreviously cached responses will be considered invalid\nafter upgrading to a newer nginx version.
\n
string …
\n" + ], "isBlock": false, "description_md": "Defines conditions under which the request will be considered a cache\npurge request.\nIf at least one value of the string parameters is not empty and is not equal\nto “0” then the cache entry with a corresponding\n[cache key](https://nginx.org/en/docs/http/ngx_http_uwsgi_module.html#uwsgi_cache_key) is removed.\nThe result of successful operation is indicated by returning\nthe 204 (No Content) response.\n\nIf the [cache key](https://nginx.org/en/docs/http/ngx_http_uwsgi_module.html#uwsgi_cache_key) of a purge request ends\nwith an asterisk (“`*`”), all cache entries matching the\nwildcard key will be removed from the cache.\nHowever, these entries will remain on the disk until they are deleted\nfor either [inactivity](https://nginx.org/en/docs/http/ngx_http_uwsgi_module.html#uwsgi_cache_path),\nor processed by the [cache purger](https://nginx.org/en/docs/http/ngx_http_uwsgi_module.html#purger) (1.7.12),\nor a client attempts to access them.\n\nExample configuration:\n```\nuwsgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;\n\nmap $request_method $purge_method {\n PURGE 1;\n default 0;\n}\n\nserver {\n ...\n location / {\n uwsgi_pass backend;\n uwsgi_cache cache_zone;\n uwsgi_cache_key $uri;\n uwsgi_cache_purge $purge_method;\n }\n}\n```\n> This functionality is available as part of our\n> [commercial subscription](https://nginx.com/products/).", "description_html": "Defines conditions under which the request will be considered a cache\npurge request.\nIf at least one value of the string parameters is not empty and is not equal\nto “0” then the cache entry with a corresponding\ncache key is removed.\nThe result of successful operation is indicated by returning\nthe 204 (No Content) response.
\n\nIf the cache key of a purge request ends\nwith an asterisk (“*”), all cache entries matching the\nwildcard key will be removed from the cache.\nHowever, these entries will remain on the disk until they are deleted\nfor either inactivity,\nor processed by the cache purger (1.7.12),\nor a client attempts to access them.
Example configuration:
\n\nuwsgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;\n\nmap $request_method $purge_method {\n PURGE 1;\n default 0;\n}\n\nserver {\n ...\n location / {\n uwsgi_pass backend;\n uwsgi_cache cache_zone;\n uwsgi_cache_key $uri;\n uwsgi_cache_purge $purge_method;\n }\n}\n\n\n" @@ -8007,9 +9594,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "This functionality is available as part of our\ncommercial subscription.
\n
on | off
Enables revalidation of expired cache items using conditional requests with\nthe “If-Modified-Since” and “If-None-Match”\nheader fields.
\n" @@ -8022,9 +9612,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`error` | `timeout` | `invalid_header` | `updating` | `http_500` | `http_503` | `http_403` | `http_404` | `http_429` | `off` ..." ], + "syntax_html": [ + "error | timeout | invalid_header | updating | http_500 | http_503 | http_403 | http_404 | http_429 | off …
Determines in which cases a stale cached response can be used\nwhen an error occurs during communication with the uwsgi server.\nThe directive’s parameters match the parameters of the\nuwsgi_next_upstream directive.
The error parameter also permits\nusing a stale cached response if a uwsgi server to process a request\ncannot be selected.
Additionally, the updating parameter permits\nusing a stale cached response if it is currently being updated.\nThis allows minimizing the number of accesses to uwsgi servers\nwhen updating cached data.
Using a stale cached response\ncan also be enabled directly in the response header\nfor a specified number of seconds after the response became stale (1.11.10).\nThis has lower priority than using the directive parameters.
\n\nTo minimize the number of accesses to uwsgi servers when\npopulating a new cache element, the uwsgi_cache_lock\ndirective can be used.
[code …] time
Sets caching time for different response codes.\nFor example, the following directives
\n\nuwsgi_cache_valid 200 302 10m;\nuwsgi_cache_valid 404 1m;\nset 10 minutes of caching for responses with codes 200 and 302\nand 1 minute for responses with code 404.
\n\nIf only caching time is specified
uwsgi_cache_valid 5m;\nthen only 200, 301, and 302 responses are cached.
\n\nIn addition, the any parameter can be specified\nto cache any responses:
uwsgi_cache_valid 200 302 10m;\nuwsgi_cache_valid 301 1h;\nuwsgi_cache_valid any 1m;\nParameters of caching can also be set directly\nin the response header.\nThis has higher priority than setting of caching time using the directive.
\n\n@ prefix, it sets an absolute\ntime in seconds since Epoch, up to which the response may be cached.*”, such a\nresponse will not be cached (1.7.7).\nIf the header includes the “Vary” field\nwith another value, such a response will be cached\ntaking into account the corresponding request header fields (1.7.7).Processing of one or more of these response header fields can be disabled\nusing the uwsgi_ignore_headers directive.
time
Defines a timeout for establishing a connection with a uwsgi server.\nIt should be noted that this timeout cannot usually exceed 75 seconds.
\n" @@ -8067,9 +9666,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables byte-range support\nfor both cached and uncached responses from the uwsgi server\nregardless of the “Accept-Ranges” field in these responses.
\n" @@ -8082,9 +9684,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`field`*" ], + "syntax_html": [ + "field
By default,\nnginx does not pass the header fields “Status” and\n“X-Accel-…” from the response of a uwsgi\nserver to a client.\nThe uwsgi_hide_header directive sets additional fields\nthat will not be passed.\nIf, on the contrary, the passing of fields needs to be permitted,\nthe uwsgi_pass_header directive can be used.
on | off
Determines whether the connection with a uwsgi server should be\nclosed when a client closes the connection without waiting\nfor a response.
\n" @@ -8112,9 +9720,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`field`* ..." ], + "syntax_html": [ + "field …
Disables processing of certain response header fields from the uwsgi server.\nThe following fields can be ignored: “X-Accel-Redirect”,\n“X-Accel-Expires”, “X-Accel-Limit-Rate” (1.1.6),\n“X-Accel-Buffering” (1.1.6),\n“X-Accel-Charset” (1.1.6), “Expires”,\n“Cache-Control”, “Set-Cookie” (0.8.44),\nand “Vary” (1.7.7).
\n\nIf not disabled, processing of these header fields has the following\neffect:
\n\ncharset\nof a response.on | off
Determines whether a uwsgi server responses with codes greater than or equal\nto 300 should be passed to a client\nor be intercepted and redirected to nginx for processing\nwith the error_page directive.
rate
Limits the speed of reading the response from the uwsgi server.\nThe rate is specified in bytes per second.\nThe zero value disables rate limiting.\nThe limit is set per a request, and so if nginx simultaneously opens\ntwo connections to the uwsgi server,\nthe overall rate will be twice as much as the specified limit.\nThe limitation works only if\nbuffering of responses from the uwsgi\nserver is enabled.
size
When buffering of responses from the uwsgi\nserver is enabled, and the whole response does not fit into the buffers\nset by the uwsgi_buffer_size and uwsgi_buffers\ndirectives, a part of the response can be saved to a temporary file.\nThis directive sets the maximum size of the temporary file.\nThe size of data written to the temporary file at a time is set\nby the uwsgi_temp_file_write_size directive.
The zero value disables buffering of responses to temporary files.
\n\n\n\n" @@ -8172,9 +9792,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "This restriction does not apply to responses\nthat will be cached\nor stored on disk.
\n
number
Sets the value of the modifier1 field in the\nuwsgi packet header.
number
Sets the value of the modifier2 field in the\nuwsgi packet header.
error | timeout | invalid_header | http_500 | http_503 | http_403 | http_404 | http_429 | non_idempotent | off …
Specifies in which cases a request should be passed to the next server:
\n\nerror
an error occurred while establishing a connection with the\nserver, passing a request to it, or reading the response header;
timeout
a timeout has occurred while establishing a connection with the\nserver, passing a request to it, or reading the response header;
invalid_header
a server returned an empty or invalid response;
http_500
a server returned a response with the code 500;
http_503
a server returned a response with the code 503;
http_403
a server returned a response with the code 403;
http_404
a server returned a response with the code 404;
http_429
a server returned a response with the code 429 (1.11.13);
non_idempotent
normally, requests with a\nnon-idempotent\nmethod\n(POST, LOCK, PATCH)\nare not passed to the next server\nif a request has been sent to an upstream server (1.9.13);\nenabling this option explicitly allows retrying such requests;
off
disables passing a request to the next server.
One should bear in mind that passing a request to the next server is\nonly possible if nothing has been sent to a client yet.\nThat is, if an error or timeout occurs in the middle of the\ntransferring of a response, fixing this is impossible.
\n\nThe directive also defines what is considered an\nunsuccessful attempt of communication with a server.\nThe cases of error, timeout and\ninvalid_header are always considered unsuccessful attempts,\neven if they are not specified in the directive.\nThe cases of http_500, http_503,\nand http_429 are\nconsidered unsuccessful attempts only if they are specified in the directive.\nThe cases of http_403 and http_404\nare never considered unsuccessful attempts.
Passing a request to the next server can be limited by\nthe number of tries\nand by time.
\n" @@ -8217,9 +9846,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Limits the time during which a request can be passed to the\nnext server.\nThe 0 value turns off this limitation.
number
Limits the number of possible tries for passing a request to the\nnext server.\nThe 0 value turns off this limitation.
string …
Defines conditions under which the response will not be saved to a cache.\nIf at least one value of the string parameters is not empty and is not\nequal to “0” then the response will not be saved:
\n\nuwsgi_no_cache $cookie_nocache $arg_nocache$arg_comment;\nuwsgi_no_cache $http_pragma $http_authorization;\nCan be used along with the uwsgi_cache_bypass directive.
parameter value [if_not_empty]
Sets a parameter that should be passed to the uwsgi server.\nThe value can contain text, variables, and their combination.\nThese directives are inherited from the previous configuration level\nif and only if there are no uwsgi_param directives\ndefined on the current level.
Standard\nCGI environment variables\nshould be provided as uwsgi headers, see the uwsgi_params file\nprovided in the distribution:
location / {\n include uwsgi_params;\n ...\n}\nIf the directive is specified with if_not_empty (1.1.11) then\nsuch a parameter will be passed to the server only if its value is not empty:
uwsgi_param HTTPS $https if_not_empty;\n[protocol://]address
Sets the protocol and address of a uwsgi server.\nAs a protocol,\n“uwsgi” or “suwsgi”\n(secured uwsgi, uwsgi over SSL) can be specified.\nThe address can be specified as a domain name or IP address,\nand a port:
uwsgi_pass localhost:9000;\nuwsgi_pass uwsgi://localhost:9000;\nuwsgi_pass suwsgi://[2001:db8::1]:9090;\nor as a UNIX-domain socket path:
\n\nuwsgi_pass unix:/tmp/uwsgi.socket;\nIf a domain name resolves to several addresses, all of them will be\nused in a round-robin fashion.\nIn addition, an address can be specified as a\nserver group.
\n\nParameter value can contain variables.\nIn this case, if an address is specified as a domain name,\nthe name is searched among the described\nserver groups,\nand, if not found, is determined using a\nresolver.
\n\n" @@ -8291,9 +9935,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`field`*" ], + "syntax_html": [ + "Secured uwsgi protocol is supported since version 1.5.8.
\n
field
Permits passing otherwise disabled header\nfields from a uwsgi server to a client.
\n" @@ -8306,9 +9953,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Indicates whether the original request body is passed\nto the uwsgi server.\nSee also the uwsgi_pass_request_headers directive.
on | off
Indicates whether the header fields of the original request are passed\nto the uwsgi server.\nSee also the uwsgi_pass_request_body directive.
time
Defines a timeout for reading a response from the uwsgi server.\nThe timeout is set only between two successive read operations,\nnot for the transmission of the whole response.\nIf the uwsgi server does not transmit anything within this time,\nthe connection is closed.
\n" @@ -8351,9 +10007,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables buffering of a client request body.
\n\nWhen buffering is enabled, the entire request body is\nread\nfrom the client before sending the request to a uwsgi server.
\n\nWhen buffering is disabled, the request body is sent to the uwsgi server\nimmediately as it is received.\nIn this case, the request cannot be passed to the\nnext server\nif nginx already started sending the request body.
\n\nWhen HTTP/1.1 chunked transfer encoding is used\nto send the original request body,\nthe request body will be buffered regardless of the directive value.
\n" @@ -8366,9 +10025,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Sets a timeout for transmitting a request to the uwsgi server.\nThe timeout is set only between two successive write operations,\nnot for the transmission of the whole request.\nIf the uwsgi server does not receive anything within this time,\nthe connection is closed.
\n" @@ -8381,9 +10043,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Configures the “TCP keepalive” behavior\nfor outgoing connections to a uwsgi server.\nBy default, the operating system’s settings are in effect for the socket.\nIf the directive is set to the value “on”, the\nSO_KEEPALIVE socket option is turned on for the socket.
file
Specifies a file with the certificate in the PEM format\nused for authentication to a secured uwsgi server.
Since version 1.21.0, variables can be used in the file name.
file
Specifies a file with the secret key in the PEM format\nused for authentication to a secured uwsgi server.
The value\nengine:name:id\ncan be specified instead of the file (1.7.9),\nwhich loads a secret key with a specified id\nfrom the OpenSSL engine name.
Since version 1.21.0, variables can be used in the file name.
ciphers
Specifies the enabled ciphers for requests to a secured uwsgi server.\nThe ciphers are specified in the format understood by the OpenSSL library.
\n\nThe full list can be viewed using the\n“openssl ciphers” command.
name value
Sets arbitrary OpenSSL configuration\ncommands\nwhen establishing a connection with the secured uwsgi server.
\n\n\n\n\nThe directive is supported when using OpenSSL 1.0.2 or higher.
\n
Several uwsgi_ssl_conf_command directives\ncan be specified on the same level.\nThese directives are inherited from the previous configuration level\nif and only if there are\nno uwsgi_ssl_conf_command directives\ndefined on the current level.
\n\n" @@ -8456,9 +10133,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "Note that configuring OpenSSL directly\nmight result in unexpected behavior.
\n
file
Specifies a file with revoked certificates (CRL)\nin the PEM format used to verify\nthe certificate of the secured uwsgi server.
name
Allows overriding the server name used to\nverify\nthe certificate of the secured uwsgi server and to be\npassed through SNI\nwhen establishing a connection with the secured uwsgi server.
\n\nBy default, the host part from uwsgi_pass is used.
file
Specifies a file with passphrases for\nsecret keys\nwhere each passphrase is specified on a separate line.\nPassphrases are tried in turn when loading the key.
[SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]
Enables the specified protocols for requests to a secured uwsgi server.
\n\n\n\n" @@ -8516,9 +10205,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "The
\nTLSv1.3parameter is used by default\nsince 1.23.4.
on | off
Enables or disables passing of the server name through\nTLS Server Name Indication extension (SNI, RFC 6066)\nwhen establishing a connection with the secured uwsgi server.
\n" @@ -8531,9 +10223,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Determines whether SSL sessions can be reused when working with\na secured uwsgi server.\nIf the errors\n“SSL3_GET_FINISHED:digest check failed”\nappear in the logs, try disabling session reuse.
file
Specifies a file with trusted CA certificates in the PEM format\nused to verify\nthe certificate of the secured uwsgi server.
on | off
Enables or disables verification of the secured uwsgi server certificate.
\n" @@ -8576,9 +10277,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
Sets the verification depth in the secured uwsgi server certificates chain.
\n" @@ -8591,9 +10295,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "`on` | `off` | *`string`*" ], + "syntax_html": [ + "on | off | string
Enables saving of files to a disk.\nThe on parameter saves files with paths\ncorresponding to the directives\nalias or\nroot.\nThe off parameter disables saving of files.\nIn addition, the file name can be set explicitly using the\nstring with variables:
uwsgi_store /data/www$original_uri;\nThe modification time of files is set according to the received\n“Last-Modified” response header field.\nThe response is first written to a temporary file,\nand then the file is renamed.\nStarting from version 0.8.9, temporary files and the persistent store\ncan be put on different file systems.\nHowever, be aware that in this case a file is copied\nacross two file systems instead of the cheap renaming operation.\nIt is thus recommended that for any given location both saved files and a\ndirectory holding temporary files, set by the uwsgi_temp_path\ndirective, are put on the same file system.
This directive can be used to create local copies of static unchangeable\nfiles, e.g.:
\n\nlocation /images/ {\n root /data/www;\n error_page 404 = /fetch$uri;\n}\n\nlocation /fetch/ {\n internal;\n\n uwsgi_pass backend:9000;\n ...\n\n uwsgi_store on;\n uwsgi_store_access user:rw group:rw all:r;\n uwsgi_temp_path /data/temp;\n\n alias /data/www/;\n}\nusers:permissions …
Sets access permissions for newly created files and directories, e.g.:
\n\nuwsgi_store_access user:rw group:rw all:r;\nIf any group or all access permissions\nare specified then user permissions may be omitted:
uwsgi_store_access group:rw all:r;\nsize
Limits the size of data written to a temporary file\nat a time, when buffering of responses from the uwsgi server\nto temporary files is enabled.\nBy default, size is limited by two buffers set by the\nuwsgi_buffer_size and uwsgi_buffers directives.\nThe maximum size of a temporary file is set by the\nuwsgi_max_temp_file_size directive.
path [level1 [level2 [level3]]]
Defines a directory for storing temporary files\nwith data received from uwsgi servers.\nUp to three-level subdirectory hierarchy can be used underneath the specified\ndirectory.\nFor example, in the following configuration
\n\nuwsgi_temp_path /spool/nginx/uwsgi_temp 1 2;\na temporary file might look like this:
\n\n/spool/nginx/uwsgi_temp/7/45/00000123457\nSee also the use_temp_path parameter of the\nuwsgi_cache_path directive.
on | off
Enables\nthe HTTP/2\nprotocol.
\n" @@ -8670,9 +10389,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
Sets the size of the buffer per each request\nin which the request body may be saved\nbefore it is started to be processed.
size
Sets the maximum size of chunks\ninto which the response body is sliced.\nA too low value results in higher overhead.\nA too high value impairs prioritization due to\n HOL blocking.
\n" @@ -8699,9 +10424,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
\n\n\nThis directive is obsolete since version 1.19.7.\nThe
\nkeepalive_timeout\ndirective should be used instead.
Sets the timeout of inactivity after which the connection is closed.
\n" @@ -8713,9 +10441,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
\n\n\nThis directive is obsolete since version 1.25.1.
\n
Limits the maximum number of concurrent\npush requests in a connection.
\n" @@ -8727,9 +10458,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
Sets the maximum number of concurrent HTTP/2 streams\nin a connection.
\n" @@ -8741,9 +10475,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
\n\n\nThis directive is obsolete since version 1.19.7.\nThe
\nlarge_client_header_buffers\ndirective should be used instead.
Limits the maximum size of\nan HPACK-compressed\nrequest header field.\nThe limit applies equally to both name and value.\nNote that if Huffman encoding is applied,\nthe actual size of decompressed name and value strings may be larger.\nFor most requests, the default limit should be enough.
\n" @@ -8755,9 +10492,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
\n\n\nThis directive is obsolete since version 1.19.7.\nThe
\nlarge_client_header_buffers\ndirective should be used instead.
Limits the maximum size of the entire request header list after\nHPACK decompression.\nFor most requests, the default limit should be enough.
\n" @@ -8769,9 +10509,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
\n\n\nThis directive is obsolete since version 1.19.7.\nThe
\nkeepalive_requests\ndirective should be used instead.
Sets the maximum number of requests (including\npush requests) that can be served\nthrough one HTTP/2 connection,\nafter which the next client request will lead to connection closing\nand the need of establishing a new connection.
\n\nClosing connections periodically is necessary to free\nper-connection memory allocations.\nTherefore, using too high maximum number of requests\ncould result in excessive memory usage and not recommended.
\n" @@ -8784,9 +10527,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`uri`* | `off`" ], + "syntax_html": [ + "uri | off
\n\n\nThis directive is obsolete since version 1.25.1.
\n
Pre-emptively sends\n(pushes)\na request to the specified uri\nalong with the response to the original request.\nOnly relative URIs with absolute path will be processed,\nfor example:
http2_push /static/css/main.css;\nThe uri value can contain variables.
Several http2_push directives\ncan be specified on the same configuration level.\nThe off parameter cancels the effect\nof the http2_push directives\ninherited from the previous configuration level.
on | off
\n\n\nThis directive is obsolete since version 1.25.1.
\n
Enables automatic conversion of\npreload links\nspecified in the “Link” response header fields into\npush\nrequests.
\n" @@ -8812,9 +10561,12 @@ "contexts": [ "http" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
Sets the size of the per\nworker\ninput buffer.
\n" @@ -8826,9 +10578,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
\n\n\nThis directive is obsolete since version 1.19.7.\nThe
\nclient_header_timeout\ndirective should be used instead.
Sets the timeout for expecting more data from the client,\nafter which the connection is closed.
\n" @@ -8846,9 +10601,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables\nHTTP/3\nprotocol negotiation.
\n" @@ -8860,9 +10618,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables HTTP/0.9 protocol negotiation\nused in\nQUIC interoperability tests.
\n" @@ -8874,9 +10635,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
Sets the maximum number of concurrent HTTP/3 request streams\nin a connection.
\n" @@ -8888,9 +10652,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
Sets the size of the buffer used for reading and writing of the\nQUIC streams.
\n" @@ -8902,9 +10669,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
Sets the\nQUIC active_connection_id_limit transport parameter value.\nThis is the maximum number of client connection IDs\nwhich can be stored on the server.
on | off
Enables routing of QUIC packets using\neBPF.\nWhen enabled, this allows supporting QUIC connection migration.
\n\n\n\n" @@ -8929,9 +10702,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "The directive is only supported on Linux 5.7+.
\n
on | off
Enables sending in optimized batch mode\nusing segmentation offloading.
\n\n\n\n" @@ -8943,9 +10719,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "Optimized sending is supported only on Linux\nfeaturing
\nUDP_SEGMENT.
file
Sets a file with the secret key used to encrypt\nstateless reset and address validation tokens.\nBy default, a random key is generated on each reload.\nTokens generated with old keys are not accepted.
on | off
Enables the\nQUIC Address Validation feature.\nThis includes sending a new token in a Retry packet\nor a NEW_TOKEN frame\nand\nvalidating a token received in the Initial packet.
path
Specifies the DTD file that declares character entities.\nThis file is compiled at the configuration stage.\nFor technical reasons, the module is unable to use the\nexternal subset declared in the processed XML, so it is\nignored and a specially defined file is used instead.\nThis file should not describe the XML structure.\nIt is enough to declare just the required character entities, for example:
\n\n<!ENTITY nbsp " ">\non | off
Allows preserving the “Last-Modified” header field\nfrom the original response during XSLT transformations\nto facilitate response caching.
\n\nBy default, the header field is removed as contents of the response\nare modified during transformations and may contain dynamically generated\nelements or parts that are changed independently of the original response.
\n" @@ -9008,9 +10796,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`parameter`* *`value`*" ], + "syntax_html": [ + "parameter value
Defines the parameters for XSLT stylesheets.\nThe value is treated as an XPath expression.\nThe value can contain variables.\nTo pass a string value to a stylesheet,\nthe xslt_string_param directive can be used.
There could be several xslt_param directives.\nThese directives are inherited from the previous configuration level\nif and only if there are no xslt_param and\nxslt_string_param directives\ndefined on the current level.
parameter value
Defines the string parameters for XSLT stylesheets.\nXPath expressions in the value are not interpreted.\nThe value can contain variables.
There could be several xslt_string_param directives.\nThese directives are inherited from the previous configuration level\nif and only if there are no xslt_param and\nxslt_string_param directives\ndefined on the current level.
stylesheet [parameter=value …]
Defines the XSLT stylesheet and its optional parameters.\nA stylesheet is compiled at the configuration stage.
\n\nParameters can either be specified separately, or grouped in a\nsingle line using the “:” delimiter.\nIf a parameter includes the “:” character,\nit should be escaped as “%3A”.\nAlso, libxslt requires to enclose parameters\nthat contain non-alphanumeric characters into single or double quotes,\nfor example:
param1='http%3A//www.example.com':param2=value2\nThe parameters description can contain variables, for example,\nthe whole line of parameters can be taken from a single variable:
\n\nlocation / {\n xslt_stylesheet /site/xslt/one.xslt\n $arg_xslt_params\n param1='$value1':param2=value2\n param3=value3;\n}\nIt is possible to specify several stylesheets.\nThey will be applied sequentially in the specified order.
\n" @@ -9051,9 +10848,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`mime-type`* ..." ], + "syntax_html": [ + "mime-type …
Enables transformations in responses with the specified MIME types\nin addition to “text/xml”.\nThe special value “*” matches any MIME type (0.8.29).\nIf the transformation result is an HTML response, its MIME type\nis changed to “text/html”.
URL
Sets the URL of the HTTP authentication server.\nThe protocol is described below.
\n" @@ -9085,9 +10888,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "*`header`* *`value`*" ], + "syntax_html": [ + "header value
Appends the specified header to requests sent to the authentication server.\nThis header can be used as the shared secret to verify\nthat the request comes from nginx.\nFor example:
\n\nauth_http_header X-Auth-Key "secret_string";\non | off
Appends the “Auth-SSL-Cert” header with the\nclient\ncertificate in the PEM format (urlencoded)\nto requests sent to the authentication server.
\n" @@ -9113,9 +10922,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Sets the timeout for communication with the authentication server.
\n" @@ -9132,9 +10944,12 @@ "contexts": [ "server" ], - "syntax": [ + "syntax_md": [ "*`address`*:*`port`* [`ssl`] [`proxy_protocol`] [`backlog`=*`number`*] [`rcvbuf`=*`size`*] [`sndbuf`=*`size`*] [`bind`] [`ipv6only`=`on`|`off`] [`so_keepalive`=`on`|`off`|[*`keepidle`*]:[*`keepintvl`*]:[*`keepcnt`*]]" ], + "syntax_html": [ + "address:port [ssl] [proxy_protocol] [backlog=number] [rcvbuf=size] [sndbuf=size] [bind] [ipv6only=on|off] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]]
Sets the address and port for the socket\non which the server will accept requests.\nIt is possible to specify just the port.\nThe address can also be a hostname, for example:
listen 127.0.0.1:110;\nlisten *:110;\nlisten 110; # same as *:110\nlisten localhost:110;\nIPv6 addresses (0.7.58) are specified in square brackets:
\n\nlisten [::1]:110;\nlisten [::]:110;\nUNIX-domain sockets (1.3.5) are specified with the “unix:”\nprefix:
listen unix:/var/run/nginx.sock;\nDifferent servers must listen on different\naddress:port pairs.
The ssl parameter allows specifying that all\nconnections accepted on this port should work in SSL mode.
The proxy_protocol parameter (1.19.8)\nallows specifying that all connections accepted on this port should use the\nPROXY protocol.\nObtained information is passed to the\nauthentication server\nand can be used to\nchange the client address.
The listen directive\ncan have several additional parameters specific to socket-related system calls.
backlog=number
sets the backlog parameter in the\nlisten() call that limits\nthe maximum length for the queue of pending connections (1.9.2).\nBy default,\nbacklog is set to -1 on FreeBSD, DragonFly BSD, and macOS,\nand to 511 on other platforms.
rcvbuf=size
sets the receive buffer size\n(the SO_RCVBUF option) for the listening socket (1.11.13).
sndbuf=size
sets the send buffer size\n(the SO_SNDBUF option) for the listening socket (1.11.13).
bind
this parameter instructs to make a separate bind()\ncall for a given address:port pair.\nThe fact is that if there are several listen directives with\nthe same port but different addresses, and one of the\nlisten directives listens on all addresses\nfor the given port (*:port), nginx will\nbind() only to *:port.\nIt should be noted that the getsockname() system call will be\nmade in this case to determine the address that accepted the connection.\nIf the backlog,\nrcvbuf, sndbuf,\nipv6only,\nor so_keepalive parameters\nare used then for a given\naddress:port pair\na separate bind() call will always be made.
ipv6only=on|off
this parameter determines\n(via the IPV6_V6ONLY socket option)\nwhether an IPv6 socket listening on a wildcard address [::]\nwill accept only IPv6 connections or both IPv6 and IPv4 connections.\nThis parameter is turned on by default.\nIt can only be set once on start.
so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]
this parameter configures the “TCP keepalive” behavior\nfor the listening socket.\nIf this parameter is omitted then the operating system’s settings will be\nin effect for the socket.\nIf it is set to the value “on”, the\nSO_KEEPALIVE option is turned on for the socket.\nIf it is set to the value “off”, the\nSO_KEEPALIVE option is turned off for the socket.\nSome operating systems support setting of TCP keepalive parameters on\na per-socket basis using the TCP_KEEPIDLE,\nTCP_KEEPINTVL, and TCP_KEEPCNT socket options.\nOn such systems (currently, Linux 2.4+, NetBSD 5+, and\nFreeBSD 9.0-STABLE), they can be configured\nusing the keepidle, keepintvl, and\nkeepcnt parameters.\nOne or two parameters may be omitted, in which case the system default setting\nfor the corresponding socket option will be in effect.\nFor example,
so_keepalive=30m::10\nwill set the idle timeout (TCP_KEEPIDLE) to 30 minutes,\nleave the probe interval (TCP_KEEPINTVL) at its system default,\nand set the probes count (TCP_KEEPCNT) to 10 probes.
{...}
Provides the configuration file context in which the mail server directives\nare specified.
\n" @@ -9159,9 +10977,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
Sets the number of protocol errors after which the connection is closed.
\n" @@ -9172,9 +10993,12 @@ "contexts": [ "server" ], - "syntax": [ + "syntax_md": [ "`imap` | `pop3` | `smtp`" ], + "syntax_html": [ + "imap | pop3 | smtp
Sets the protocol for a proxied server.\nSupported protocols are\nIMAP,\nPOP3, and\nSMTP.
\n\nIf the directive is not set, the protocol can be detected automatically\nbased on the well-known port specified in the listen\ndirective:
imap: 143, 993pop3: 110, 995smtp: 25, 587, 465Unnecessary protocols can be disabled using the\nconfiguration\nparameters --without-mail_imap_module,\n--without-mail_pop3_module, and\n--without-mail_smtp_module.
address … [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone]
off
Configures name servers used to find the client’s hostname\nto pass it to the\nauthentication server,\nand in the\nXCLIENT\ncommand when proxying SMTP.\nFor example:
\n\nresolver 127.0.0.1 [::1]:5353;\nThe address can be specified as a domain name or IP address,\nwith an optional port (1.3.1, 1.2.2).\nIf port is not specified, the port 53 is used.\nName servers are queried in a round-robin fashion.
\n\n\n\n\nBefore version 1.1.7, only a single name server could be configured.\nSpecifying name servers using IPv6 addresses is supported\nstarting from versions 1.3.1 and 1.2.2.
\n
By default, nginx will look up both IPv4 and IPv6 addresses while resolving.\nIf looking up of IPv4 or IPv6 addresses is not desired,\nthe ipv4=off (1.23.1) or\nthe ipv6=off parameter can be specified.
\n\n\nResolving of names into IPv6 addresses is supported\nstarting from version 1.5.8.
\n
By default, nginx caches answers using the TTL value of a response.\nAn optional valid parameter allows overriding it:
resolver 127.0.0.1 [::1]:5353 valid=30s;\n\n\n\nBefore version 1.1.9, tuning of caching time was not possible,\nand nginx always cached answers for the duration of 5 minutes.
\n\nTo prevent DNS spoofing, it is recommended\nconfiguring DNS servers in a properly secured trusted local network.
\n
The optional status_zone parameter (1.17.1)\nenables\ncollection\nof DNS server statistics of requests and responses\nin the specified zone.\nThe parameter is available as part of our\ncommercial subscription.
The special value off disables resolving.
time
Sets a timeout for DNS operations, for example:
\n\nresolver_timeout 5s;\n{...}
Sets the configuration for a server.
\n" @@ -9228,9 +11062,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "*`name`*" ], + "syntax_html": [ + "name
Sets the server name that is used:
\n\nEHLO command when connecting to the SMTP backend,\nif the passing of the\nXCLIENT command\nis enabled.If the directive is not specified, the machine’s hostname is used.
\n" @@ -9242,9 +11079,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Sets the timeout that is used before proxying to the backend starts.
\n" @@ -9262,9 +11102,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "*`method`* ..." ], + "syntax_html": [ + "method …
Sets permitted methods of authentication for IMAP clients.\nSupported methods are:
\n\nplain
login
cram-md5
AUTH=CRAM-MD5.\nIn order for this method to work, the password must be stored unencrypted.
external
AUTH=EXTERNAL (1.11.6).
Plain text authentication methods\n(the LOGIN command, AUTH=PLAIN,\nand AUTH=LOGIN) are always enabled,\nthough if the plain and login methods\nare not specified,\nAUTH=PLAIN and AUTH=LOGIN\nwill not be automatically included in imap_capabilities.
extension …
Sets the\nIMAP protocol\nextensions list that is passed to the client in response to\nthe CAPABILITY command.\nThe authentication methods specified in the imap_auth directive and\nSTARTTLS\nare automatically added to this list depending on the\nstarttls directive value.
It makes sense to specify the extensions\nsupported by the IMAP backends\nto which the clients are proxied (if these extensions are related to commands\nused after the authentication, when nginx transparently proxies a client\nconnection to the backend).
\n\nThe current list of standardized extensions is published at\nwww.iana.org.
\n" @@ -9290,9 +11136,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
Sets the size of the buffer used for reading IMAP commands.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.
method …
Sets permitted methods of authentication for POP3 clients.\nSupported methods are:
\n\nplain
apop
APOP.\nIn order for this method to work, the password must be stored unencrypted.
cram-md5
AUTH CRAM-MD5.\nIn order for this method to work, the password must be stored unencrypted.
external
AUTH EXTERNAL (1.11.6).
Plain text authentication methods\n(USER/PASS, AUTH PLAIN,\nand AUTH LOGIN) are always enabled,\nthough if the plain method is not specified,\nAUTH PLAIN and AUTH LOGIN\nwill not be automatically included in pop3_capabilities.
extension …
Sets the\nPOP3 protocol\nextensions list that is passed to the client in response to\nthe CAPA command.\nThe authentication methods specified in the pop3_auth directive\n(SASL extension) and\nSTLS\nare automatically added to this list depending on the\nstarttls directive value.
It makes sense to specify the extensions\nsupported by the POP3 backends\nto which the clients are proxied (if these extensions are related to commands\nused after the authentication, when nginx transparently proxies the client\nconnection to the backend).
\n\nThe current list of standardized extensions is published at\nwww.iana.org.
\n" @@ -9344,9 +11199,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
Sets the size of the buffer used for proxying.\nBy default, the buffer size is equal to one memory page.\nDepending on a platform, it is either 4K or 8K.
\n" @@ -9358,9 +11216,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Indicates whether to pass the error message obtained during\nthe authentication on the backend to the client.
\n\nUsually, if the authentication in nginx is a success,\nthe backend cannot return an error.\nIf it nevertheless returns an error,\nit means some internal error has occurred.\nIn such case the backend message can contain information\nthat should not be shown to the client.\nHowever, responding with an error for the correct password\nis a normal behavior for some POP3 servers.\nFor example, CommuniGatePro informs a user about\nmailbox overflow or other events by periodically outputting the\nauthentication error.\nThe directive should be enabled in this case.
\n" @@ -9372,9 +11233,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables the\nPROXY protocol for connections to a backend.
\n" @@ -9386,9 +11250,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables user authentication on the SMTP backend\nusing the AUTH command.
If XCLIENT is also enabled,\nthen the XCLIENT command will not send\nthe LOGIN parameter.
timeout
Sets the timeout between two successive\nread or write operations on client or proxied server connections.\nIf no data is transmitted within this time, the connection is closed.
on | off
Enables or disables the passing of the\nXCLIENT\ncommand with client parameters when connecting to the SMTP backend.
\n\nWith XCLIENT, the MTA is able to write client information\nto the log and apply various limitations based on this data.
If XCLIENT is enabled\nthen nginx passes the following commands when connecting to the backend:
EHLO with the\nserver name\nXCLIENT\nEHLO or HELO,\nas passed by the clientIf the name\nfound\nby the client IP address points to the same address,\nit is passed in the NAME parameter\nof the XCLIENT command.\nIf the name could not be found, points to a different address,\nor resolver is not specified,\nthe [UNAVAILABLE] is passed\nin the NAME parameter.\nIf an error has occurred in the process of resolving,\nthe [TEMPUNAVAIL] value is used.
If XCLIENT is disabled\nthen nginx passes the EHLO command with the\nserver name\nwhen connecting to the backend if the client has passed\nEHLO,\nor HELO with the server name, otherwise.
address | CIDR | unix:
Defines trusted addresses that are known to send correct\nreplacement addresses.\nIf the special value unix: is specified,\nall UNIX-domain sockets will be trusted.
method …
Sets permitted methods of\nSASL authentication\nfor SMTP clients.\nSupported methods are:
\n\nplain
login
cram-md5
AUTH CRAM-MD5.\nIn order for this method to work, the password must be stored unencrypted.
external
AUTH EXTERNAL (1.11.6).
none
Authentication is not required.
Plain text authentication methods\n(AUTH PLAIN and AUTH LOGIN)\nare always enabled,\nthough if the plain and login methods\nare not specified,\nAUTH PLAIN and AUTH LOGIN\nwill not be automatically included in smtp_capabilities.
extension …
Sets the SMTP protocol extensions list\nthat is passed to the client in response to the\nEHLO command.\nThe authentication methods specified in the smtp_auth directive and\nSTARTTLS\nare automatically added to this list depending on the\nstarttls directive value.
It makes sense to specify the extensions\nsupported by the MTA\nto which the clients are proxied (if these extensions are related to commands\nused after the authentication, when nginx transparently proxies the client\nconnection to the backend).
\n\nThe current list of standardized extensions is published at\nwww.iana.org.
\n" @@ -9482,9 +11364,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
Sets the size of the buffer used for reading SMTP commands.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.
time
Allows setting a delay before sending an SMTP greeting\nin order to reject clients who fail to wait for the greeting before\nsending SMTP commands.
\n" @@ -9516,9 +11404,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
This directive was made obsolete in version 1.15.0\nand was removed in version 1.25.1.\nThe ssl parameter\nof the listen directive\nshould be used instead.
file
Specifies a file with the certificate in the PEM format\nfor the given server.\nIf intermediate certificates should be specified in addition to a primary\ncertificate, they should be specified in the same file in the following\norder: the primary certificate comes first, then the intermediate certificates.\nA secret key in the PEM format may be placed in the same file.
Since version 1.11.0,\nthis directive can be specified multiple times\nto load certificates of different types, for example, RSA and ECDSA:
\n\nserver {\n listen 993 ssl;\n\n ssl_certificate example.com.rsa.crt;\n ssl_certificate_key example.com.rsa.key;\n\n ssl_certificate example.com.ecdsa.crt;\n ssl_certificate_key example.com.ecdsa.key;\n\n ...\n}\n\n\n\nOnly OpenSSL 1.0.2 or higher supports separate certificate chains\nfor different certificates.\nWith older versions, only one certificate chain can be used.
\n
The value\ndata:certificate\ncan be specified instead of the file (1.15.10),\nwhich loads a certificate without using intermediate files.\nNote that inappropriate use of this syntax may have its security implications,\nsuch as writing secret key data to\nerror log.
file
Specifies a file with the secret key in the PEM format\nfor the given server.
The value\nengine:name:id\ncan be specified instead of the file (1.7.9),\nwhich loads a secret key with a specified id\nfrom the OpenSSL engine name.
The value\ndata:key\ncan be specified instead of the file (1.15.10),\nwhich loads a secret key without using intermediate files.\nNote that inappropriate use of this syntax may have its security implications,\nsuch as writing secret key data to\nerror log.
ciphers
Specifies the enabled ciphers.\nThe ciphers are specified in the format understood by the\nOpenSSL library, for example:
\n\nssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;\nThe full list can be viewed using the\n“openssl ciphers” command.
\n\n" @@ -9572,9 +11472,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "The previous versions of nginx used\ndifferent\nciphers by default.
\n
file
Specifies a file with trusted CA certificates in the PEM format\nused to verify client certificates.
The list of certificates will be sent to clients.\nIf this is not desired, the ssl_trusted_certificate\ndirective can be used.
name value
Sets arbitrary OpenSSL configuration\ncommands.
\n\n\n\n\nThe directive is supported when using OpenSSL 1.0.2 or higher.
\n
Several ssl_conf_command directives\ncan be specified on the same level:
ssl_conf_command Options PrioritizeChaCha;\nssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;\nThese directives are inherited from the previous configuration level\nif and only if there are no ssl_conf_command directives\ndefined on the current level.
\n\n" @@ -9600,9 +11506,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "Note that configuring OpenSSL directly\nmight result in unexpected behavior.
\n
file
Specifies a file with revoked certificates (CRL)\nin the PEM format used to verify\nclient certificates.
file
Specifies a file with DH parameters for DHE ciphers.
By default no parameters are set,\nand therefore DHE ciphers will not be used.
\n\n\n\n" @@ -9628,9 +11540,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "*`curve`*" ], + "syntax_html": [ + "Prior to version 1.11.0, builtin parameters were used by default.
\n
curve
Specifies a curve for ECDHE ciphers.
When using OpenSSL 1.0.2 or higher,\nit is possible to specify multiple curves (1.11.0), for example:
\n\nssl_ecdh_curve prime256v1:secp384r1;\nThe special value auto (1.11.0) instructs nginx to use\na list built into the OpenSSL library when using OpenSSL 1.0.2 or higher,\nor prime256v1 with older versions.
\n\n" @@ -9642,9 +11557,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "Prior to version 1.11.0,\nthe
\n\nprime256v1curve was used by default.When using OpenSSL 1.0.2 or higher,\nthis directive sets the list of curves supported by the server.\nThus, in order for ECDSA certificates to work,\nit is important to include the curves used in the certificates.
\n
file
Specifies a file with passphrases for\nsecret keys\nwhere each passphrase is specified on a separate line.\nPassphrases are tried in turn when loading the key.
Example:
\n\nmail {\n ssl_password_file /etc/keys/global.pass;\n ...\n\n server {\n server_name mail1.example.com;\n ssl_certificate_key /etc/keys/first.key;\n }\n\n server {\n server_name mail2.example.com;\n\n # named pipe can also be used instead of a file\n ssl_password_file /etc/keys/fifo;\n ssl_certificate_key /etc/keys/second.key;\n }\n}\non | off
Specifies that server ciphers should be preferred over client ciphers\nwhen the SSLv3 and TLS protocols are used.
\n" @@ -9670,9 +11591,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "[`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]" ], + "syntax_html": [ + "[SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]
Enables the specified protocols.
\n\n\n\n" @@ -9684,9 +11608,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "`off` | `none` | [`builtin`[:*`size`*]] [`shared`:*`name`*:*`size`*]" ], + "syntax_html": [ + "The
\n\nTLSv1.1andTLSv1.2parameters\n(1.1.13, 1.0.12) work only when OpenSSL 1.0.1 or higher is used.The
\n\nTLSv1.3parameter (1.13.0) works only when\nOpenSSL 1.1.1 or higher is used.The
\nTLSv1.3parameter is used by default\nsince 1.23.4.
off | none | [builtin[:size]] [shared:name:size]
Sets the types and sizes of caches that store session parameters.\nA cache can be of any of the following types:
\n\noff
the use of a session cache is strictly prohibited:\nnginx explicitly tells a client that sessions may not be reused.
none
the use of a session cache is gently disallowed:\nnginx tells a client that sessions may be reused, but does not\nactually store session parameters in the cache.
builtin
a cache built in OpenSSL; used by one worker process only.\nThe cache size is specified in sessions.\nIf size is not given, it is equal to 20480 sessions.\nUse of the built-in cache can cause memory fragmentation.
shared
a cache shared between all worker processes.\nThe cache size is specified in bytes; one megabyte can store\nabout 4000 sessions.\nEach shared cache should have an arbitrary name.\nA cache with the same name can be used in several\nservers.\nIt is also used to automatically generate, store, and\nperiodically rotate TLS session ticket keys (1.23.2)\nunless configured explicitly\nusing the ssl_session_ticket_key directive.
Both cache types can be used simultaneously, for example:
\n\nssl_session_cache builtin:1000 shared:SSL:10m;\nbut using only shared cache without the built-in cache should\nbe more efficient.
\n" @@ -9698,9 +11625,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "file
Sets a file with the secret key used to encrypt\nand decrypt TLS session tickets.\nThe directive is necessary if the same key has to be shared between\nmultiple servers.\nBy default, a randomly generated key is used.
If several keys are specified, only the first key is\nused to encrypt TLS session tickets.\nThis allows configuring key rotation, for example:
\n\nssl_session_ticket_key current.key;\nssl_session_ticket_key previous.key;\nThe file must contain 80 or 48 bytes\nof random data and can be created using the following command:
openssl rand 80 > ticket.key\nDepending on the file size either AES256 (for 80-byte keys, 1.11.8)\nor AES128 (for 48-byte keys) is used for encryption.
\n" @@ -9712,9 +11642,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables session resumption through\nTLS session tickets.
\n" @@ -9726,9 +11659,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Specifies a time during which a client may reuse the\nsession parameters.
\n" @@ -9740,9 +11676,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "file
Specifies a file with trusted CA certificates in the PEM format\nused to verify client certificates.
In contrast to the certificate set by ssl_client_certificate,\nthe list of these certificates will not be sent to clients.
on | off | optional | optional_no_ca
Enables verification of client certificates.\nThe verification result is passed in the\n“Auth-SSL-Verify” header of the\nauthentication\nrequest.
\n\nThe optional parameter requests the client\ncertificate and verifies it if the certificate is present.
The optional_no_ca parameter\nrequests the client\ncertificate but does not require it to be signed by a trusted CA certificate.\nThis is intended for the use in cases when a service that is external to nginx\nperforms the actual certificate verification.\nThe contents of the certificate is accessible through requests\nsent\nto the authentication server.
number
Sets the verification depth in the client certificates chain.
\n" @@ -9782,9 +11727,12 @@ "mail", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off` | `only`" ], + "syntax_html": [ + "on | off | only
on
allow usage of the STLS command for the POP3\nand the STARTTLS command for the IMAP and SMTP;
off
deny usage of the STLS\nand STARTTLS commands;
only
require preliminary TLS transition.
on | off
If accept_mutex is enabled,\nworker processes will accept new connections by turn.\nOtherwise, all worker processes will be notified about new connections,\nand if volume of new connections is low, some of the worker processes\nmay just waste system resources.
\n\n" @@ -9814,9 +11765,12 @@ "contexts": [ "events" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "There is no need to enable
\n\naccept_mutex\non systems that support the\nEPOLLEXCLUSIVE flag (1.11.3) or\nwhen usingreuseport.Prior to version 1.11.3, the default value was
\non.
time
If accept_mutex is enabled, specifies the maximum time\nduring which a worker process will try to restart accepting new\nconnections if another worker process is currently accepting\nnew connections.
on | off
Determines whether nginx should become a daemon.\nMainly used during development.
\n" @@ -9840,9 +11797,12 @@ "contexts": [ "events" ], - "syntax": [ + "syntax_md": [ "*`address`* | *`CIDR`* | `unix:`" ], + "syntax_html": [ + "address | CIDR | unix:
Enables debugging log for selected client connections.\nOther connections will use logging level set by the\nerror_log directive.\nDebugged connections are specified by IPv4 or IPv6 (1.3.0, 1.2.1)\naddress or network.\nA connection may also be specified using a hostname.\nFor connections using UNIX-domain sockets (1.3.0, 1.2.1),\ndebugging log is enabled by the “unix:” parameter.
events {\n debug_connection 127.0.0.1;\n debug_connection localhost;\n debug_connection 192.0.2.0/24;\n debug_connection ::1;\n debug_connection 2001:0db8::/32;\n debug_connection unix:;\n ...\n}\n\n\n" @@ -9853,9 +11813,12 @@ "contexts": [ "main" ], - "syntax": [ + "syntax_md": [ "`abort` | `stop`" ], + "syntax_html": [ + "For this directive to work, nginx needs to\nbe built with
\n--with-debug,\nsee “A debugging log”.
abort | stop
This directive is used for debugging.
\n\nWhen internal error is detected, e.g. the leak of sockets on\nrestart of working processes, enabling debug_points\nleads to a core file creation (abort)\nor to stopping of a process (stop) for further\nanalysis using a system debugger.
variable[=value]
By default, nginx removes all environment variables inherited\nfrom its parent process except the TZ variable.\nThis directive allows preserving some of the inherited variables,\nchanging their values, or creating new environment variables.\nThese variables are then:
\n\nThe TZ variable is always inherited and available to the\nngx_http_perl_module\nmodule, unless it is configured explicitly.
\n\nUsage example:
\n\nenv MALLOC_OPTIONS;\nenv PERL5LIB=/data/site/modules;\nenv OPENSSL_ALLOW_PROXY_CERTS=1;\n\n\n" @@ -9884,9 +11850,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`file`* [*`level`*]" ], + "syntax_html": [ + "The NGINX environment variable is used internally by nginx\nand should not be set directly by the user.
\n
file [level]
Configures logging.\nSeveral logs can be specified on the same configuration level (1.5.2).\nIf on the main configuration level writing a log to a file\nis not explicitly defined, the default file will be used.
The first parameter defines a file that will store the log.
The special value stderr selects the standard error file.\nLogging to syslog can be configured by specifying\nthe “syslog:” prefix.\nLogging to a\ncyclic memory buffer\ncan be configured by specifying the “memory:” prefix and\nbuffer size, and is generally used for debugging (1.7.11).
The second parameter determines the level of logging,\nand can be one of the following:\ndebug, info, notice,\nwarn, error, crit,\nalert, or emerg.\nLog levels above are listed in the order of increasing severity.\nSetting a certain log level will cause all messages of\nthe specified and more severe log levels to be logged.\nFor example, the default level error will\ncause error, crit,\nalert, and emerg messages\nto be logged.\nIf this parameter is omitted then error is used.
\n\n" @@ -9897,9 +11866,12 @@ "contexts": [ "main" ], - "syntax": [ + "syntax_md": [ " `{...}`" ], + "syntax_html": [ + "For
\n\ndebuglogging to work, nginx needs to\nbe built with--with-debug,\nsee “A debugging log”.The directive can be specified on the\n
\nstreamlevel\nstarting from version 1.7.11,\nand on the
{...}
Provides the configuration file context in which the directives that\naffect connection processing are specified.
\n" @@ -9910,9 +11882,12 @@ "contexts": [ "" ], - "syntax": [ + "syntax_md": [ "*`file`* | *`mask`*" ], + "syntax_html": [ + "file | mask
Includes another file, or files matching the\nspecified mask, into configuration.\nIncluded files should consist of\nsyntactically correct directives and blocks.
Usage example:
\n\ninclude mime.types;\ninclude vhosts/*.conf;\nfile
Loads a dynamic module.
\n\nExample:
\n\nload_module modules/ngx_mail_module.so;\nfile
nginx uses the locking mechanism to implement accept_mutex\nand serialize access to shared memory.\nOn most systems the locks are implemented using atomic operations,\nand this directive is ignored.\nOn other systems the “lock file” mechanism is used.\nThis directive specifies a prefix for the names of lock files.
on | off
Determines whether worker processes are started.\nThis directive is intended for nginx developers.
\n" @@ -9962,9 +11946,12 @@ "contexts": [ "events" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
If multi_accept is disabled, a worker process\nwill accept one new connection at a time.\nOtherwise, a worker process\nwill accept all new connections at a time.
\n\n" @@ -9975,9 +11962,12 @@ "contexts": [ "main" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "The directive is ignored if
\nkqueue\nconnection processing method is used, because it reports\nthe number of new connections waiting to be accepted.
on | off
Enables or disables the use of “just-in-time compilation” (PCRE JIT)\nfor the regular expressions known by the time of configuration parsing.
\n\nPCRE JIT can speed up processing of regular expressions significantly.
\n\n\n\n" @@ -9988,9 +11978,12 @@ "contexts": [ "main" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "The JIT is available in PCRE libraries starting from version 8.20\nbuilt with the
\n--enable-jitconfiguration parameter.\nWhen the PCRE library is built with nginx (--with-pcre=),\nthe JIT support is enabled via the\n--with-pcre-jitconfiguration parameter.
file
Defines a file that will store the process ID of the main process.
device
Defines the name of the hardware SSL accelerator.
\n" @@ -10014,9 +12010,12 @@ "contexts": [ "main" ], - "syntax": [ + "syntax_md": [ "*`name`* `threads`=*`number`* [`max_queue`=*`number`*]" ], + "syntax_html": [ + "name threads=number [max_queue=number]
Defines the name and parameters of a thread pool\nused for multi-threaded reading and sending of files\nwithout blocking\nworker processes.
The threads parameter\ndefines the number of threads in the pool.
In the event that all threads in the pool are busy,\na new task will wait in the queue.\nThe max_queue parameter limits the number\nof tasks allowed to be waiting in the queue.\nBy default, up to 65536 tasks can wait in the queue.\nWhen the queue overflows, the task is completed with an error.
interval
Reduces timer resolution in worker processes, thus reducing the\nnumber of gettimeofday() system calls made.\nBy default, gettimeofday() is called each time\na kernel event is received.\nWith reduced resolution, gettimeofday() is only\ncalled once per specified interval.
Example:
\n\ntimer_resolution 100ms;\nInternal implementation of the interval depends on the method used:
\n\nEVFILT_TIMER filter if kqueue is used;timer_create() if eventport is used;setitimer() otherwise.method
Specifies the connection processing\nmethod to use.\nThere is normally no need to specify it explicitly, because nginx will\nby default use the most efficient method.
user [group]
Defines user and group\ncredentials used by worker processes.\nIf group is omitted, a group whose name equals\nthat of user is used.
number
When using aio\nwith the epoll\nconnection processing method, sets the maximum number of\noutstanding asynchronous I/O operations\nfor a single worker process.
number
Sets the maximum number of simultaneous connections that\ncan be opened by a worker process.
\n\nIt should be kept in mind that this number includes all connections\n(e.g. connections with proxied servers, among others),\nnot only connections with clients.\nAnother consideration is that the actual number of simultaneous\nconnections cannot exceed the current limit on\nthe maximum number of open files, which can be changed by\nworker_rlimit_nofile.
cpumask …
auto [cpumask]
Binds worker processes to the sets of CPUs.\nEach CPU set is represented by a bitmask of allowed CPUs.\nThere should be a separate set defined for each of the worker processes.\nBy default, worker processes are not bound to any specific CPUs.
\n\nFor example,
\n\nworker_processes 4;\nworker_cpu_affinity 0001 0010 0100 1000;\nbinds each worker process to a separate CPU, while
\n\nworker_processes 2;\nworker_cpu_affinity 0101 1010;\nbinds the first worker process to CPU0/CPU2,\nand the second worker process to CPU1/CPU3.\nThe second example is suitable for hyper-threading.
\n\nThe special value auto (1.9.10) allows\nbinding worker processes automatically to available CPUs:
worker_processes auto;\nworker_cpu_affinity auto;\nThe optional mask parameter can be used to limit the CPUs\navailable for automatic binding:
\n\nworker_cpu_affinity auto 01010101;\n\n\n" @@ -10106,9 +12124,12 @@ "contexts": [ "main" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "The directive is only available on FreeBSD and Linux.
\n
number
Defines the scheduling priority for worker processes like it is\ndone by the nice command: a negative\nnumber\nmeans higher priority.\nAllowed range normally varies from -20 to 20.
Example:
\n\nworker_priority -10;\nnumber | auto
Defines the number of worker processes.
\n\nThe optimal value depends on many factors including (but not\nlimited to) the number of CPU cores, the number of hard disk\ndrives that store data, and load pattern.\nWhen one is in doubt, setting it to the number of available CPU cores\nwould be a good start (the value “auto”\nwill try to autodetect it).
\n\n" @@ -10132,9 +12156,12 @@ "contexts": [ "main" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "The
\nautoparameter is supported starting from\nversions 1.3.8 and 1.2.5.
size
Changes the limit on the largest size of a core file\n(RLIMIT_CORE) for worker processes.\nUsed to increase the limit without restarting the main process.
number
Changes the limit on the maximum number of open files\n(RLIMIT_NOFILE) for worker processes.\nUsed to increase the limit without restarting the main process.
time
Configures a timeout for a graceful shutdown of worker processes.\nWhen the time expires,\nnginx will try to close all the connections currently open\nto facilitate shutdown.
directory
Defines the current working directory for a worker process.\nIt is primarily used when writing a core-file, in which case\na worker process should have write permission for the\nspecified directory.
\n" @@ -10190,9 +12226,12 @@ "contexts": [ "main" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "file
Sets a file name that keeps profiling information of\nnginx worker process.\nThe ID of the worker process is always a part of the file name\nand is appended to the end of the file name, after a dot.
\n" @@ -10209,9 +12248,12 @@ "contexts": [ "http" ], - "syntax": [ + "syntax_md": [ " `{...}`" ], + "syntax_html": [ + "{...}
Specifies OTel data export parameters:
\n\nendpoint
the address of OTLP/gRPC endpoint that will accept telemetry data.
interval
the maximum interval between two exports,\nby default is 5 seconds.
batch_size
the maximum number of spans to be sent in one batch per worker,\nby default is 512.
batch_count
the number of pending batches per worker,\nspans exceeding the limit are dropped,\nby default is 4.
Example:
\n\notel_exporter {\n endpoint localhost:4317;\n interval 5s;\n batch_size 512;\n batch_count 4;\n}\nname
Sets the\n“service.name”\nattribute of the OTel resource.
on | off | $variable
Enables or disables OpenTelemetry tracing.\nThe directive can also be enabled by specifying a variable:
\n\nsplit_clients "$otel_trace_id" $ratio_sampler {\n 10% on;\n * off;\n}\n\nserver {\n location / {\n otel_trace $ratio_sampler;\n otel_trace_context inject;\n proxy_pass http://backend;\n }\n}\nextract | inject | propagate | ignore
Specifies how to propagate\ntraceparent/tracestate headers:
\n\nextract
uses an existing trace context from the request,\nso that the identifiers of\na trace and\nthe parent span\nare inherited from the incoming request.
inject
adds a new context to the request, overwriting existing headers, if any.
propagate
updates the existing context\n(combines extract and inject).
ignore
skips context headers processing.
name
Defines the name of the OTel\nspan.\nBy default, it is a name of the location for a request.\nThe name can contain variables.
\n" @@ -10282,9 +12336,12 @@ "server", "location" ], - "syntax": [ + "syntax_md": [ "*`name`* *`value`*" ], + "syntax_html": [ + "name value
Adds a custom OTel span attribute.\nThe value can contain variables.
\n" @@ -10302,9 +12359,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`address`* | *`CIDR`* | `unix:` | `all`" ], + "syntax_html": [ + "address | CIDR | unix: | all
Allows access for the specified network or address.\nIf the special value unix: is specified,\nallows access for all UNIX-domain sockets.
address | CIDR | unix: | all
Denies access for the specified network or address.\nIf the special value unix: is specified,\ndenies access for all UNIX-domain sockets.
address:port [ssl] [udp] [proxy_protocol] [fastopen=number] [backlog=number] [rcvbuf=size] [sndbuf=size] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]]
Sets the address and port for the socket\non which the server will accept connections.\nIt is possible to specify just the port.\nThe address can also be a hostname, for example:
listen 127.0.0.1:12345;\nlisten *:12345;\nlisten 12345; # same as *:12345\nlisten localhost:12345;\nIPv6 addresses are specified in square brackets:
\n\nlisten [::1]:12345;\nlisten [::]:12345;\nUNIX-domain sockets are specified with the “unix:”\nprefix:
listen unix:/var/run/nginx.sock;\nPort ranges (1.15.10) are specified with the\nfirst and last port separated by a hyphen:
\n\nlisten 127.0.0.1:12345-12399;\nlisten 12345-12399;\nThe ssl parameter allows specifying that all\nconnections accepted on this port should work in SSL mode.
The udp parameter configures a listening socket\nfor working with datagrams (1.9.13).\nIn order to handle packets from the same address and port in the same session,\nthe reuseport parameter\nshould also be specified.
The proxy_protocol parameter (1.11.4)\nallows specifying that all connections accepted on this port should use the\nPROXY protocol.
\n\n\nThe PROXY protocol version 2 is supported since version 1.13.11.
\n
The listen directive\ncan have several additional parameters specific to socket-related system calls.
fastopen=number
enables\n“TCP Fast Open”\nfor the listening socket (1.21.0) and\nlimits\nthe maximum length for the queue of connections that have not yet completed\nthe three-way handshake.
\n\n\n\nDo not enable this feature unless the server can handle\nreceiving the\n same SYN packet with data more than once.
\n
backlog=number
sets the backlog parameter in the\nlisten() call that limits\nthe maximum length for the queue of pending connections (1.9.2).\nBy default,\nbacklog is set to -1 on FreeBSD, DragonFly BSD, and macOS,\nand to 511 on other platforms.
rcvbuf=size
sets the receive buffer size\n(the SO_RCVBUF option) for the listening socket (1.11.13).
sndbuf=size
sets the send buffer size\n(the SO_SNDBUF option) for the listening socket (1.11.13).
bind
this parameter instructs to make a separate bind()\ncall for a given address:port pair.\nThe fact is that if there are several listen directives with\nthe same port but different addresses, and one of the\nlisten directives listens on all addresses\nfor the given port (*:port), nginx will\nbind() only to *:port.\nIt should be noted that the getsockname() system call will be\nmade in this case to determine the address that accepted the connection.\nIf the backlog,\nrcvbuf, sndbuf,\nipv6only, reuseport,\nor so_keepalive parameters\nare used then for a given\naddress:port pair\na separate bind() call will always be made.
ipv6only=on|off
this parameter determines\n(via the IPV6_V6ONLY socket option)\nwhether an IPv6 socket listening on a wildcard address [::]\nwill accept only IPv6 connections or both IPv6 and IPv4 connections.\nThis parameter is turned on by default.\nIt can only be set once on start.
reuseport
this parameter (1.9.1) instructs to create an individual listening socket\nfor each worker process\n(using the\nSO_REUSEPORT socket option on Linux 3.9+ and DragonFly BSD,\nor SO_REUSEPORT_LB on FreeBSD 12+), allowing a kernel\nto distribute incoming connections between worker processes.\nThis currently works only on Linux 3.9+, DragonFly BSD,\nand FreeBSD 12+ (1.15.1).
\n\nInappropriate use of this option may have its security\nimplications.
\n
so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]
this parameter configures the “TCP keepalive” behavior\nfor the listening socket.\nIf this parameter is omitted then the operating system’s settings will be\nin effect for the socket.\nIf it is set to the value “on”, the\nSO_KEEPALIVE option is turned on for the socket.\nIf it is set to the value “off”, the\nSO_KEEPALIVE option is turned off for the socket.\nSome operating systems support setting of TCP keepalive parameters on\na per-socket basis using the TCP_KEEPIDLE,\nTCP_KEEPINTVL, and TCP_KEEPCNT socket options.\nOn such systems (currently, Linux 2.4+, NetBSD 5+, and\nFreeBSD 9.0-STABLE), they can be configured\nusing the keepidle, keepintvl, and\nkeepcnt parameters.\nOne or two parameters may be omitted, in which case the system default setting\nfor the corresponding socket option will be in effect.\nFor example,
so_keepalive=30m::10\nwill set the idle timeout (TCP_KEEPIDLE) to 30 minutes,\nleave the probe interval (TCP_KEEPINTVL) at its system default,\nand set the probes count (TCP_KEEPCNT) to 10 probes.
Different servers must listen on different\naddress:port pairs.
size
Specifies a size of the\npreread buffer.
timeout
Specifies a timeout of the\npreread phase.
timeout
Specifies a timeout for\nreading the PROXY protocol header to complete.\nIf no entire header is transmitted within this time,\nthe connection is closed.
address … [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone]
Configures name servers used to resolve names of upstream servers\ninto addresses, for example:
\n\nresolver 127.0.0.1 [::1]:5353;\nThe address can be specified as a domain name or IP address,\nwith an optional port.\nIf port is not specified, the port 53 is used.\nName servers are queried in a round-robin fashion.
\n\nBy default, nginx will look up both IPv4 and IPv6 addresses while resolving.\nIf looking up of IPv4 or IPv6 addresses is not desired,\nthe ipv4=off (1.23.1) or\nthe ipv6=off parameter can be specified.
By default, nginx caches answers using the TTL value of a response.\nThe optional valid parameter allows overriding it:
resolver 127.0.0.1 [::1]:5353 valid=30s;\n\n\n\nTo prevent DNS spoofing, it is recommended\nconfiguring DNS servers in a properly secured trusted local network.
\n
The optional status_zone parameter (1.17.1)\nenables\ncollection\nof DNS server statistics of requests and responses\nin the specified zone.\nThe parameter is available as part of our\ncommercial subscription.
\n\n" @@ -10405,9 +12483,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "Before version 1.11.3, this directive was available as part of our\ncommercial subscription.
\n
time
Sets a timeout for name resolution, for example:
\n\nresolver_timeout 5s;\n\n\n" @@ -10418,9 +12499,12 @@ "contexts": [ "stream" ], - "syntax": [ + "syntax_md": [ " `{...}`" ], + "syntax_html": [ + "Before version 1.11.3, this directive was available as part of our\ncommercial subscription.
\n
{...}
Sets the configuration for a server.
\n" @@ -10431,9 +12515,12 @@ "contexts": [ "main" ], - "syntax": [ + "syntax_md": [ " `{...}`" ], + "syntax_html": [ + "{...}
Provides the configuration file context in which the stream server directives\nare specified.
\n" @@ -10445,9 +12532,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables the use of the TCP_NODELAY option.\nThe option is enabled for both client and proxied server connections.
size
Sets the bucket size for the variables hash table.\nThe details of setting up hash tables are provided in a separate\ndocument.
\n" @@ -10471,9 +12564,12 @@ "contexts": [ "stream" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
Sets the maximum size of the variables hash table.\nThe details of setting up hash tables are provided in a separate\ndocument.
[$address] $variable {...}
Describes the dependency of values of the specified variable\non the client IP address.\nBy default, the address is taken from the $remote_addr variable,\nbut it can also be taken from another variable, for example:
geo $arg_remote_addr $geo {\n ...;\n}\n\n\n\nSince variables are evaluated only when used, the mere existence\nof even a large number of declared “
\ngeo” variables\ndoes not cause any extra costs for connection processing.
If the value of a variable does not represent a valid IP address\nthen the “255.255.255.255” address is used.
Addresses are specified either as prefixes in CIDR notation\n(including individual addresses) or as ranges.
\n\nThe following special parameters are also supported:
\n\ndelete
deletes the specified network.
default
a value set to the variable if the client address does not\nmatch any of the specified addresses.\nWhen addresses are specified in CIDR notation,\n“0.0.0.0/0” and “::/0”\ncan be used instead of default.\nWhen default is not specified, the default\nvalue will be an empty string.
include
includes a file with addresses and values.\nThere can be several inclusions.
ranges
indicates that addresses are specified as ranges.\nThis parameter should be the first.\nTo speed up loading of a geo base, addresses should be put in ascending order.
Example:
\n\ngeo $country {\n default ZZ;\n include conf/geo.conf;\n delete 127.0.0.0/16;\n\n 127.0.0.0/24 US;\n 127.0.0.1/32 RU;\n 10.1.0.0/16 RU;\n 192.168.1.0/24 UK;\n}\nThe conf/geo.conf file could contain the following lines:
10.2.0.0/16 RU;\n192.168.2.0/24 RU;\nA value of the most specific match is used.\nFor example, for the 127.0.0.1 address the value “RU”\nwill be chosen, not “US”.
Example with ranges:
\n\ngeo $country {\n ranges;\n default ZZ;\n 127.0.0.0-127.0.0.0 US;\n 127.0.0.1-127.0.0.1 RU;\n 127.0.0.1-127.0.0.255 US;\n 10.1.0.0-10.1.255.255 RU;\n 192.168.1.0-192.168.1.255 UK;\n}\nfile
Specifies a database used to determine the country\ndepending on the client IP address.\nThe following variables are available when using this database:
\n\n$geoip_country_code
two-letter country code, for example,\n“RU”, “US”.
$geoip_country_code3
three-letter country code, for example,\n“RUS”, “USA”.
$geoip_country_name
country name, for example,\n“Russian Federation”, “United States”.
file
Specifies a database used to determine the country, region, and city\ndepending on the client IP address.\nThe following variables are available when using this database:
\n\n$geoip_area_code
telephone area code (US only).
\n\n\n\nThis variable may contain outdated information since\nthe corresponding database field is deprecated.
\n
$geoip_city_continent_code
two-letter continent code, for example,\n“EU”, “NA”.
$geoip_city_country_code
two-letter country code, for example,\n“RU”, “US”.
$geoip_city_country_code3
three-letter country code, for example,\n“RUS”, “USA”.
$geoip_city_country_name
country name, for example,\n“Russian Federation”, “United States”.
$geoip_dma_code
DMA region code in US (also known as “metro code”), according to the\ngeotargeting\nin Google AdWords API.
$geoip_latitude
latitude.
$geoip_longitude
longitude.
$geoip_region
two-symbol country region code (region, territory, state, province, federal land\nand the like), for example,\n“48”, “DC”.
$geoip_region_name
country region name (region, territory, state, province, federal land\nand the like), for example,\n“Moscow City”, “District of Columbia”.
$geoip_city
city name, for example,\n“Moscow”, “Washington”.
$geoip_postal_code
postal code.
file
Specifies a database used to determine the organization\ndepending on the client IP address.\nThe following variable is available when using this database:
\n\n$geoip_org
organization name, for example, “The University of Melbourne”.
function | module.function
Sets an njs function which will be called at the\naccess phase.\nSince 0.4.0,\na module function can be referenced.
\n\nThe function is called once at the moment when the stream session reaches\nthe access phase\nfor the first time.\nThe function is called with the following arguments:
\n\ns
the Stream Session object
At this phase, it is possible to perform initialization\nor register a callback with\nthe s.on()\nmethod\nfor each incoming data chunk until one of the following methods are called:\ns.allow(),\ns.decline(),\ns.done().\nAs soon as one of these methods is called, the stream session processing\nswitches to the next phase\nand all current\ns.on()\ncallbacks are dropped.
size
Sets the size of the buffer used for reading and writing\nwith Fetch API.
ciphers
Specifies the enabled ciphers for HTTPS connections\nwith Fetch API.\nThe ciphers are specified in the format understood by the OpenSSL library.
\n\nThe full list can be viewed using the\n“openssl ciphers” command.
size
Sets the maximum size of the response received\nwith Fetch API.
[TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]
Enables the specified protocols for HTTPS connections\nwith Fetch API.
\n" @@ -10625,9 +12748,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Defines a timeout for reading and writing\nfor Fetch API.\nThe timeout is set only between two successive read/write operations,\nnot for the whole response.\nIf no data is transmitted within this time, the connection is closed.
\n" @@ -10639,9 +12765,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "file
Specifies a file with trusted CA certificates in the PEM format\nused to\nverify\nthe HTTPS certificate\nwith Fetch API.
on | off
Enables or disables verification of the HTTPS server certificate\nwith Fetch API.
\n" @@ -10667,9 +12799,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
Sets the verification depth in the HTTPS server certificates chain\nwith Fetch API.
\n" @@ -10681,9 +12816,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`function`* | *`module.function`*" ], + "syntax_html": [ + "function | module.function
Sets a data filter.\nSince 0.4.0,\na module function can be referenced.\nThe filter function is called once at the moment when the stream session reaches\nthe content phase.
\n\nThe filter function is called with the following arguments:
\n\ns
the Stream Session object
At this phase, it is possible to perform initialization\nor register a callback with\nthe s.on()\nmethod for each incoming data chunk.\nThe\ns.off()\nmethod may be used to unregister a callback and stop filtering.
\n\n" @@ -10695,9 +12833,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`module.js`* | *`export_name from module.js`*" ], + "syntax_html": [ + "As the
\njs_filterhandler\nreturns its result immediately, it supports\nonly synchronous operations.\nThus, asynchronous operations such as\nngx.fetch()\nor\nsetTimeout()\nare not supported.
module.js | export_name from module.js
Imports a module that implements location and variable handlers in njs.\nThe export_name is used as a namespace\nto access module functions.\nIf the export_name is not specified,\nthe module name will be used as a namespace.
js_import stream.js;\nHere, the module name stream is used as a namespace\nwhile accessing exports.\nIf the imported module exports foo(),\nstream.foo is used to refer to it.
Several js_import directives can be specified.
\n\n" @@ -10708,9 +12849,12 @@ "contexts": [ "stream" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "The directive can be specified on the\n
\nserverlevel\nsince 0.7.7.
file
Specifies a file that implements server and variable handlers in njs:
\n\nnginx.conf:\njs_include stream.js;\njs_set $js_addr address;\nserver {\n listen 127.0.0.1:12345;\n return $js_addr;\n}\n\nstream.js:\nfunction address(s) {\n return s.remoteAddress;\n}\nThe directive was made obsolete in version\n0.4.0\nand was removed in version\n0.7.1.\nThe js_import directive should be used instead.
path
Sets an additional path for njs modules.
\n\n\n\n" @@ -10736,9 +12883,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`name.json`* | *`name`* from *`file.json`*" ], + "syntax_html": [ + "The directive can be specified on the\n
\nserverlevel\nsince 0.7.7.
name.json | name from file.json
Preloads an\nimmutable object\nat configure time.\nThe name is used a name of the global variable\nthough which the object is available in njs code.\nIf the name is not specified,\nthe file name will be used instead.
js_preload_object map.json;\nHere, the map is used as a name\nwhile accessing the preloaded object.
Several js_preload_object directives can be specified.
function | module.function
Sets an njs function which will be called at the\npreread phase.\nSince 0.4.0,\na module function can be referenced.
\n\nThe function is called once\nat the moment when the stream session reaches the\npreread phase\nfor the first time.\nThe function is called with the following arguments:
\n\ns
the Stream Session object
At this phase, it is possible to perform initialization\nor register a callback with\nthe s.on()\nmethod\nfor each incoming data chunk until one of the following methods are called:\ns.allow(),\ns.decline(),\ns.done().\nWhen one of these methods is called,\nthe stream session switches to the\nnext phase\nand all current\ns.on()\ncallbacks are dropped.
\n\n" @@ -10764,9 +12917,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`$variable`* *`function`* | *`module.function`*" ], + "syntax_html": [ + "As the
\njs_prereadhandler\nreturns its result immediately, it supports\nonly synchronous callbacks.\nThus, asynchronous callbacks such as\nngx.fetch()\nor\nsetTimeout()\nare not supported.\nNevertheless, asynchronous operations are supported in\ns.on()\ncallbacks in the\npreread phase.\nSee\nthis example for more information.
$variable function | module.function
Sets an njs function\nfor the specified variable.\nSince 0.4.0,\na module function can be referenced.
The function is called when\nthe variable is referenced for the first time for a given request.\nThe exact moment depends on a\nphase\nat which the variable is referenced.\nThis can be used to perform some logic\nnot related to variable evaluation.\nFor example, if the variable is referenced only in the\nlog_format directive,\nits handler will not be executed until the log phase.\nThis handler can be used to do some cleanup\nright before the request is freed.
\n\n" @@ -10777,9 +12933,12 @@ "contexts": [ "stream" ], - "syntax": [ + "syntax_md": [ "`zone`=*`name`*:*`size`* [`timeout`=*`time`*] [`type`=`string`|`number`] [`evict`]" ], + "syntax_html": [ + "As the
\n\njs_sethandler\nreturns its result immediately, it supports\nonly synchronous callbacks.\nThus, asynchronous callbacks such as\nngx.fetch()\nor\nsetTimeout()\nare not supported.The directive can be specified on the\n
\nserverlevel\nsince 0.7.7.
zone=name:size [timeout=time] [type=string|number] [evict]
Sets the name and size of the shared memory zone\nthat keeps the key-value dictionary\nshared between worker processes.
By default the shared dictionary uses a string as a key and a value.\nThe optional type parameter\nallows redefining the value type to number.
The optional timeout parameter sets\nthe time after which all shared dictionary entries are removed from the zone.
The optional evict parameter removes the oldest\nkey-value pair when the zone storage is exhausted.
Examples:
\n\nexample.conf:\n # Creates a 1Mb dictionary with string values,\n # removes key-value pairs after 60 seconds of inactivity:\n js_shared_dict_zone zone=foo:1M timeout=60s;\n\n # Creates a 512Kb dictionary with string values,\n # forcibly removes oldest key-value pairs when the zone is exhausted:\n js_shared_dict_zone zone=bar:512K timeout=30s evict;\n\n # Creates a 32Kb permanent dictionary with number values:\n js_shared_dict_zone zone=num:32k type=number;\n\nexample.js:\n function get(r) {\n r.return(200, ngx.shared.foo.get(r.args.key));\n }\n\n function set(r) {\n r.return(200, ngx.shared.foo.set(r.args.key, r.args.value));\n }\n\n function del(r) {\n r.return(200, ngx.shared.bar.delete(r.args.key));\n }\n\n function increment(r) {\n r.return(200, ngx.shared.num.incr(r.args.key, 2));\n }\n$variable [value]
Declares\na writable\nvariable.\nThe value can contain text, variables, and their combination.
\n\n\n\n" @@ -10810,9 +12972,12 @@ "contexts": [ "stream" ], - "syntax": [ + "syntax_md": [ "*`key`* *`$variable`* `zone`=*`name`*" ], + "syntax_html": [ + "The directive can be specified on the\n
\nserverlevel\nsince 0.7.7.
key $variable zone=name
Creates a new $variable whose value\nis looked up by the key in the key-value database.\nMatching rules are defined by the\ntype parameter of the\nkeyval_zone directive.\nThe database is stored in a shared memory zone\nspecified by the zone parameter.
zone=name:size [state=file] [timeout=time] [type=string|ip|prefix] [sync]
Sets the name and size of the shared memory zone\nthat keeps the key-value database.\nKey-value pairs are managed by the\nAPI.
The optional state parameter specifies a file\nthat keeps the current state of the key-value database in the JSON format\nand makes it persistent across nginx restarts.\nChanging the file content directly should be avoided.
Examples:
\n\nkeyval_zone zone=one:32k state=/var/lib/nginx/state/one.keyval; # path for Linux\nkeyval_zone zone=one:32k state=/var/db/nginx/state/one.keyval; # path for FreeBSD\nThe optional timeout parameter (1.15.0) sets\nthe time after which key-value pairs are removed from the zone.
The optional type parameter (1.17.1) activates\nan extra index optimized for matching the key of a certain type\nand defines matching rules when evaluating\na keyval $variable.
\n\n\nThe index is stored in the same shared memory zone\nand thus requires additional storage.
\n
type=string
default, no index is enabled;\nvariable lookup is performed using exact match\nof the record key and a search key
type=ip
the search key is the textual representation of IPv4 or IPv6 address\nor CIDR range;\nto match a record key, the search key must belong to a subnet\nspecified by a record key or exactly match an IP address
type=prefix
variable lookup is performed using prefix match\nof a record key and a search key (1.17.5);\nto match a record key, the record key must be a prefix of the search key
The optional sync parameter (1.15.0) enables\nsynchronization\nof the shared memory zone.\nThe synchronization requires the\ntimeout parameter to be set.
\n\n" @@ -10843,9 +13011,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`zone`* *`number`*" ], + "syntax_html": [ + "If the synchronization is enabled, removal of key-value pairs (no matter\none\nor\nall)\nwill be performed only on a target cluster node.\nThe same key-value pairs on other cluster nodes\nwill be removed upon
\ntimeout.
zone number
Sets the shared memory zone\nand the maximum allowed number of connections for a given key value.\nWhen this limit is exceeded, the server will close the connection.\nFor example, the directives
\n\nlimit_conn_zone $binary_remote_addr zone=addr:10m;\n\nserver {\n ...\n limit_conn addr 1;\n}\nallow only one connection per an IP address at a time.
\n\nWhen several limit_conn directives are specified,\nany configured limit will apply.
These directives are inherited from the previous configuration level\nif and only if there are no limit_conn directives\ndefined on the current level.
on | off
Enables the dry run mode.\nIn this mode, the number of connections is not limited, however,\nin the shared memory zone, the number of excessive connections is accounted\nas usual.
\n" @@ -10871,9 +13045,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "`info` | `notice` | `warn` | `error`" ], + "syntax_html": [ + "info | notice | warn | error
Sets the desired logging level for cases when the server\nlimits the number of connections.
\n" @@ -10884,9 +13061,12 @@ "contexts": [ "stream" ], - "syntax": [ + "syntax_md": [ "*`key`* `zone`=*`name`*:*`size`*" ], + "syntax_html": [ + "key zone=name:size
Sets parameters for a shared memory zone\nthat will keep states for various keys.\nIn particular, the state includes the current number of connections.\nThe key can contain text, variables,\nand their combinations (1.11.2).\nConnections with an empty key value are not accounted.\nUsage example:
limit_conn_zone $binary_remote_addr zone=addr:10m;\nHere, the key is a client IP address set by the\n$binary_remote_addr variable.\nThe size of $binary_remote_addr\nis 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses.\nThe stored state always occupies 32 or 64 bytes\non 32-bit platforms and 64 bytes on 64-bit platforms.\nOne megabyte zone can keep about 32 thousand 32-byte states\nor about 16 thousand 64-byte states.\nIf the zone storage is exhausted, the server will close the connection.
\n\n" @@ -10904,10 +13084,14 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`path`* *`format`* [`buffer`=*`size`*] [`gzip[=]`] [`flush`=*`time`*] [`if`=*`condition`*]", "`off`" ], + "syntax_html": [ + "Additionally, as part of our\ncommercial subscription,\nthe\nstatus information\nfor each such shared memory zone can be\nobtained or\nreset\nwith the API since 1.17.7.
\n
path format [buffer=size] [gzip[=]] [flush=time] [if=condition]
off
Sets the path, format,\nand configuration for a buffered log write.\nSeveral logs can be specified on the same configuration level.\nLogging to syslog\ncan be configured by specifying\nthe “syslog:” prefix in the first parameter.\nThe special value off cancels all\naccess_log directives on the current level.
If either the buffer or gzip\nparameter is used, writes to log will be buffered.
\n\n\nThe buffer size must not exceed the size of an atomic write to a disk file.\nFor FreeBSD this size is unlimited.
\n
When buffering is enabled, the data will be written to the file:
\n\nflush\nparameter;If the gzip parameter is used, then the buffered data will\nbe compressed before writing to the file.\nThe compression level can be set between 1 (fastest, less compression)\nand 9 (slowest, best compression).\nBy default, the buffer size is equal to 64K bytes, and the compression level\nis set to 1.\nSince the data is compressed in atomic blocks, the log file can be decompressed\nor read by “zcat” at any time.
Example:
\n\naccess_log /path/to/log.gz basic gzip flush=5m;\n\n\n\nFor gzip compression to work, nginx must be built with the zlib library.
\n
The file path can contain variables,\nbut such logs have some constraints:
\n\nuser\nwhose credentials are used by worker processes should\nhave permissions to create files in a directory with\nsuch logs;open_log_file_cache\ndirective’s valid parameterThe if parameter enables conditional logging.\nA session will not be logged if the condition evaluates to “0”\nor an empty string.
name [escape=default|json|none] string …
Specifies the log format, for example:
\n\nlog_format proxy '$remote_addr [$time_local] '\n '$protocol $status $bytes_sent $bytes_received '\n '$session_time "$upstream_addr" '\n '"$upstream_bytes_sent" "$upstream_bytes_received" "$upstream_connect_time"';\nThe escape parameter (1.11.8) allows setting\njson or default characters escaping\nin variables, by default, default escaping is used.\nThe none parameter (1.13.10) disables escaping.
For default escaping,\ncharacters “"”, “\\”,\nand other characters with values less than 32 or above 126\nare escaped as “\\xXX”.\nIf the variable value is not found,\na hyphen (“-”) will be logged.
For json escaping,\nall characters not allowed\nin JSON strings\nwill be escaped:\ncharacters “"” and\n“\\” are escaped as\n“\\"” and “\\\\”,\ncharacters with values less than 32 are escaped as\n“\\n”,\n“\\r”,\n“\\t”,\n“\\b”,\n“\\f”, or\n“\\u00XX”.
max=N [inactive=time] [min_uses=N] [valid=time]
off
Defines a cache that stores the file descriptors of frequently used logs\nwhose names contain variables.\nThe directive has the following parameters:
\n\nmax
sets the maximum number of descriptors in a cache;\nif the cache becomes full the least recently used (LRU)\ndescriptors are closed
inactive
sets the time after which the cached descriptor is closed\nif there were no access during this time;\nby default, 10 seconds
min_uses
sets the minimum number of file uses during the time\ndefined by the inactive parameter\nto let the descriptor stay open in a cache;\nby default, 1
valid
sets the time after which it should be checked that the file\nstill exists with the same name; by default, 60 seconds
off
disables caching
Usage example:
\n\nopen_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;\nstring $variable {...}
Creates a new variable whose value\ndepends on values of one or more of the source variables\nspecified in the first parameter.
\n\n\n\n\nSince variables are evaluated only when they are used, the mere declaration\neven of a large number of “
\nmap” variables\ndoes not add any extra costs to connection processing.
Parameters inside the map block specify a mapping\nbetween source and resulting values.
Source values are specified as strings or regular expressions.
\n\nStrings are matched ignoring the case.
\n\nA regular expression should either start from the “~”\nsymbol for a case-sensitive matching, or from the “~*”\nsymbols for case-insensitive matching.\nA regular expression can contain named and positional captures\nthat can later be used in other directives along with the\nresulting variable.
If a source value matches one of the names of special parameters\ndescribed below, it should be prefixed with the “\\” symbol.
The resulting value can contain text,\nvariable, and their combination.
\n\nThe following special parameters are also supported:
\n\ndefault value
sets the resulting value if the source value matches none\nof the specified variants.\nWhen default is not specified, the default\nresulting value will be an empty string.
hostnames
indicates that source values can be hostnames with a prefix or suffix mask:
\n\n*.example.com 1;\nexample.* 1;\nThe following two records
\n\nexample.com 1;\n*.example.com 1;\ncan be combined:
\n\n.example.com 1;\nThis parameter should be specified before the list of values.
include file
includes a file with values.\nThere can be several inclusions.
volatile
indicates that the variable is not cacheable (1.11.7).
If the source value matches more than one of the specified variants,\ne.g. both a mask and a regular expression match, the first matching\nvariant will be chosen, in the following order of priority:
\n\n*.example.com”mail.*”size
Sets the bucket size for the map variables hash tables.\nDefault value depends on the processor’s cache line size.\nThe details of setting up hash tables are provided in a separate\ndocument.
size
Sets the maximum size of the map variables\nhash tables.\nThe details of setting up hash tables are provided in a separate\ndocument.
on | off
Enables the MQTT protocol for the given virtual server.
\n" @@ -11012,9 +13215,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`number`* *`size`*" ], + "syntax_html": [ + "number size
Sets the number and size of the buffers\nused for handling MQTT messages,\nfor a single connection.
size
\n\n\nThis directive is obsolete since version 1.25.1.\nThe
\nmqtt_buffers\ndirective should be used instead.
Sets the size of the buffer\nused for writing a modified message.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.\nIt can be made smaller, however.
field value
Sets the message field\nto the given value for CONNECT message.\nThe following fields are supported:\nclientid,\nusername, and\npassword.\nThe value can contain text, variables, and their combination.
Several mqtt_set_connect directives\ncan be specified on the same level:
mqtt_set_connect clientid "$client";\nmqtt_set_connect username "$name";\non | off
Enables extracting information from the MQTT CONNECT message at\nthe preread phase.
\n" @@ -11078,9 +13293,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`address`* [`transparent`] | `off`" ], + "syntax_html": [ + "address [transparent] | off
Makes outgoing connections to a proxied server originate\nfrom the specified local IP address.\nParameter value can contain variables (1.11.2).\nThe special value off cancels the effect\nof the proxy_bind directive\ninherited from the previous configuration level, which allows the\nsystem to auto-assign the local IP address.
The transparent parameter (1.11.0) allows\noutgoing connections to a proxied server originate\nfrom a non-local IP address,\nfor example, from a real IP address of a client:
proxy_bind $remote_addr transparent;\nIn order for this parameter to work,\nit is usually necessary to run nginx worker processes with the\nsuperuser privileges.\nOn Linux it is not required (1.13.8) as if\nthe transparent parameter is specified, worker processes\ninherit the CAP_NET_RAW capability from the master process.\nIt is also necessary to configure kernel routing table\nto intercept network traffic from the proxied server.
size
Sets the size of the buffer used for reading data\nfrom the proxied server.\nAlso sets the size of the buffer used for reading data\nfrom the client.
time
Defines a timeout for establishing a connection with a proxied server.
\n" @@ -11120,9 +13344,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`rate`*" ], + "syntax_html": [ + "rate
Limits the speed of reading the data from the proxied server.\nThe rate is specified in bytes per second.\nThe zero value disables rate limiting.\nThe limit is set per a connection, so if nginx simultaneously opens\ntwo connections to the proxied server,\nthe overall rate will be twice as much as the specified limit.
Parameter value can contain variables (1.17.0).\nIt may be useful in cases where rate should be limited\ndepending on a certain condition:
\n\nmap $slow $rate {\n 1 4k;\n 2 8k;\n}\n\nproxy_download_rate $rate;\non | off
Enables or disables closing\neach direction of a TCP connection independently (“TCP half-close”).\nIf enabled, proxying over TCP will be kept\nuntil both sides close the connection.
\n" @@ -11148,9 +13378,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
When a connection to the proxied server cannot be established, determines\nwhether a client connection will be passed to the next server.
\n\nPassing a connection to the next server can be limited by\nthe number of tries\nand by time.
\n" @@ -11162,9 +13395,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Limits the time allowed to pass a connection to the\nnext server.\nThe 0 value turns off this limitation.
number
Limits the number of possible tries for passing a connection to the\nnext server.\nThe 0 value turns off this limitation.
address
Sets the address of a proxied server.\nThe address can be specified as a domain name or IP address,\nand a port:
\n\nproxy_pass localhost:12345;\nor as a UNIX-domain socket path:
\n\nproxy_pass unix:/tmp/stream.socket;\nIf a domain name resolves to several addresses, all of them will be\nused in a round-robin fashion.\nIn addition, an address can be specified as a\nserver group.
\n\nThe address can also be specified using variables (1.11.3):
\n\nproxy_pass $upstream;\nIn this case, the server name is searched among the described\nserver groups,\nand, if not found, is determined using a\nresolver.
on | off
Enables the\nPROXY protocol for connections to a proxied server.
\n" @@ -11217,9 +13462,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
Sets the number of client datagrams at which\nbinding between a client and existing UDP stream session is dropped.\nAfter receiving the specified number of datagrams, next datagram\nfrom the same client starts a new session.\nThe session terminates when all client datagrams are transmitted\nto a proxied server and the expected number of\nresponses is received,\nor when it reaches a timeout.
\n" @@ -11231,9 +13479,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
Sets the number of datagrams expected from the proxied server\nin response to a client datagram\nif the UDP\nprotocol is used.\nThe number serves as a hint for session termination.\nBy default, the number of datagrams is not limited.
\n\nIf zero value is specified, no response is expected.\nHowever, if a response is received and the\nsession is still not finished, the response will be handled.
\n" @@ -11245,9 +13496,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables terminating all sessions to a proxied server\nafter it was removed from the group or marked as permanently unavailable.\nThis can occur because of\nre-resolve\nor with the API\nDELETE\ncommand.\nA server can be marked as permanently unavailable if it is considered\nunhealthy\nor with the API\nPATCH\ncommand.\nEach session is terminated when the next\nread or write event is processed for the client or proxied server.
\n\n" @@ -11259,9 +13513,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "This directive is available as part of our\ncommercial subscription.
\n
on | off
Configures the “TCP keepalive” behavior\nfor outgoing connections to a proxied server.\nBy default, the operating system’s settings are in effect for the socket.\nIf the directive is set to the value “on”, the\nSO_KEEPALIVE socket option is turned on for the socket.
on | off
Enables the SSL/TLS protocol for connections to a proxied server.
\n" @@ -11287,9 +13547,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "file
Specifies a file with the certificate in the PEM format\nused for authentication to a proxied server.
Since version 1.21.0, variables can be used in the file name.
file
Specifies a file with the secret key in the PEM format\nused for authentication to a proxied server.
Since version 1.21.0, variables can be used in the file name.
ciphers
Specifies the enabled ciphers for connections to a proxied server.\nThe ciphers are specified in the format understood by the OpenSSL library.
\n\nThe full list can be viewed using the\n“openssl ciphers” command.
name value
Sets arbitrary OpenSSL configuration\ncommands\nwhen establishing a connection with the proxied server.
\n\n\n\n\nThe directive is supported when using OpenSSL 1.0.2 or higher.
\n
Several proxy_ssl_conf_command directives\ncan be specified on the same level.\nThese directives are inherited from the previous configuration level\nif and only if there are\nno proxy_ssl_conf_command directives\ndefined on the current level.
\n\n" @@ -11343,9 +13615,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "Note that configuring OpenSSL directly\nmight result in unexpected behavior.
\n
file
Specifies a file with revoked certificates (CRL)\nin the PEM format used to verify\nthe certificate of the proxied server.
name
Allows overriding the server name used to\nverify\nthe certificate of the proxied server and to be\npassed through SNI\nwhen establishing a connection with the proxied server.\nThe server name can also be specified using variables (1.11.3).
\n\nBy default, the host part of the proxy_pass address is used.
file
Specifies a file with passphrases for\nsecret keys\nwhere each passphrase is specified on a separate line.\nPassphrases are tried in turn when loading the key.
[SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]
Enables the specified protocols for connections to a proxied server.
\n\n\n\n" @@ -11399,9 +13683,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "The
\nTLSv1.3parameter is used by default\nsince 1.23.4.
on | off
Enables or disables passing of the server name through\nTLS Server Name Indication extension (SNI, RFC 6066)\nwhen establishing a connection with the proxied server.
\n" @@ -11413,9 +13700,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Determines whether SSL sessions can be reused when working with\nthe proxied server.\nIf the errors\n“SSL3_GET_FINISHED:digest check failed”\nappear in the logs, try disabling session reuse.
file
Specifies a file with trusted CA certificates in the PEM format\nused to verify\nthe certificate of the proxied server.
on | off
Enables or disables verification of the proxied server certificate.
\n" @@ -11455,9 +13751,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
Sets the verification depth in the proxied server certificates chain.
\n" @@ -11469,9 +13768,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`timeout`*" ], + "syntax_html": [ + "timeout
Sets the timeout between two successive\nread or write operations on client or proxied server connections.\nIf no data is transmitted within this time, the connection is closed.
rate
Limits the speed of reading the data from the client.\nThe rate is specified in bytes per second.\nThe zero value disables rate limiting.\nThe limit is set per a connection, so if the client simultaneously opens\ntwo connections,\nthe overall rate will be twice as much as the specified limit.
Parameter value can contain variables (1.17.0).\nIt may be useful in cases where rate should be limited\ndepending on a certain condition:
\n\nmap $slow $rate {\n 1 4k;\n 2 8k;\n}\n\nproxy_upload_rate $rate;\naddress | CIDR | unix:
Defines trusted addresses that are known to send correct\nreplacement addresses.\nIf the special value unix: is specified,\nall UNIX-domain sockets will be trusted.
value
Specifies a value to send to the client.\nThe value can contain text, variables, and their combination.
$variable value
Sets a value for the specified variable.\nThe value can contain text, variables, and their combination.
string $variable {...}
Creates a variable for A/B testing, for example:
\n\nsplit_clients "${remote_addr}AAA" $variant {\n 0.5% .one;\n 2.0% .two;\n * "";\n}\nThe value of the original string is hashed using MurmurHash2.\nIn the example given, hash values from 0 to 21474835 (0.5%)\ncorrespond to the\nvalue ".one" of the $variant variable,\nhash values from 21474836 to 107374180 (2%) correspond to\nthe value ".two",\nand hash values from 107374181 to 4294967295 correspond to\nthe value "" (an empty string).
protocol …
Specifies the list of supported\nALPN protocols.\nOne of the protocols must be\nnegotiated if the client uses ALPN:
\n\nmap $ssl_alpn_protocol $proxy {\n h2 127.0.0.1:8001;\n http/1.1 127.0.0.1:8002;\n}\n\nserver {\n listen 12346;\n proxy_pass $proxy;\n ssl_alpn h2 http/1.1;\n}\nfile
Specifies a file with the certificate in the PEM format\nfor the given server.\nIf intermediate certificates should be specified in addition to a primary\ncertificate, they should be specified in the same file in the following\norder: the primary certificate comes first, then the intermediate certificates.\nA secret key in the PEM format may be placed in the same file.
Since version 1.11.0,\nthis directive can be specified multiple times\nto load certificates of different types, for example, RSA and ECDSA:
\n\nserver {\n listen 12345 ssl;\n\n ssl_certificate example.com.rsa.crt;\n ssl_certificate_key example.com.rsa.key;\n\n ssl_certificate example.com.ecdsa.crt;\n ssl_certificate_key example.com.ecdsa.key;\n\n ...\n}\n\n\n\nOnly OpenSSL 1.0.2 or higher supports separate certificate chains\nfor different certificates.\nWith older versions, only one certificate chain can be used.
\n
Since version 1.15.9, variables can be used in the file name\nwhen using OpenSSL 1.0.2 or higher:
ssl_certificate $ssl_server_name.crt;\nssl_certificate_key $ssl_server_name.key;\nNote that using variables implies that\na certificate will be loaded for each SSL handshake,\nand this may have a negative impact on performance.
\n\nThe value\ndata:$variable\ncan be specified instead of the file (1.15.10),\nwhich loads a certificate from a variable without using intermediate files.\nNote that inappropriate use of this syntax may have its security implications,\nsuch as writing secret key data to\nerror log.
file
Specifies a file with the secret key in the PEM format\nfor the given server.
The value\nengine:name:id\ncan be specified instead of the file,\nwhich loads a secret key with a specified id\nfrom the OpenSSL engine name.
The value\ndata:$variable\ncan be specified instead of the file (1.15.10),\nwhich loads a secret key from a variable without using intermediate files.\nNote that inappropriate use of this syntax may have its security implications,\nsuch as writing secret key data to\nerror log.
Since version 1.15.9, variables can be used in the file name\nwhen using OpenSSL 1.0.2 or higher.
ciphers
Specifies the enabled ciphers.\nThe ciphers are specified in the format understood by the\nOpenSSL library, for example:
\n\nssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;\nThe full list can be viewed using the\n“openssl ciphers” command.
file
Specifies a file with trusted CA certificates in the PEM format\nused to verify client certificates.
The list of certificates will be sent to clients.\nIf this is not desired, the ssl_trusted_certificate\ndirective can be used.
name value
Sets arbitrary OpenSSL configuration\ncommands.
\n\n\n\n\nThe directive is supported when using OpenSSL 1.0.2 or higher.
\n
Several ssl_conf_command directives\ncan be specified on the same level:
ssl_conf_command Options PrioritizeChaCha;\nssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;\nThese directives are inherited from the previous configuration level\nif and only if there are no ssl_conf_command directives\ndefined on the current level.
\n\n" @@ -11664,9 +13999,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "Note that configuring OpenSSL directly\nmight result in unexpected behavior.
\n
file
Specifies a file with revoked certificates (CRL)\nin the PEM format used to verify\nclient certificates.
file
Specifies a file with DH parameters for DHE ciphers.
By default no parameters are set,\nand therefore DHE ciphers will not be used.
\n\n\n\n" @@ -11692,9 +14033,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`curve`*" ], + "syntax_html": [ + "Prior to version 1.11.0, builtin parameters were used by default.
\n
curve
Specifies a curve for ECDHE ciphers.
When using OpenSSL 1.0.2 or higher,\nit is possible to specify multiple curves (1.11.0), for example:
\n\nssl_ecdh_curve prime256v1:secp384r1;\nThe special value auto (1.11.0) instructs nginx to use\na list built into the OpenSSL library when using OpenSSL 1.0.2 or higher,\nor prime256v1 with older versions.
\n\n" @@ -11706,9 +14050,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "Prior to version 1.11.0,\nthe
\n\nprime256v1curve was used by default.When using OpenSSL 1.0.2 or higher,\nthis directive sets the list of curves supported by the server.\nThus, in order for ECDSA certificates to work,\nit is important to include the curves used in the certificates.
\n
time
Specifies a timeout for the SSL handshake to complete.
\n" @@ -11720,9 +14067,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "file
Specifies a file with passphrases for\nsecret keys\nwhere each passphrase is specified on a separate line.\nPassphrases are tried in turn when loading the key.
Example:
\n\nstream {\n ssl_password_file /etc/keys/global.pass;\n ...\n\n server {\n listen 127.0.0.1:12345;\n ssl_certificate_key /etc/keys/first.key;\n }\n\n server {\n listen 127.0.0.1:12346;\n\n # named pipe can also be used instead of a file\n ssl_password_file /etc/keys/fifo;\n ssl_certificate_key /etc/keys/second.key;\n }\n}\non | off
Specifies that server ciphers should be preferred over client ciphers\nwhen the SSLv3 and TLS protocols are used.
\n" @@ -11748,9 +14101,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "[`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]" ], + "syntax_html": [ + "[SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]
Enables the specified protocols.
\n\n\n\n" @@ -11762,9 +14118,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "`off` | `none` | [`builtin`[:*`size`*]] [`shared`:*`name`*:*`size`*]" ], + "syntax_html": [ + "The
\n\nTLSv1.1andTLSv1.2parameters work\nonly when OpenSSL 1.0.1 or higher is used.The
\n\nTLSv1.3parameter (1.13.0) works only when\nOpenSSL 1.1.1 or higher is used.The
\nTLSv1.3parameter is used by default\nsince 1.23.4.
off | none | [builtin[:size]] [shared:name:size]
Sets the types and sizes of caches that store session parameters.\nA cache can be of any of the following types:
\n\noff
the use of a session cache is strictly prohibited:\nnginx explicitly tells a client that sessions may not be reused.
none
the use of a session cache is gently disallowed:\nnginx tells a client that sessions may be reused, but does not\nactually store session parameters in the cache.
builtin
a cache built in OpenSSL; used by one worker process only.\nThe cache size is specified in sessions.\nIf size is not given, it is equal to 20480 sessions.\nUse of the built-in cache can cause memory fragmentation.
shared
a cache shared between all worker processes.\nThe cache size is specified in bytes; one megabyte can store\nabout 4000 sessions.\nEach shared cache should have an arbitrary name.\nA cache with the same name can be used in several\nservers.\nIt is also used to automatically generate, store, and\nperiodically rotate TLS session ticket keys (1.23.2)\nunless configured explicitly\nusing the ssl_session_ticket_key directive.
Both cache types can be used simultaneously, for example:
\n\nssl_session_cache builtin:1000 shared:SSL:10m;\nbut using only shared cache without the built-in cache should\nbe more efficient.
\n" @@ -11776,9 +14135,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "file
Sets a file with the secret key used to encrypt\nand decrypt TLS session tickets.\nThe directive is necessary if the same key has to be shared between\nmultiple servers.\nBy default, a randomly generated key is used.
If several keys are specified, only the first key is\nused to encrypt TLS session tickets.\nThis allows configuring key rotation, for example:
\n\nssl_session_ticket_key current.key;\nssl_session_ticket_key previous.key;\nThe file must contain 80 or 48 bytes\nof random data and can be created using the following command:
openssl rand 80 > ticket.key\nDepending on the file size either AES256 (for 80-byte keys, 1.11.8)\nor AES128 (for 48-byte keys) is used for encryption.
\n" @@ -11790,9 +14152,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables session resumption through\nTLS session tickets.
\n" @@ -11804,9 +14169,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Specifies a time during which a client may reuse the\nsession parameters.
\n" @@ -11818,9 +14186,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "file
Specifies a file with trusted CA certificates in the PEM format\nused to verify client certificates.
In contrast to the certificate set by ssl_client_certificate,\nthe list of these certificates will not be sent to clients.
on | off | optional | optional_no_ca
Enables verification of client certificates.\nThe verification result is stored in the\n$ssl_client_verify variable.\nIf an error has occurred during the client certificate verification\nor a client has not presented the required certificate,\nthe connection is closed.
\n\nThe optional parameter requests the client\ncertificate and verifies it if the certificate is present.
The optional_no_ca parameter\nrequests the client\ncertificate but does not require it to be signed by a trusted CA certificate.\nThis is intended for the use in cases when a service that is external to nginx\nperforms the actual certificate verification.\nThe contents of the certificate is accessible through the\n$ssl_client_cert variable.
number
Sets the verification depth in the client certificates chain.
\n" @@ -11866,9 +14243,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables extracting information from the ClientHello message at\nthe preread phase.
\n" @@ -11885,9 +14265,12 @@ "contexts": [ "server" ], - "syntax": [ + "syntax_md": [ "[*`parameters`*]" ], + "syntax_html": [ + "[parameters]
Enables periodic health checks of the servers in a\ngroup.
\n\nThe following optional parameters are supported:
\n\ninterval=time
sets the interval between two consecutive health checks,\nby default, 5 seconds.
jitter=time
sets the time within which\neach health check will be randomly delayed,\nby default, there is no delay.
fails=number
sets the number of consecutive failed health checks of a particular server\nafter which this server will be considered unhealthy,\nby default, 1.
passes=number
sets the number of consecutive passed health checks of a particular server\nafter which the server will be considered healthy,\nby default, 1.
mandatory [persistent]
sets the initial “checking” state for a server\nuntil the first health check is completed (1.11.7).\nClient connections are not passed to servers in the “checking” state.\nIf the parameter is not specified,\nthe server will be initially considered healthy.
\n\nThe persistent parameter (1.21.1)\nsets the initial “up” state for a server after reload\nif the server was considered healthy before reload.
match=name
specifies the match block configuring the tests that a\nsuccessful connection should pass in order for a health check to pass.\nBy default, for TCP, only the ability\nto establish a TCP connection with the server is checked.\nFor UDP, the absence of\nICMP “Destination Unreachable” message is expected\nin reply to the sent string “nginx health check”.
\n\nPrior to version 1.11.7, by default, UDP health check\nrequired a match block with the\nsend and expect\nparameters.
\n
port=number
defines the port used when connecting to a server\nto perform a health check (1.9.7).\nBy default, equals the\nserver port.
udp
specifies that the UDP protocol should be used for\nhealth checks instead of the default TCP protocol (1.9.13).
timeout
Overrides the\nproxy_timeout\nvalue for health checks.
name {...}
Defines the named test set used to verify server responses to health checks.
\n\nThe following parameters can be configured:
\n\nsend string;
sends a string to the server;
expect string |\n~ regex;
a literal string (1.9.12) or a regular expression\nthat the data obtained from the server should match.\nThe regular expression is specified with the preceding\n“~*” modifier (for case-insensitive matching), or the\n“~” modifier (for case-sensitive matching).
Both send and expect parameters\ncan contain hexadecimal literals with the prefix “\\x”\nfollowed by two hex digits, for example, “\\x80” (1.9.12).
Health check is passed if:
\n\nstring from the send parameter,\nif specified, was sent;expect parameter, if specified;health_check_timeout directive.Example:
\n\nupstream backend {\n zone upstream_backend 10m;\n server 127.0.0.1:12345;\n}\n\nmatch http {\n send "GET / HTTP/1.0\\r\\nHost: localhost\\r\\n\\r\\n";\n expect ~ "200 OK";\n}\n\nserver {\n listen 12346;\n proxy_pass backend;\n health_check match=http;\n}\n\n\n" @@ -11931,9 +14320,12 @@ "contexts": [ "stream" ], - "syntax": [ + "syntax_md": [ "*`name`* `{...}`" ], + "syntax_html": [ + "Only the first\n
\nproxy_buffer_size\nbytes of data obtained from the server are examined.
name {...}
Defines a group of servers.\nServers can listen on different ports.\nIn addition, servers listening on TCP and UNIX-domain sockets\ncan be mixed.
\n\nExample:
\n\nupstream backend {\n server backend1.example.com:12345 weight=5;\n server 127.0.0.1:12345 max_fails=3 fail_timeout=30s;\n server unix:/tmp/backend2;\n server backend3.example.com:12345 resolve;\n\n server backup1.example.com:12345 backup;\n}\nBy default, connections are distributed between the servers using a\nweighted round-robin balancing method.\nIn the above example, each 7 connections will be distributed as follows:\n5 connections go to backend1.example.com:12345\nand one connection to each of the second and third servers.\nIf an error occurs during communication with a server, the connection will\nbe passed to the next server, and so on until all of the functioning\nservers will be tried.\nIf communication with all servers fails, the connection will be closed.
address [parameters]
Defines the address and other parameters\nof a server.\nThe address can be specified as a domain name or IP address\nwith an obligatory port, or as a UNIX-domain socket path\nspecified after the “unix:” prefix.\nA domain name that resolves to several IP addresses defines\nmultiple servers at once.
The following parameters can be defined:
\n\nweight=number
sets the weight of the server, by default, 1.
max_conns=number
limits the maximum number of simultaneous\nconnections to the proxied server (1.11.5).\nDefault value is zero, meaning there is no limit.\nIf the server group does not reside in the shared memory,\nthe limitation works per each worker process.
\n\nPrior to version 1.11.5, this parameter was available as part of our\ncommercial subscription.
\n
max_fails=number
sets the number of unsuccessful attempts to communicate with the server\nthat should happen in the duration set by the fail_timeout\nparameter to consider the server unavailable for a duration also set by the\nfail_timeout parameter.\nBy default, the number of unsuccessful attempts is set to 1.\nThe zero value disables the accounting of attempts.\nHere, an unsuccessful attempt is an error or timeout\nwhile establishing a connection with the server.
fail_timeout=time
sets
\n\nBy default, the parameter is set to 10 seconds.
backup
marks the server as a backup server.\nConnections to the backup server will be passed\nwhen the primary servers are unavailable.
\n\n\n\nThe parameter cannot be used along with the\n
\nhashandrandomload balancing methods.
down
marks the server as permanently unavailable.
Additionally,\nthe following parameters are available as part of our\ncommercial subscription:
\n\nresolve
monitors changes of the IP addresses\nthat correspond to a domain name of the server,\nand automatically modifies the upstream configuration\nwithout the need of restarting nginx.\nThe server group must reside in the shared memory.
\n\nIn order for this parameter to work,\nthe resolver directive\nmust be specified in the\nstream block\nor in the corresponding upstream block.
service=name
enables resolving of DNS\nSRV\nrecords and sets the service name (1.9.13).\nIn order for this parameter to work, it is necessary to specify\nthe resolve parameter for the server\nand specify a hostname without a port number.
If the service name does not contain a dot (“.”), then\nthe RFC-compliant name\nis constructed\nand the TCP protocol is added to the service prefix.\nFor example, to look up the\n_http._tcp.backend.example.com SRV record,\nit is necessary to specify the directive:
server backend.example.com service=http resolve;\nIf the service name contains one or more dots, then the name is constructed\nby joining the service prefix and the server name.\nFor example, to look up the _http._tcp.backend.example.com\nand server1.backend.example.com SRV records,\nit is necessary to specify the directives:
server backend.example.com service=_http._tcp resolve;\nserver example.com service=server1.backend resolve;\nHighest-priority SRV records\n(records with the same lowest-number priority value)\nare resolved as primary servers,\nthe rest of SRV records are resolved as backup servers.\nIf the backup parameter is specified for the server,\nhigh-priority SRV records are resolved as backup servers,\nthe rest of SRV records are ignored.
slow_start=time
sets the time during which the server will recover its weight\nfrom zero to a nominal value, when unhealthy server becomes\nhealthy,\nor when the server becomes available after a period of time\nit was considered unavailable.\nDefault value is zero, i.e. slow start is disabled.
\n\nThe parameter cannot be used along with the\n
\nhashandrandomload balancing methods.
\n\n" @@ -11957,9 +14352,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "*`name`* [*`size`*]" ], + "syntax_html": [ + "If there is only a single server in a group,
\nmax_fails,\nfail_timeoutandslow_startparameters\nare ignored, and such a server will never be considered unavailable.
name [size]
Defines the name and size of the shared\nmemory zone that keeps the group’s configuration and run-time state that are\nshared between worker processes.\nSeveral groups may share the same zone.\nIn this case, it is enough to specify the size only once.
Additionally,\nas part of our commercial subscription,\nsuch groups allow changing the group membership\nor modifying the settings of a particular server\nwithout the need of restarting nginx.\nThe configuration is accessible via the\nAPI module (1.13.3).
\n\n\n\n" @@ -11970,9 +14368,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "Prior to version 1.13.3,\nthe configuration was accessible only via a special location\nhandled by\n
\nupstream_conf.
file
Specifies a file that keeps the state\nof the dynamically configurable group.
Examples:
\n\nstate /var/lib/nginx/state/servers.conf; # path for Linux\nstate /var/db/nginx/state/servers.conf; # path for FreeBSD\nThe state is currently limited to the list of servers with their parameters.\nThe file is read when parsing the configuration and is updated each time\nthe upstream configuration is\nchanged.\nChanging the file content directly should be avoided.\nThe directive cannot be used\nalong with the server directive.
\n\n" @@ -11983,9 +14384,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "*`key`* [`consistent`]" ], + "syntax_html": [ + "Changes made during\nconfiguration reload\nor binary upgrade\ncan be lost.
\n\nThis directive is available as part of our\ncommercial subscription.
\n
key [consistent]
Specifies a load balancing method for a server group\nwhere the client-server mapping is based on the hashed key value.\nThe key can contain text, variables,\nand their combinations (1.11.2).\nUsage example:
hash $remote_addr;\nNote that adding or removing a server from the group\nmay result in remapping most of the keys to different servers.\nThe method is compatible with the\nCache::Memcached\nPerl library.
\n\nIf the consistent parameter is specified,\nthe ketama\nconsistent hashing method will be used instead.\nThe method ensures that only a few keys\nwill be remapped to different servers\nwhen a server is added to or removed from the group.\nThis helps to achieve a higher cache hit ratio for caching servers.\nThe method is compatible with the\nCache::Memcached::Fast\nPerl library with the ketama_points parameter set to 160.
connect | first_byte | last_byte [inflight]
Specifies that a group should use a load balancing method where a connection\nis passed to the server with the least average time and\nleast number of active connections, taking into account weights of servers.\nIf there are several such servers, they are tried in turn using a\nweighted round-robin balancing method.
\n\nIf the connect parameter is specified,\ntime to\nconnect\nto the upstream server is used.\nIf the first_byte parameter is specified,\ntime to receive the\nfirst byte of data is used.\nIf the last_byte is specified,\ntime to receive the\nlast byte of data is used.\nIf the inflight parameter is specified (1.11.6),\nincomplete connections are also taken into account.
\n\n" @@ -12022,9 +14432,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "[`two` [*`method`*]]" ], + "syntax_html": [ + "Prior to version 1.11.6,\nincomplete connections were taken into account by default.
\n\nThis directive is available as part of our\ncommercial subscription.
\n
[two [method]]
Specifies that a group should use a load balancing method where a connection\nis passed to a randomly selected server, taking into account weights\nof servers.
\n\nThe optional two parameter\ninstructs nginx to randomly select\ntwo\nservers and then choose a server\nusing the specified method.\nThe default method is least_conn\nwhich passes a connection to a server\nwith the least number of active connections.
The least_time method passes a connection to a server\nwith the least average time and least number of active connections.\nIf least_time=connect parameter is specified,\ntime to\nconnect\nto the upstream server is used.\nIf least_time=first_byte parameter is specified,\ntime to receive the\nfirst byte of data is used.\nIf least_time=last_byte is specified,\ntime to receive the\nlast byte of data is used.
\n\n" @@ -12035,9 +14448,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "*`address`* ... [`valid`=*`time`*] [`ipv4`=`on`|`off`] [`ipv6`=`on`|`off`] [`status_zone`=*`zone`*]" ], + "syntax_html": [ + "The
\nleast_timemethod is available as a part of our\ncommercial subscription.
address … [valid=time] [ipv4=on|off] [ipv6=on|off] [status_zone=zone]
Configures name servers used to resolve names of upstream servers\ninto addresses, for example:
\n\nresolver 127.0.0.1 [::1]:5353;\nThe address can be specified as a domain name or IP address,\nwith an optional port.\nIf port is not specified, the port 53 is used.\nName servers are queried in a round-robin fashion.
\n\nBy default, nginx will look up both IPv4 and IPv6 addresses while resolving.\nIf looking up of IPv4 or IPv6 addresses is not desired,\nthe ipv4=off (1.23.1) or\nthe ipv6=off parameter can be specified.
By default, nginx caches answers using the TTL value of a response.\nThe optional valid parameter allows overriding it:
resolver 127.0.0.1 [::1]:5353 valid=30s;\n\n\n\nTo prevent DNS spoofing, it is recommended\nconfiguring DNS servers in a properly secured trusted local network.
\n
The optional status_zone parameter\nenables\ncollection\nof DNS server statistics of requests and responses\nin the specified zone.
\n\n" @@ -12048,9 +14464,12 @@ "contexts": [ "upstream" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "This directive is available as part of our\ncommercial subscription.
\n
time
Sets a timeout for name resolution, for example:
\n\nresolver_timeout 5s;\n\n\n" @@ -12067,7 +14486,10 @@ "contexts": [ "server" ], - "syntax": [ + "syntax_md": [ + "" + ], + "syntax_html": [ "" ], "isBlock": false, @@ -12081,9 +14503,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`number`* *`size`*" ], + "syntax_html": [ + "This directive is available as part of our\ncommercial subscription.
\n
number size
Sets the number and size of the\nper-zone buffers used for pushing zone contents.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.
\n\n" @@ -12095,9 +14520,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "A single buffer must be large enough to hold any entry of each zone being\nsynchronized.
\n
time
Defines an interval between connection attempts to another cluster node.
\n" @@ -12109,9 +14537,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Defines a timeout for establishing a connection with another cluster node.
\n" @@ -12123,9 +14554,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`time`*" ], + "syntax_html": [ + "time
Defines an interval for polling updates in a shared memory zone.
\n" @@ -12137,9 +14571,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`size`*" ], + "syntax_html": [ + "size
Sets size of a per-connection receive buffer used to parse\nincoming stream of synchronization messages.\nThe buffer size must be equal or greater than one of the\nzone_sync_buffers.\nBy default, the buffer size is equal to\nzone_sync_buffers size\nmultiplied by number.
address [resolve]
Defines the address of a cluster node.\nThe address can be specified as a domain name or IP address\nwith a mandatory port, or as a UNIX-domain socket path\nspecified after the “unix:” prefix.\nA domain name that resolves to several IP addresses defines\nmultiple nodes at once.
The resolve parameter instructs nginx to monitor\nchanges of the IP addresses that correspond to a domain name of the node\nand automatically modify the configuration\nwithout the need of restarting nginx.
Cluster nodes are specified either dynamically as a single\nzone_sync_server directive with\nthe resolve parameter, or statically as a series of several\ndirectives without the parameter.
\n\n\nEach cluster node should be specified only once.
\n\nAll cluster nodes should use the same configuration.
\n
In order for the resolve parameter to work,\nthe resolver directive\nmust be specified in the\nstream block.\nExample:
stream {\n resolver 10.0.0.1;\n\n server {\n zone_sync;\n zone_sync_server cluster.example.com:12345 resolve;\n ...\n }\n}\non | off
Enables the SSL/TLS protocol for connections to another cluster server.
\n" @@ -12178,9 +14621,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "file
Specifies a file with the certificate in the PEM format\nused for authentication to another cluster server.
file
Specifies a file with the secret key in the PEM format\nused for authentication to another cluster server.
ciphers
Specifies the enabled ciphers for connections to another cluster server.\nThe ciphers are specified in the format understood by the OpenSSL library.
\n\nThe full list can be viewed using the\n“openssl ciphers” command.
name value
Sets arbitrary OpenSSL configuration\ncommands\nwhen establishing a connection with another cluster server.
\n\n\n\n\nThe directive is supported when using OpenSSL 1.0.2 or higher.
\n
Several zone_sync_ssl_conf_command directives\ncan be specified on the same level.\nThese directives are inherited from the previous configuration level\nif and only if there are\nno zone_sync_ssl_conf_command directives\ndefined on the current level.
\n\n" @@ -12234,9 +14689,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "Note that configuring OpenSSL directly\nmight result in unexpected behavior.
\n
file
Specifies a file with revoked certificates (CRL)\nin the PEM format used to verify\nthe certificate of another cluster server.
name
Allows overriding the server name used to\nverify\nthe certificate of a cluster server and to be\npassed through SNI\nwhen establishing a connection with the cluster server.
\n\nBy default, the host part of the zone_sync_server address is used,\nor resolved IP address if the resolve parameter is specified.
file
Specifies a file with passphrases for\nsecret keys\nwhere each passphrase is specified on a separate line.\nPassphrases are tried in turn when loading the key.
[SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]
Enables the specified protocols for connections to another cluster server.
\n" @@ -12290,9 +14757,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Enables or disables passing of the server name through\nTLS Server Name Indication extension (SNI, RFC 6066)\nwhen establishing a connection with another cluster server.
\n" @@ -12304,9 +14774,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`file`*" ], + "syntax_html": [ + "file
Specifies a file with trusted CA certificates in the PEM format\nused to verify\nthe certificate of another cluster server.
on | off
Enables or disables verification of another cluster server certificate.
\n" @@ -12332,9 +14808,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`number`*" ], + "syntax_html": [ + "number
Sets the verification depth in another cluster server certificates chain.
\n" @@ -12346,9 +14825,12 @@ "stream", "server" ], - "syntax": [ + "syntax_md": [ "*`timeout`*" ], + "syntax_html": [ + "timeout
Sets the timeout between two successive\nread or write operations on connection to another cluster node.\nIf no data is transmitted within this time, the connection is closed.
on | off
Разрешает\nсогласование протокола\nHTTP/3.
\n" @@ -12380,9 +14865,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "on | off
Разрешает согласование протокола HTTP/0.9,\nиспользуемого в\nфункциональных тестах QUIC.
\n" @@ -12394,9 +14882,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`число`*" ], + "syntax_html": [ + "число
Задаёт максимальное число параллельных HTTP/3-потоков\nв соединении.
\n" @@ -12408,9 +14899,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`размер`*" ], + "syntax_html": [ + "размер
Задаёт размер буфера, используемого для чтения и записи\nQUIC-потоков.
\n" @@ -12422,9 +14916,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`число`*" ], + "syntax_html": [ + "число
Устанавливает\nзначение транспортного параметра QUIC active_connection_id_limit.\nЭто максимальное значение ID соединений,\nвозможное для хранения на сервере.
on | off
Разрешает маршрутизацию пакетов QUIC при помощи\neBPF.\nЕсли маршрутизация включена, то обеспечивается поддержка миграции QUIC-соединений.
\n\n\n\n" @@ -12449,9 +14949,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "`on` | `off`" ], + "syntax_html": [ + "Директива поддерживается только на Linux 5.7+.
\n
on | off
Разрешает отправку оптимизированного пакетного режима\nпри помощи segmentation offloading.
\n\n\n\n" @@ -12463,9 +14966,12 @@ "http", "server" ], - "syntax": [ + "syntax_md": [ "*`файл`*" ], + "syntax_html": [ + "Оптимизированная отправка поддерживается только на Linux\nс поддержкой
\nUDP_SEGMENT.
файл
Задаёт файл с секретным ключом, применяемым при шифровании\nstateless reset и address validation токенов.\nПо умолчанию создаётся случайный ключ при каждой перезагрузке.\nТокены, созданные при помощи старых ключей, не принимаются.
on | off
Разрешает функциональность\nQUIC Address Validation,\nв том числе отправку нового токена в Retry-пакете\nили NEW_TOKEN frame\nи\nвалидацию токена, полученного в Initial-пакете.