@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}\nSets 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, see\nRegular expression captures.
\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}\nname …
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
The search is performed in the following order of priority\nand terminates on the first matching variant:
\n\n*.example.com”mail.*”Detailed description of server names is provided in a separate\nServer names document.
\n" + "description_md": "Sets names of a virtual server, for example:\n```\nserver {\n server_name example.com www.example.com;\n}\n```\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:\n```\nserver {\n server_name example.com *.example.com www.example.*;\n}\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}\n```\n\nIt is also possible to use regular expressions in server names,\npreceding the name with a tilde (“`~`”):\n```\nserver {\n server_name www.example.com ~^www\\d+\\.example\\.com$;\n}\n```\n\nRegular expressions can contain captures (0.7.40) that can later\nbe used in other directives (see [Regular expression captures](https://nginx.org/en/docs/regex_captures.html)):\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}\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\\.)?(?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 (see Regular expression captures):
\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
The search is performed in the following order of priority\nand terminates on the first matching variant:
\n\n*.example.com”mail.*”Detailed description of server names is provided in a separate\nServer names document.
\n" }, { "name": "server_name_in_redirect", @@ -5645,8 +5645,8 @@ "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.
When js_import is specified inside a\nlocation,\nthe imported modules are visible only if no JavaScript code\nhas been invoked earlier in the request.\nA single VM is created per request when a\njs_set variable is first accessed\nor when a js_content, js_header_filter,\njs_body_filter, or js_access handler\nis first invoked.\nThe VM is cloned from the configuration scope active at that moment,\nand all subsequent JavaScript invocations within the request reuse it.\nThus, if any of the above is referenced before the request is mapped\nto its final location, for example from a server-level\nset,\nthe VM is bound to the import set of the outer scope, and modules\nimported in the matched location will not be visible.\nTo avoid this, declare such imports in a common parent scope.
\n\n" + "description_md": "Imports a module that implements location, variable,\nand filter 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.\n```\njs_import http.js;\n```\nHere, the module name `http` is used as a namespace\nwhile accessing exports.\nIf the imported module exports `foo()`,\n`http.foo` is used to refer to it.\n\nSeveral `js_import` directives can be specified.\n\nWhen `js_import` is specified inside a\n[`location`](https://nginx.org/en/docs/http/ngx_http_core_module.html#location),\nthe imported modules are visible only if no JavaScript code\nhas been invoked earlier in the request.\nA single VM is created per request when a\n[`js_set`](https://nginx.org/en/docs/http/ngx_http_js_module.html#js_set) variable is first accessed\nor when a [`js_content`](https://nginx.org/en/docs/http/ngx_http_js_module.html#js_content), [`js_header_filter`](https://nginx.org/en/docs/http/ngx_http_js_module.html#js_header_filter),\n[`js_body_filter`](https://nginx.org/en/docs/http/ngx_http_js_module.html#js_body_filter), or [`js_access`](https://nginx.org/en/docs/http/ngx_http_js_module.html#js_access) handler\nis first invoked.\nThe VM is cloned from the configuration scope active at that moment,\nand all subsequent JavaScript invocations within the request reuse it.\nThus, if any of the above is referenced before the request is mapped\nto its final location, for example from a server-level\n[`set`](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#set),\nthe VM is bound to the import set of the outer scope, and modules\nimported in the matched `location` will not be visible.\nTo avoid this, declare such imports in a common parent scope.\n\n> The directive can be specified on the\n> `server` and `location` level\n> since [0.7.7](https://nginx.org/en/docs/njs/changes.html#njs0.7.7).", + "description_html": "The directive can be specified on the\n
\nserverandlocationlevel\nsince 0.7.7.
Imports a module that implements location, variable,\nand filter 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.
When js_import is specified inside a\nlocation,\nthe imported modules are visible only if no JavaScript code\nhas been invoked earlier in the request.\nA single VM is created per request when a\njs_set variable is first accessed\nor when a js_content, js_header_filter,\njs_body_filter, or js_access handler\nis first invoked.\nThe VM is cloned from the configuration scope active at that moment,\nand all subsequent JavaScript invocations within the request reuse it.\nThus, if any of the above is referenced before the request is mapped\nto its final location, for example from a server-level\nset,\nthe VM is bound to the import set of the outer scope, and modules\nimported in the matched location will not be visible.\nTo avoid this, declare such imports in a common parent scope.
\n\n" }, { "name": "js_include", @@ -5711,8 +5711,8 @@ "The directive can be specified on the\n
\nserverandlocationlevel\nsince 0.7.7.
module.function [interval=time] [jitter=number] [worker_affinity=mask]
Specifies a content handler to run at regular interval.\nThe handler receives a\nsession object\nas its first argument,\nit also has access to global objects such as\nngx.
\n\nThe optional interval parameter\nsets the interval between two consecutive runs,\nby default, 5 seconds.
The optional jitter parameter sets the time within which\nthe location content handler will be randomly delayed,\nby default, there is no delay.
By default, the js_handler is executed on worker process 0.\nThe optional worker_affinity parameter\nallows specifying particular worker processes\nwhere the location content handler should be executed.\nEach worker process set is represented by a bitmask of allowed worker processes.\nThe all mask allows the handler to be executed\nin all worker processes.
Example:
\n\nexample.conf:\n\nlocation @periodics {\n # to be run at 1 minute intervals in worker process 0\n js_periodic main.handler interval=60s;\n\n # to be run at 1 minute intervals in all worker processes\n js_periodic main.handler interval=60s worker_affinity=all;\n\n # to be run at 1 minute intervals in worker processes 1 and 3\n js_periodic main.handler interval=60s worker_affinity=0101;\n\n resolver 10.0.0.1;\n js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;\n}\n\nexample.js:\n\nasync function handler(s) {\n let reply = await ngx.fetch('https://nginx.org/en/docs/njs/');\n let body = await reply.text();\n\n ngx.log(ngx.INFO, body);\n}\nSpecifies a content handler to run at regular interval.\nThe handler receives a\nsession object\nas its first argument,\nit also has access to global objects such as\nngx.
\n\nThe optional interval parameter\nsets the interval between two consecutive runs,\nby default, 5 seconds.
The optional jitter parameter sets the time within which\nthe location content handler will be randomly delayed,\nby default, there is no delay.
By default, the js_periodic handler\nis executed on worker process 0.\nThe optional worker_affinity parameter\nallows specifying particular worker processes\nwhere the location content handler should be executed.\nEach worker process set is represented by a bitmask of allowed worker processes.\nThe all mask allows the handler to be executed\nin all worker processes.
Example:
\n\nexample.conf:\n\nlocation @periodics {\n # to be run at 1 minute intervals in worker process 0\n js_periodic main.handler interval=60s;\n\n # to be run at 1 minute intervals in all worker processes\n js_periodic main.handler interval=60s worker_affinity=all;\n\n # to be run at 1 minute intervals in worker processes 1 and 3\n js_periodic main.handler interval=60s worker_affinity=0101;\n\n resolver 10.0.0.1;\n js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;\n}\n\nexample.js:\n\nasync function handler(s) {\n let reply = await ngx.fetch('https://nginx.org/en/docs/njs/');\n let body = await reply.text();\n\n ngx.log(ngx.INFO, body);\n}\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).
The search is performed in the following order of priority\nand terminates on the first matching variant:
\n\n*.example.com”mail.*”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.\nThe regular expressions are matched when the resulting variable is\nevaluated, and a successful match replaces the positional captures\n“$1”…“$9”\nset by previously matched regular expressions, see\nRegular expression captures.
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).
The search is performed in the following order of priority\nand terminates on the first matching variant:
\n\n*.example.com”mail.*”(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" + "description_md": "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\n`if` directive.\nConfigurations inside the `if` directives are\ninherited from the previous configuration level.\n\nA condition may be any of the following:\n- a variable name; false if the value of a variable is an empty string\n or “`0`”;\n > Before version 1.0.1, any string starting with “`0`”\n > was considered a false value.\n- comparison of a variable with a string using the\n “`=`” and “`!=`” operators;\n- matching of a variable against a regular expression using the\n “`~`” (for case-sensitive matching) and\n “`~*`” (for case-insensitive matching) operators.\n Regular expressions can contain captures that are made available for\n later reuse in the `$1`..`$9` variables\n (see [Regular expression captures](https://nginx.org/en/docs/regex_captures.html)).\n Negative operators “`!~`” and “`!~*`”\n are also available.\n If a regular expression includes the “`}`”\n or “`;`” characters, the whole expressions should be enclosed\n in single or double quotes.\n- checking of a file existence with the “`-f`” and\n “`!-f`” operators;\n- checking of a directory existence with the “`-d`” and\n “`!-d`” operators;\n- checking of a file, directory, or symbolic link existence with the\n “`-e`” and “`!-e`” operators;\n- checking for an executable file with the “`-x`”\n and “`!-x`” operators.\n\nExamples:\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> A value of the `$invalid_referer` embedded variable is set by the\n> [`valid_referers`](https://nginx.org/en/docs/http/ngx_http_referer_module.html#valid_referers) directive.", + "description_html": "A value of the
\n$invalid_refererembedded variable is set by the\nvalid_referersdirective.
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\n(see Regular expression captures).\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" }, { "name": "return", @@ -15413,8 +15413,8 @@ "A value of the
\n$invalid_refererembedded variable is set by the\nvalid_referersdirective.
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 that can later\nbe used in other directives:
\n\nserver {\n server_name ~^(www\\.)?(.+)$;\n\n proxy_pass www.$2:12345;\n}\nNamed captures in regular expressions create variables\nthat can later be used in other directives:
\n\nserver {\n server_name ~^(www\\.)?(?<domain>.+)$;\n\n proxy_pass www.$domain:12345;\n}\nIf the directive’s parameter is set to “$hostname”, the\nmachine’s hostname is inserted.
The search is performed in the following order of priority\nand terminates on the first matching variant:
\n\n*.example.com”mail.*”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 that can later\nbe used in other directives (see Regular expression captures):
\n\nserver {\n server_name ~^(www\\.)?(.+)$;\n\n proxy_pass www.$2:12345;\n}\nNamed captures in regular expressions create variables\nthat can later be used in other directives:
\n\nserver {\n server_name ~^(www\\.)?(?<domain>.+)$;\n\n proxy_pass www.$domain:12345;\n}\nIf the directive’s parameter is set to “$hostname”, the\nmachine’s hostname is inserted.
The search is performed in the following order of priority\nand terminates on the first matching variant:
\n\n*.example.com”mail.*”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" + "description_md": "Imports a module that implements session 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.\n```\njs_import stream.js;\n```\nHere, the module name `stream` is used as a namespace\nwhile accessing exports.\nIf the imported module exports `foo()`,\n`stream.foo` is used to refer to it.\n\nSeveral `js_import` directives can be specified.\n\n> The directive can be specified on the\n> `server` level\n> since [0.7.7](https://nginx.org/en/docs/njs/changes.html#njs0.7.7).", + "description_html": "The directive can be specified on the\n
\nserverlevel\nsince 0.7.7.
Imports a module that implements session 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" }, { "name": "js_include", @@ -16080,8 +16080,8 @@ "The directive can be specified on the\n
\nserverlevel\nsince 0.7.7.
module.function [interval=time] [jitter=number] [worker_affinity=mask]
Specifies a content handler to run at regular interval.\nThe handler receives a\nsession object\nas its first argument,\nit also has access to global objects such as\nngx.
\n\nThe optional interval parameter\nsets the interval between two consecutive runs,\nby default, 5 seconds.
The optional jitter parameter sets the time within which\nthe location content handler will be randomly delayed,\nby default, there is no delay.
By default, the js_handler is executed on worker process 0.\nThe optional worker_affinity parameter\nallows specifying particular worker processes\nwhere the location content handler should be executed.\nEach worker process set is represented by a bitmask of allowed worker processes.\nThe all mask allows the handler to be executed\nin all worker processes.
Example:
\n\nexample.conf:\n\nlocation @periodics {\n # to be run at 1 minute intervals in worker process 0\n js_periodic main.handler interval=60s;\n\n # to be run at 1 minute intervals in all worker processes\n js_periodic main.handler interval=60s worker_affinity=all;\n\n # to be run at 1 minute intervals in worker processes 1 and 3\n js_periodic main.handler interval=60s worker_affinity=0101;\n\n resolver 10.0.0.1;\n js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;\n}\n\nexample.js:\n\nasync function handler(s) {\n let reply = await ngx.fetch('https://nginx.org/en/docs/njs/');\n let body = await reply.text();\n\n ngx.log(ngx.INFO, body);\n}\nSpecifies a content handler to run at regular interval.\nThe handler receives a\nsession object\nas its first argument,\nit also has access to global objects such as\nngx.
\n\nThe optional interval parameter\nsets the interval between two consecutive runs,\nby default, 5 seconds.
The optional jitter parameter sets the time within which\nthe location content handler will be randomly delayed,\nby default, there is no delay.
By default, the js_periodic handler\nis executed on worker process 0.\nThe optional worker_affinity parameter\nallows specifying particular worker processes\nwhere the location content handler should be executed.\nEach worker process set is represented by a bitmask of allowed worker processes.\nThe all mask allows the handler to be executed\nin all worker processes.
Example:
\n\nexample.conf:\n\nlocation @periodics {\n # to be run at 1 minute intervals in worker process 0\n js_periodic main.handler interval=60s;\n\n # to be run at 1 minute intervals in all worker processes\n js_periodic main.handler interval=60s worker_affinity=all;\n\n # to be run at 1 minute intervals in worker processes 1 and 3\n js_periodic main.handler interval=60s worker_affinity=0101;\n\n resolver 10.0.0.1;\n js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;\n}\n\nexample.js:\n\nasync function handler(s) {\n let reply = await ngx.fetch('https://nginx.org/en/docs/njs/');\n let body = await reply.text();\n\n ngx.log(ngx.INFO, body);\n}\n$variable module.function [nocache]
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.
Since 0.8.6, when\noptional argument nocache is provided the handler\nis called every time it is referenced.\nDue to current limitations\nof the rewrite module,\nwhen a nocache variable is referenced by the\nset directive\nits handler should always return a fixed-length value.
\n\n" + "description_md": "Sets an njs `function`\nfor the specified `variable`.\nSince [0.4.0](https://nginx.org/en/docs/njs/changes.html#njs0.4.0),\na module function can be referenced.\n\nThe function is called when\nthe variable is referenced for the first time for a given request.\nThe exact moment depends on a\n[phase](https://nginx.org/en/docs/stream/stream_processing.html)\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\n[`log_format`](https://nginx.org/en/docs/stream/ngx_stream_log_module.html#log_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\nSince [0.8.6](https://nginx.org/en/docs/njs/changes.html#njs0.8.6), when\noptional argument `nocache` is provided the handler\nis called every time it is referenced.\nDue to current limitations\nof the [ngx_stream_set_module](https://nginx.org/en/docs/stream/ngx_stream_set_module.html) module,\nwhen a `nocache` variable is referenced by the\n[set](https://nginx.org/en/docs/stream/ngx_stream_set_module.html#set) directive\nits handler should always return a fixed-length value.\n\n> As the `js_set` handler\n> returns its result immediately, it supports\n> only synchronous callbacks.\n> Thus, asynchronous callbacks such as\n> [ngx.fetch()](https://nginx.org/en/docs/njs/reference.html#ngx_fetch)\n> or\n> [setTimeout()](https://nginx.org/en/docs/njs/reference.html#settimeout)\n> are not supported.\n\n> The directive can be specified on the\n> `server` level\n> since [0.7.7](https://nginx.org/en/docs/njs/changes.html#njs0.7.7).", + "description_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.
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.
Since 0.8.6, when\noptional argument nocache is provided the handler\nis called every time it is referenced.\nDue to current limitations\nof the ngx_stream_set_module module,\nwhen a nocache variable is referenced by the\nset directive\nits handler should always return a fixed-length value.
\n\n" }, { "name": "js_shared_dict_zone", @@ -16364,8 +16364,8 @@ "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.
string $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).
The search is performed in the following order of priority\nand terminates on the first matching variant:
\n\n*.example.com”mail.*”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.\nThe regular expressions are matched when the resulting variable is\nevaluated, and a successful match replaces the positional captures\n“$1”…“$9”\nset by previously matched regular expressions, see\nRegular expression captures.
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).
The search is performed in the following order of priority\nand terminates on the first matching variant:
\n\n*.example.com”mail.*”