From e17e6d1eac73a76ab3fa83b4d0d6ec61e851480a Mon Sep 17 00:00:00 2001 From: Ryan Davis Date: Fri, 7 Jun 2024 16:27:43 -0400 Subject: [PATCH 1/3] feat: parse XML for module-defined variables --- reference-converter/internal/output/output.go | 14 +++ .../internal/parse/elements.go | 101 +++++++++++++++++- .../internal/parse/parse_test.go | 17 +++ .../internal/parse/testdata/module.xml | 17 +++ 4 files changed, 144 insertions(+), 5 deletions(-) diff --git a/reference-converter/internal/output/output.go b/reference-converter/internal/output/output.go index 6da0ffd..27a8404 100644 --- a/reference-converter/internal/output/output.go +++ b/reference-converter/internal/output/output.go @@ -21,10 +21,17 @@ type Directive struct { DescriptionHtml string `json:"description_html"` } +type Variable struct { + Name string `json:"name"` + DescriptionMd string `json:"description_md"` + DescriptionHtml string `json:"description_html"` +} + type Module struct { Id string `json:"id"` Name string `json:"name"` Directives []Directive `json:"directives"` + Variables []Variable `json:"variables,omitempty"` } func toModule(m *parse.Module) Module { @@ -45,6 +52,13 @@ func toModule(m *parse.Module) Module { DescriptionHtml: directive.Prose.ToHTML(), }) } + for _, variable := range section.Variables { + module.Variables = append(module.Variables, Variable{ + Name: variable.Name, + DescriptionMd: variable.Prose.ToMarkdown(), + DescriptionHtml: variable.Prose.ToHTML(), + }) + } } return module } diff --git a/reference-converter/internal/parse/elements.go b/reference-converter/internal/parse/elements.go index da1428d..abd5789 100644 --- a/reference-converter/internal/parse/elements.go +++ b/reference-converter/internal/parse/elements.go @@ -3,11 +3,12 @@ package parse import ( "encoding/xml" "fmt" + "regexp" + "strings" + "github.com/gomarkdown/markdown" "github.com/gomarkdown/markdown/html" "github.com/gomarkdown/markdown/parser" - "regexp" - "strings" ) // Syntax contain the markdown formatted syntax for the directive, very close to @@ -153,10 +154,100 @@ type Directive struct { Prose Prose `xml:"para"` } +// Variable represents an NGINX variable defined by a module, e.g $binary_remote_addr. +type Variable struct { + Name string + Prose Prose +} + +// unmarshalVariablesCML extracts NGINX variables from the common pattern: +// +//
+// +// $VARIABLE_NAME +// $DOCUMENTATION +// $VARIABLE_NAME$DYNAMIC_SUFFIX +// $DOCUMENTATION +// +//
+func unmarshalVariablesCML(d *xml.Decoder, start xml.StartElement) ([]Variable, error) { + var v struct { + ID string `xml:"id,attr"` + Paragraphs []struct { + List struct { + TagNames []struct { + Name string `xml:"var"` + Suffix string `xml:"value"` + } `xml:"tag-name"` + TagDesc []Prose `xml:"tag-desc"` + } `xml:"list"` + } `xml:"para"` + } + if err := d.DecodeElement(&v, &start); err != nil { + return nil, fmt.Errorf("failed to parse variables: %w", err) + } + var vs []Variable + for _, para := range v.Paragraphs { + if len(para.List.TagDesc) != len(para.List.TagNames) { + return nil, fmt.Errorf( + "invalid variables section, need to have the same number of names (%d) and descriptions (%d)", + len(para.List.TagNames), len(para.List.TagDesc), + ) + } + for idx, tn := range para.List.TagNames { + name := tn.Name + if tn.Suffix != "" { + name += strings.ToUpper(tn.Suffix) + } + vs = append(vs, Variable{ + Name: name, + Prose: para.List.TagDesc[idx], + }) + } + } + + return vs, nil +} + type Section struct { - ID string `xml:"id,attr"` - Directives []Directive `xml:"directive"` - Prose Prose `xml:"para"` + ID string + Directives []Directive + Prose Prose + Variables []Variable +} + +// UnmarshalXML handles parsing sections with directives vs sections with variables. +func (s *Section) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error { + attrs := newAttrs(start.Attr) + if attrs["id"] == "variables" { + // parse as a list of variables + vs, err := unmarshalVariablesCML(d, start) + if err != nil { + return fmt.Errorf("failed to unmarshall variables: %w", err) + } + *s = Section{ + ID: "variables", + Variables: vs, + } + return nil + } + + // parse as a normal section + var sec struct { + ID string `xml:"id,attr"` + Directives []Directive `xml:"directive"` + Prose Prose `xml:"para"` + } + if err := d.DecodeElement(&sec, &start); err != nil { + return err + } + + *s = Section{ + ID: sec.ID, + Directives: sec.Directives, + Prose: sec.Prose, + } + return nil } type Module struct { diff --git a/reference-converter/internal/parse/parse_test.go b/reference-converter/internal/parse/parse_test.go index ae4ef8d..14dc558 100644 --- a/reference-converter/internal/parse/parse_test.go +++ b/reference-converter/internal/parse/parse_test.go @@ -41,6 +41,23 @@ func TestParse(t *testing.T) { }, }, }, + { + ID: "variables", + Variables: []parse.Variable{ + { + Name: "$wildcard_var_NAME", + Prose: parse.Prose{ + {Content: "\nI support a dynamic suffix *`name`*\n"}, + }, + }, + { + Name: "$variable", + Prose: parse.Prose{ + {Content: "\nI am a variable with `formatting` in my desc\n"}, + }, + }, + }, + }, }, }, }, diff --git a/reference-converter/internal/parse/testdata/module.xml b/reference-converter/internal/parse/testdata/module.xml index 864cb07..d2f2377 100644 --- a/reference-converter/internal/parse/testdata/module.xml +++ b/reference-converter/internal/parse/testdata/module.xml @@ -27,4 +27,21 @@ Can have more than one, with some html—ish entities and verb +
+We add these variables: + + + +$wildcard_var_name + +I support a dynamic suffix name + + +$variable + +I am a variable with formatting in my desc + + + +
From 4f0e9789145727f11217ecc07b9c8a60cf8ce977 Mon Sep 17 00:00:00 2001 From: Ryan Davis Date: Fri, 7 Jun 2024 16:53:17 -0400 Subject: [PATCH 2/3] feat: new funcs to see variables New function and new data file from running the converter. --- examples/autocomplete/index.ts | 20 +- reference-lib/index.ts | 88 +- reference-lib/package.json | 2 +- .../src/__mocks__/reference_mock.json | 29 +- reference-lib/src/reference.json | 968 +++++++++++++++++- reference-lib/tests/index.test.ts | 88 +- 6 files changed, 1123 insertions(+), 72 deletions(-) diff --git a/examples/autocomplete/index.ts b/examples/autocomplete/index.ts index 34259d7..ee8b98e 100644 --- a/examples/autocomplete/index.ts +++ b/examples/autocomplete/index.ts @@ -1,4 +1,9 @@ -import { getDirectives, Format, Directive } from '@nginx/reference-lib' +import { + getDirectives, + Format, + Directive, + getVariables, +} from '@nginx/reference-lib' type autocomplete = { /** name of the NGINX module */ m: string @@ -10,10 +15,10 @@ type autocomplete = { * nginx config */ v?: string /** markdown CSV for valid contexts */ - c: string + c?: string /** markdown-formatted syntax specifications, including directive name. * Multiple syntaxes are seperated by newlines */ - s: string + s?: string } function toAutocomplete(d: Directive): autocomplete { @@ -32,5 +37,10 @@ function toAutocomplete(d: Directive): autocomplete { return ret } -const formatted = getDirectives(Format.Markdown).map(toAutocomplete) -console.log(JSON.stringify(formatted, undefined, 4)) +const directives = getDirectives(Format.Markdown).map(toAutocomplete) +const variables = getVariables(Format.Markdown).map((v) => ({ + m: v.module, + n: v.name, + d: v.description, +})) +console.log(JSON.stringify(directives.concat(variables), undefined, 4)) diff --git a/reference-lib/index.ts b/reference-lib/index.ts index fce6fd3..62143c1 100644 --- a/reference-lib/index.ts +++ b/reference-lib/index.ts @@ -1,13 +1,19 @@ import reference from './src/reference.json' export interface Directive { - name: string - module: string - description: string - syntax: string[] - contexts: string[] - isBlock: boolean - default: string + name: string + module: string + description: string + syntax: string[] + contexts: string[] + isBlock: boolean + default: string +} + +export interface Variable { + name: string + module: string + description: string } export enum Format { @@ -41,26 +47,47 @@ for (const modules of reference.modules) { * Returns all the nginx directives * * @param: format: format of the return type HTML or markdown - * * @return: an array of Directives */ -export function getDirectives(format=Format.HTML): Directive[] { - const directives = reference.modules.flatMap((m) => - m.directives.map((d) => ({...d, module: m.name}))) - .map ((d) => ({ - name: d.name, - module: d.module, - description: format === Format.HTML ? d.description_html : d.description_md, - syntax: format === Format.HTML ? d.syntax_html : d.syntax_md, - contexts: d.contexts, - isBlock: d.isBlock, - default: d.default - } as Directive)) - return directives +export function getDirectives(format = Format.HTML): Directive[] { + const directives = reference.modules + .flatMap((m) => m.directives.map((d) => ({ ...d, module: m.name }))) + .map( + (d) => + ({ + name: d.name, + module: d.module, + description: + format === Format.HTML ? d.description_html : d.description_md, + syntax: format === Format.HTML ? d.syntax_html : d.syntax_md, + contexts: d.contexts, + isBlock: d.isBlock, + default: d.default, + } as Directive) + ) + return directives +} + +/** + * Returns all variables defined by any moduled + * + * @param: format: format of the return type HTML or markdown + * @return: an array of Variables + */ +export function getVariables(format = Format.HTML): Variable[] { + return reference.modules.flatMap( + (m) => + m.variables?.map((v) => ({ + name: v.name, + description: + format === Format.HTML ? v.description_html : v.description_md, + module: m.name, + })) ?? [] + ) } /** - * Returns the description corresponding to the directive name + * Returns the description corresponding to the directive or variable name * * @param: directive: directive name to find * @param: module: optional name of module @@ -68,10 +95,15 @@ export function getDirectives(format=Format.HTML): Directive[] { * * @return: a string containing the description of the directive in xml or markdown format */ -export function find(directive: string, module: string | undefined, format=Format.HTML): string | undefined { - const data = - module - ? refDirectives.get(directive)?.find((d) => d.module.toUpperCase() === module.toUpperCase()) - : refDirectives.get(directive)?.at(0) - return (format === Format.HTML ? data?.description_html : data?.description_md) +export function find( + directive: string, + module: string | undefined, + format = Format.HTML +): string | undefined { + const data = module + ? refDirectives + .get(directive) + ?.find((d) => d.module.toUpperCase() === module.toUpperCase()) + : refDirectives.get(directive)?.at(0) + return format === Format.HTML ? data?.description_html : data?.description_md } diff --git a/reference-lib/package.json b/reference-lib/package.json index 3866a1b..db60fad 100644 --- a/reference-lib/package.json +++ b/reference-lib/package.json @@ -1,6 +1,6 @@ { "name": "@nginx/reference-lib", - "version": "1.0.14", + "version": "1.1.0", "description": "", "main": "dist/index.js", "type": "module", diff --git a/reference-lib/src/__mocks__/reference_mock.json b/reference-lib/src/__mocks__/reference_mock.json index 64e8b91..1e06ad9 100644 --- a/reference-lib/src/__mocks__/reference_mock.json +++ b/reference-lib/src/__mocks__/reference_mock.json @@ -1,4 +1,5 @@ -{"modules": [ +{ + "modules": [ { "id": "/en/docs/http/ngx_http_access_module.html", "name": "ngx_http_access_module", @@ -6,21 +7,23 @@ { "name": "allow", "default": "", - "contexts": [ - "http", - "server", - "location", - "limit_except" - ], - "syntax_md": [ - "*`address`* | *`CIDR`* | `unix:` | `all`" - ], + "contexts": ["http", "server", "location", "limit_except"], + "syntax_md": ["*`address`* | *`CIDR`* | `unix:` | `all`"], "syntax_html": [ "

address | CIDR | unix: | all

\n" ], "isBlock": false, "description_md": "Allows access for the specified network or address.", "description_html": "\u003cp\u003eAllows access for the specified network or address\u003c/p\u003e" - }] - }] - } + } + ], + "variables": [ + { + "name": "$gzip_ratio", + "description_md": "achieved compression ratio, computed as the ratio between the\noriginal and compressed response sizes.", + "description_html": "

achieved compression ratio, computed as the ratio between the\noriginal and compressed response sizes.

\n" + } + ] + } + ] +} diff --git a/reference-lib/src/reference.json b/reference-lib/src/reference.json index e7ac81e..7b134ef 100644 --- a/reference-lib/src/reference.json +++ b/reference-lib/src/reference.json @@ -355,6 +355,23 @@ "description_md": "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;\n```\n\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`.", "description_html": "

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\n
map $jwt_claim_iss $valid_jwt_iss {\n    "good" 1;\n}\n...\n\nauth_jwt_require $valid_jwt_iss;\n
\n\n

If 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.

\n" } + ], + "variables": [ + { + "name": "$jwt_header_NAME", + "description_md": "returns the value of a specified\n[JOSE header](https://datatracker.ietf.org/doc/html/rfc7515#section-4)", + "description_html": "

returns the value of a specified\nJOSE header

\n" + }, + { + "name": "$jwt_claim_NAME", + "description_md": "returns the value of a specified\n[JWT claim](https://datatracker.ietf.org/doc/html/rfc7519#section-4)\n\n\nFor nested claims and claims including a dot (“.”),\nthe value of the variable cannot be evaluated;\nthe [`auth_jwt_claim_set`](https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_claim_set) directive should be used instead.\n\n\n\nVariable values for tokens encrypted with JWE\nare available only after decryption which occurs during the\n[Access](https://nginx.org/en/docs/dev/development_guide.html#http_phases) phase.", + "description_html": "

returns the value of a specified\nJWT claim

\n\n

For nested claims and claims including a dot (“.”),\nthe value of the variable cannot be evaluated;\nthe auth_jwt_claim_set directive should be used instead.

\n\n

Variable values for tokens encrypted with JWE\nare available only after decryption which occurs during the\nAccess phase.

\n" + }, + { + "name": "$jwt_payload", + "description_md": "returns the decrypted top-level payload\nof `nested`\nor `encrypted` tokens (1.21.2).\nFor nested tokens returns the enclosed JWS token.\nFor encrypted tokens returns JSON with claims.", + "description_html": "

returns the decrypted top-level payload\nof nested\nor encrypted tokens (1.21.2).\nFor nested tokens returns the enclosed JWS token.\nFor encrypted tokens returns JSON with claims.

\n" + } ] }, { @@ -2065,6 +2082,283 @@ "description_md": "Sets the maximum *`size`* of the variables hash table.\nThe details of setting up hash tables are provided in a separate\n[document](https://nginx.org/en/docs/hash.html).\n> Prior to version 1.5.13, the default value was 512.", "description_html": "

Sets the maximum size of the variables hash table.\nThe details of setting up hash tables are provided in a separate\ndocument.

\n\n
\n

Prior to version 1.5.13, the default value was 512.

\n
\n" } + ], + "variables": [ + { + "name": "$arg_NAME", + "description_md": "argument *`name`* in the request line", + "description_html": "

argument name in the request line

\n" + }, + { + "name": "$args", + "description_md": "arguments in the request line", + "description_html": "

arguments in the request line

\n" + }, + { + "name": "$binary_remote_addr", + "description_md": "client address in a binary form, value’s length is always 4 bytes\nfor IPv4 addresses or 16 bytes for IPv6 addresses", + "description_html": "

client address in a binary form, value’s length is always 4 bytes\nfor IPv4 addresses or 16 bytes for IPv6 addresses

\n" + }, + { + "name": "$body_bytes_sent", + "description_md": "number of bytes sent to a client, not counting the response header;\nthis variable is compatible with the “`%B`” parameter of the\n`mod_log_config`\nApache module", + "description_html": "

number of bytes sent to a client, not counting the response header;\nthis variable is compatible with the “%B” parameter of the\nmod_log_config\nApache module

\n" + }, + { + "name": "$bytes_sent", + "description_md": "number of bytes sent to a client (1.3.8, 1.2.5)", + "description_html": "

number of bytes sent to a client (1.3.8, 1.2.5)

\n" + }, + { + "name": "$connection", + "description_md": "connection serial number (1.3.8, 1.2.5)", + "description_html": "

connection serial number (1.3.8, 1.2.5)

\n" + }, + { + "name": "$connection_requests", + "description_md": "current number of requests made through a connection (1.3.8, 1.2.5)", + "description_html": "

current number of requests made through a connection (1.3.8, 1.2.5)

\n" + }, + { + "name": "$connection_time", + "description_md": "connection time in seconds with a milliseconds resolution (1.19.10)", + "description_html": "

connection time in seconds with a milliseconds resolution (1.19.10)

\n" + }, + { + "name": "$content_length", + "description_md": "\"Content-Length\" request header field", + "description_html": "

“Content-Length” request header field

\n" + }, + { + "name": "$content_type", + "description_md": "\"Content-Type\" request header field", + "description_html": "

“Content-Type” request header field

\n" + }, + { + "name": "$cookie_NAME", + "description_md": "the *`name`* cookie", + "description_html": "

the name cookie

\n" + }, + { + "name": "$document_root", + "description_md": "[`root`](https://nginx.org/en/docs/http/ngx_http_core_module.html#root) or [`alias`](https://nginx.org/en/docs/http/ngx_http_core_module.html#alias) directive’s value\nfor the current request", + "description_html": "

root or alias directive’s value\nfor the current request

\n" + }, + { + "name": "$document_uri", + "description_md": "same as `$uri`", + "description_html": "

same as $uri

\n" + }, + { + "name": "$host", + "description_md": "in this order of precedence:\nhost name from the request line, or\nhost name from the \"Host\" request header field, or\nthe server name matching a request", + "description_html": "

in this order of precedence:\nhost name from the request line, or\nhost name from the “Host” request header field, or\nthe server name matching a request

\n" + }, + { + "name": "$hostname", + "description_md": "host name", + "description_html": "

host name

\n" + }, + { + "name": "$http_NAME", + "description_md": "arbitrary request header field;\nthe last part of a variable name is the field name converted\nto lower case with dashes replaced by underscores", + "description_html": "

arbitrary request header field;\nthe last part of a variable name is the field name converted\nto lower case with dashes replaced by underscores

\n" + }, + { + "name": "$https", + "description_md": "“`on`”\nif connection operates in SSL mode,\nor an empty string otherwise", + "description_html": "

“on”\nif connection operates in SSL mode,\nor an empty string otherwise

\n" + }, + { + "name": "$is_args", + "description_md": "“`?`” if a request line has arguments,\nor an empty string otherwise", + "description_html": "

“?” if a request line has arguments,\nor an empty string otherwise

\n" + }, + { + "name": "$limit_rate", + "description_md": "setting this variable enables response rate limiting;\nsee [`limit_rate`](https://nginx.org/en/docs/http/ngx_http_core_module.html#limit_rate)", + "description_html": "

setting this variable enables response rate limiting;\nsee limit_rate

\n" + }, + { + "name": "$msec", + "description_md": "current time in seconds with the milliseconds resolution (1.3.9, 1.2.6)", + "description_html": "

current time in seconds with the milliseconds resolution (1.3.9, 1.2.6)

\n" + }, + { + "name": "$nginx_version", + "description_md": "nginx version", + "description_html": "

nginx version

\n" + }, + { + "name": "$pid", + "description_md": "PID of the worker process", + "description_html": "

PID of the worker process

\n" + }, + { + "name": "$pipe", + "description_md": "“`p`” if request was pipelined, “`.`”\notherwise (1.3.12, 1.2.7)", + "description_html": "

“p” if request was pipelined, “.”\notherwise (1.3.12, 1.2.7)

\n" + }, + { + "name": "$proxy_protocol_addr", + "description_md": "client address from the PROXY protocol header (1.5.12)\n\nThe PROXY protocol must be previously enabled by setting the\n`proxy_protocol` parameter\nin the [`listen`](https://nginx.org/en/docs/http/ngx_http_core_module.html#listen) directive.", + "description_html": "

client address from the PROXY protocol header (1.5.12)

\n\n

The PROXY protocol must be previously enabled by setting the\nproxy_protocol parameter\nin the listen directive.

\n" + }, + { + "name": "$proxy_protocol_port", + "description_md": "client port from the PROXY protocol header (1.11.0)\n\nThe PROXY protocol must be previously enabled by setting the\n`proxy_protocol` parameter\nin the [`listen`](https://nginx.org/en/docs/http/ngx_http_core_module.html#listen) directive.", + "description_html": "

client port from the PROXY protocol header (1.11.0)

\n\n

The PROXY protocol must be previously enabled by setting the\nproxy_protocol parameter\nin the listen directive.

\n" + }, + { + "name": "$proxy_protocol_server_addr", + "description_md": "server address from the PROXY protocol header (1.17.6)\n\nThe PROXY protocol must be previously enabled by setting the\n`proxy_protocol` parameter\nin the [`listen`](https://nginx.org/en/docs/http/ngx_http_core_module.html#listen) directive.", + "description_html": "

server address from the PROXY protocol header (1.17.6)

\n\n

The PROXY protocol must be previously enabled by setting the\nproxy_protocol parameter\nin the listen directive.

\n" + }, + { + "name": "$proxy_protocol_server_port", + "description_md": "server port from the PROXY protocol header (1.17.6)\n\nThe PROXY protocol must be previously enabled by setting the\n`proxy_protocol` parameter\nin the [`listen`](https://nginx.org/en/docs/http/ngx_http_core_module.html#listen) directive.", + "description_html": "

server port from the PROXY protocol header (1.17.6)

\n\n

The PROXY protocol must be previously enabled by setting the\nproxy_protocol parameter\nin the listen directive.

\n" + }, + { + "name": "$proxy_protocol_tlv_NAME", + "description_md": "TLV from the PROXY Protocol header (1.23.2).\nThe `name` can be a TLV type name or its numeric value.\nIn the latter case, the value is hexadecimal\nand should be prefixed with `0x`:\n\n```\n$proxy_protocol_tlv_alpn\n$proxy_protocol_tlv_0x01\n```\nSSL TLVs can also be accessed by TLV type name\nor its numeric value,\nboth prefixed by `ssl_`:\n```\n$proxy_protocol_tlv_ssl_version\n$proxy_protocol_tlv_ssl_0x21\n```\n\n\nThe following TLV type names are supported:\n- `alpn` (`0x01`)—\n upper layer protocol used over the connection\n- `authority` (`0x02`)—\n host name value passed by the client\n- `unique_id` (`0x05`)—\n unique connection id\n- `netns` (`0x30`)—\n name of the namespace\n- `ssl` (`0x20`)—\n binary SSL TLV structure\n\n\n\n\nThe following SSL TLV type names are supported:\n- `ssl_version` (`0x21`)—\n SSL version used in client connection\n- `ssl_cn` (`0x22`)—\n SSL certificate Common Name\n- `ssl_cipher` (`0x23`)—\n name of the used cipher\n- `ssl_sig_alg` (`0x24`)—\n algorithm used to sign the certificate\n- `ssl_key_alg` (`0x25`)—\n public-key algorithm\n\n\n\n\nAlso, the following special SSL TLV type name is supported:\n- `ssl_verify`—\n client SSL certificate verification result,\n `0` if the client presented a certificate\n and it was successfully verified,\n non-zero otherwise.\n\n\n\n\nThe PROXY protocol must be previously enabled by setting the\n`proxy_protocol` parameter\nin the [`listen`](https://nginx.org/en/docs/http/ngx_http_core_module.html#listen) directive.", + "description_html": "

TLV from the PROXY Protocol header (1.23.2).\nThe name can be a TLV type name or its numeric value.\nIn the latter case, the value is hexadecimal\nand should be prefixed with 0x:

\n\n
$proxy_protocol_tlv_alpn\n$proxy_protocol_tlv_0x01\n
\n\n

SSL TLVs can also be accessed by TLV type name\nor its numeric value,\nboth prefixed by ssl_:

\n\n
$proxy_protocol_tlv_ssl_version\n$proxy_protocol_tlv_ssl_0x21\n
\n\n

The following TLV type names are supported:

\n\n
    \n
  • alpn (0x01)—\nupper layer protocol used over the connection
    • \n
  • authority (0x02)—\nhost name value passed by the client
    • \n
  • unique_id (0x05)—\nunique connection id
    • \n
  • netns (0x30)—\nname of the namespace
    • \n
  • ssl (0x20)—\nbinary SSL TLV structure
    • \n
\n\n

The following SSL TLV type names are supported:

\n\n
    \n
  • ssl_version (0x21)—\nSSL version used in client connection
    • \n
  • ssl_cn (0x22)—\nSSL certificate Common Name
    • \n
  • ssl_cipher (0x23)—\nname of the used cipher
    • \n
  • ssl_sig_alg (0x24)—\nalgorithm used to sign the certificate
    • \n
  • ssl_key_alg (0x25)—\npublic-key algorithm
    • \n
\n\n

Also, the following special SSL TLV type name is supported:

\n\n
    \n
  • ssl_verify—\nclient SSL certificate verification result,\n0 if the client presented a certificate\nand it was successfully verified,\nnon-zero otherwise.
    • \n
\n\n

The PROXY protocol must be previously enabled by setting the\nproxy_protocol parameter\nin the listen directive.

\n" + }, + { + "name": "$query_string", + "description_md": "same as `$args`", + "description_html": "

same as $args

\n" + }, + { + "name": "$realpath_root", + "description_md": "an absolute pathname corresponding to the\n[`root`](https://nginx.org/en/docs/http/ngx_http_core_module.html#root) or [`alias`](https://nginx.org/en/docs/http/ngx_http_core_module.html#alias) directive’s value\nfor the current request,\nwith all symbolic links resolved to real paths", + "description_html": "

an absolute pathname corresponding to the\nroot or alias directive’s value\nfor the current request,\nwith all symbolic links resolved to real paths

\n" + }, + { + "name": "$remote_addr", + "description_md": "client address", + "description_html": "

client address

\n" + }, + { + "name": "$remote_port", + "description_md": "client port", + "description_html": "

client port

\n" + }, + { + "name": "$remote_user", + "description_md": "user name supplied with the Basic authentication", + "description_html": "

user name supplied with the Basic authentication

\n" + }, + { + "name": "$request", + "description_md": "full original request line", + "description_html": "

full original request line

\n" + }, + { + "name": "$request_body", + "description_md": "request body\n\nThe variable’s value is made available in locations\nprocessed by the\n[`proxy_pass`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass),\n[`fastcgi_pass`](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_pass),\n[`uwsgi_pass`](https://nginx.org/en/docs/http/ngx_http_uwsgi_module.html#uwsgi_pass),\nand\n[`scgi_pass`](https://nginx.org/en/docs/http/ngx_http_scgi_module.html#scgi_pass)\ndirectives when the request body was read to\na [memory buffer](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size).", + "description_html": "

request body

\n\n

The variable’s value is made available in locations\nprocessed by the\nproxy_pass,\nfastcgi_pass,\nuwsgi_pass,\nand\nscgi_pass\ndirectives when the request body was read to\na memory buffer.

\n" + }, + { + "name": "$request_body_file", + "description_md": "name of a temporary file with the request body\n\nAt the end of processing, the file needs to be removed.\nTo always write the request body to a file,\n[`client_body_in_file_only`](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_in_file_only) needs to be enabled.\nWhen the name of a temporary file is passed in a proxied request\nor in a request to a FastCGI/uwsgi/SCGI server,\npassing the request body should be disabled by the\n[ proxy_pass_request_body off](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_request_body),\n[ fastcgi_pass_request_body off](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_pass_request_body),\n[ uwsgi_pass_request_body off](https://nginx.org/en/docs/http/ngx_http_uwsgi_module.html#uwsgi_pass_request_body), or\n[ scgi_pass_request_body off](https://nginx.org/en/docs/http/ngx_http_scgi_module.html#scgi_pass_request_body)\ndirectives, respectively.", + "description_html": "

name of a temporary file with the request body

\n\n

At the end of processing, the file needs to be removed.\nTo always write the request body to a file,\nclient_body_in_file_only needs to be enabled.\nWhen the name of a temporary file is passed in a proxied request\nor in a request to a FastCGI/uwsgi/SCGI server,\npassing the request body should be disabled by the\n proxy_pass_request_body off,\n fastcgi_pass_request_body off,\n uwsgi_pass_request_body off, or\n scgi_pass_request_body off\ndirectives, respectively.

\n" + }, + { + "name": "$request_completion", + "description_md": "“`OK`” if a request has completed,\nor an empty string otherwise", + "description_html": "

“OK” if a request has completed,\nor an empty string otherwise

\n" + }, + { + "name": "$request_filename", + "description_md": "file path for the current request, based on the\n[`root`](https://nginx.org/en/docs/http/ngx_http_core_module.html#root) or [`alias`](https://nginx.org/en/docs/http/ngx_http_core_module.html#alias)\ndirectives, and the request URI", + "description_html": "

file path for the current request, based on the\nroot or alias\ndirectives, and the request URI

\n" + }, + { + "name": "$request_id", + "description_md": "unique request identifier\ngenerated from 16 random bytes, in hexadecimal (1.11.0)", + "description_html": "

unique request identifier\ngenerated from 16 random bytes, in hexadecimal (1.11.0)

\n" + }, + { + "name": "$request_length", + "description_md": "request length (including request line, header, and request body)\n(1.3.12, 1.2.7)", + "description_html": "

request length (including request line, header, and request body)\n(1.3.12, 1.2.7)

\n" + }, + { + "name": "$request_method", + "description_md": "request method, usually\n“`GET`” or “`POST`”", + "description_html": "

request method, usually\n“GET” or “POST”

\n" + }, + { + "name": "$request_time", + "description_md": "request processing time in seconds with a milliseconds resolution\n(1.3.9, 1.2.6);\ntime elapsed since the first bytes were read from the client", + "description_html": "

request processing time in seconds with a milliseconds resolution\n(1.3.9, 1.2.6);\ntime elapsed since the first bytes were read from the client

\n" + }, + { + "name": "$request_uri", + "description_md": "full original request URI (with arguments)", + "description_html": "

full original request URI (with arguments)

\n" + }, + { + "name": "$scheme", + "description_md": "request scheme, “`http`” or “`https`”", + "description_html": "

request scheme, “http” or “https”

\n" + }, + { + "name": "$sent_http_NAME", + "description_md": "arbitrary response header field;\nthe last part of a variable name is the field name converted\nto lower case with dashes replaced by underscores", + "description_html": "

arbitrary response header field;\nthe last part of a variable name is the field name converted\nto lower case with dashes replaced by underscores

\n" + }, + { + "name": "$sent_trailer_NAME", + "description_md": "arbitrary field sent at the end of the response (1.13.2);\nthe last part of a variable name is the field name converted\nto lower case with dashes replaced by underscores", + "description_html": "

arbitrary field sent at the end of the response (1.13.2);\nthe last part of a variable name is the field name converted\nto lower case with dashes replaced by underscores

\n" + }, + { + "name": "$server_addr", + "description_md": "an address of the server which accepted a request\n\nComputing a value of this variable usually requires one system call.\nTo avoid a system call, the [`listen`](https://nginx.org/en/docs/http/ngx_http_core_module.html#listen) directives\nmust specify addresses and use the `bind` parameter.", + "description_html": "

an address of the server which accepted a request

\n\n

Computing a value of this variable usually requires one system call.\nTo avoid a system call, the listen directives\nmust specify addresses and use the bind parameter.

\n" + }, + { + "name": "$server_name", + "description_md": "name of the server which accepted a request", + "description_html": "

name of the server which accepted a request

\n" + }, + { + "name": "$server_port", + "description_md": "port of the server which accepted a request", + "description_html": "

port of the server which accepted a request

\n" + }, + { + "name": "$server_protocol", + "description_md": "request protocol, usually\n“`HTTP/1.0`”,\n“`HTTP/1.1`”,\n“[HTTP/2.0](https://nginx.org/en/docs/http/ngx_http_v2_module.html)”,\nor\n“[HTTP/3.0](https://nginx.org/en/docs/http/ngx_http_v3_module.html)”", + "description_html": "

request protocol, usually\n“HTTP/1.0”,\n“HTTP/1.1”,\n“HTTP/2.0”,\nor\n“HTTP/3.0”

\n" + }, + { + "name": "$status", + "description_md": "response status (1.3.2, 1.2.2)", + "description_html": "

response status (1.3.2, 1.2.2)

\n" + }, + { + "name": "$tcpinfo_rcv_space", + "description_md": "information about the client TCP connection; available on systems\nthat support the `TCP_INFO` socket option", + "description_html": "

information about the client TCP connection; available on systems\nthat support the TCP_INFO socket option

\n" + }, + { + "name": "$time_iso8601", + "description_md": "local time in the ISO 8601 standard format (1.3.12, 1.2.7)", + "description_html": "

local time in the ISO 8601 standard format (1.3.12, 1.2.7)

\n" + }, + { + "name": "$time_local", + "description_md": "local time in the Common Log Format (1.3.12, 1.2.7)", + "description_html": "

local time in the Common Log Format (1.3.12, 1.2.7)

\n" + }, + { + "name": "$uri", + "description_md": "current URI in request, [normalized](https://nginx.org/en/docs/http/ngx_http_core_module.html#location)\n\nThe value of `$uri` may change during request processing,\ne.g. when doing internal redirects, or when using index files.", + "description_html": "

current URI in request, normalized

\n\n

The value of $uri may change during request processing,\ne.g. when doing internal redirects, or when using index files.

\n" + } ] }, { @@ -3106,6 +3400,18 @@ "description_md": "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;\n```\na temporary file might look like this:\n```\n/spool/nginx/fastcgi_temp/7/45/00000123457\n```\n\nSee also the `use_temp_path` parameter of the\n[`fastcgi_cache_path`](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_cache_path) directive.", "description_html": "

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\n
fastcgi_temp_path /spool/nginx/fastcgi_temp 1 2;\n
\n\n

a temporary file might look like this:

\n\n
/spool/nginx/fastcgi_temp/7/45/00000123457\n
\n\n

See also the use_temp_path parameter of the\nfastcgi_cache_path directive.

\n" } + ], + "variables": [ + { + "name": "$fastcgi_script_name", + "description_md": "request URI or, if a URI ends with a slash, request URI with an index file\nname configured by the [`fastcgi_index`](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_index) directive appended to it.\nThis variable can be used to set the\n`SCRIPT_FILENAME` and `PATH_TRANSLATED`\nparameters that determine the script name in PHP.\nFor example, for the “`/info/`” request with the\nfollowing directives\n```\nfastcgi_index index.php;\nfastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;\n```\nthe `SCRIPT_FILENAME` parameter will be equal to\n“`/home/www/scripts/php/info/index.php`”.\n\n\nWhen using the [`fastcgi_split_path_info`](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_split_path_info) directive,\nthe `$fastcgi_script_name` variable equals the value of\nthe first capture set by the directive.", + "description_html": "

request URI or, if a URI ends with a slash, request URI with an index file\nname configured by the fastcgi_index directive appended to it.\nThis variable can be used to set the\nSCRIPT_FILENAME and PATH_TRANSLATED\nparameters that determine the script name in PHP.\nFor example, for the “/info/” request with the\nfollowing directives

\n\n
fastcgi_index index.php;\nfastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;\n
\n\n

the SCRIPT_FILENAME parameter will be equal to\n“/home/www/scripts/php/info/index.php”.

\n\n

When using the fastcgi_split_path_info directive,\nthe $fastcgi_script_name variable equals the value of\nthe first capture set by the directive.

\n" + }, + { + "name": "$fastcgi_path_info", + "description_md": "the value of the second capture set by the\n[`fastcgi_split_path_info`](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_split_path_info) directive.\nThis variable can be used to set the\n`PATH_INFO` parameter.", + "description_html": "

the value of the second capture set by the\nfastcgi_split_path_info directive.\nThis variable can be used to set the\nPATH_INFO parameter.

\n" + } ] }, { @@ -3956,6 +4262,13 @@ "description_md": "Enables or disables inserting the \"Vary: Accept-Encoding\"\nresponse header field if the directives\n[`gzip`](https://nginx.org/en/docs/http/ngx_http_gzip_module.html#gzip),\n[`gzip_static`](https://nginx.org/en/docs/http/ngx_http_gzip_static_module.html#gzip_static), or\n[`gunzip`](https://nginx.org/en/docs/http/ngx_http_gunzip_module.html#gunzip)\nare active.", "description_html": "

Enables or disables inserting the “Vary: Accept-Encoding”\nresponse header field if the directives\ngzip,\ngzip_static, or\ngunzip\nare active.

\n" } + ], + "variables": [ + { + "name": "$gzip_ratio", + "description_md": "achieved compression ratio, computed as the ratio between the\noriginal and compressed response sizes.", + "description_html": "

achieved compression ratio, computed as the ratio between the\noriginal and compressed response sizes.

\n" + } ] }, { @@ -4834,6 +5147,13 @@ "description_md": "This directive was made obsolete in version 1.1.8\nand was removed in version 1.7.6.\nAn equivalent [`limit_conn_zone`](https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone) directive\nwith a changed syntax should be used instead:\n> `limit_conn_zone`\n> *`$variable`*\n> `zone`=*`name`*:*`size`*;", "description_html": "

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
\n

limit_conn_zone\n$variable\nzone=name:size;

\n
\n" } + ], + "variables": [ + { + "name": "$limit_conn_status", + "description_md": "keeps the result of limiting the number of connections (1.17.6):\n`PASSED`,\n`REJECTED`, or\n`REJECTED_DRY_RUN`", + "description_html": "

keeps the result of limiting the number of connections (1.17.6):\nPASSED,\nREJECTED, or\nREJECTED_DRY_RUN

\n" + } ] }, { @@ -4928,6 +5248,13 @@ "description_md": "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> Prior to version 1.7.6, a *`key`* could contain exactly one variable.\n\nUsage example:\n```\nlimit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;\n```\n\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.\n\nIf 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](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_status).\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\n[synchronization](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync)\nof the shared memory zone.\n> The `sync` parameter is available as part of our\n> [commercial subscription](https://nginx.com/products/).\n\n> Additionally, as part of our\n> [commercial subscription](https://nginx.com/products/),\n> the\n> [status information](https://nginx.org/en/docs/http/ngx_http_api_module.html#http_limit_reqs_)\n> for each such shared memory zone can be\n> [obtained](https://nginx.org/en/docs/http/ngx_http_api_module.html#getHttpLimitReqZone) or\n> [reset](https://nginx.org/en/docs/http/ngx_http_api_module.html#deleteHttpLimitReqZoneStat)\n> with the [API](https://nginx.org/en/docs/http/ngx_http_api_module.html) since 1.17.7.", "description_html": "

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
\n

Prior to version 1.7.6, a key could contain exactly one variable.

\n
\n\n

Usage example:

\n\n
limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;\n
\n\n

Here, 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\n

A 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.

\n\n

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\n

The 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\n

The sync parameter (1.15.3) enables\nsynchronization\nof the shared memory zone.

\n\n
\n

The sync parameter is available as part of our\ncommercial subscription.

\n\n

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
\n" } + ], + "variables": [ + { + "name": "$limit_req_status", + "description_md": "keeps the result of limiting the request processing rate (1.17.6):\n`PASSED`,\n`DELAYED`,\n`REJECTED`,\n`DELAYED_DRY_RUN`, or\n`REJECTED_DRY_RUN`", + "description_html": "

keeps the result of limiting the request processing rate (1.17.6):\nPASSED,\nDELAYED,\nREJECTED,\nDELAYED_DRY_RUN, or\nREJECTED_DRY_RUN

\n" + } ] }, { @@ -5249,6 +5576,13 @@ "description_md": "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\n`SO_KEEPALIVE` socket option is turned on for the socket.", "description_html": "

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.

\n" } + ], + "variables": [ + { + "name": "$memcached_key", + "description_md": "Defines a key for obtaining response from a memcached server.", + "description_html": "

Defines a key for obtaining response from a memcached server.

\n" + } ] }, { @@ -6728,6 +7062,23 @@ "description_md": "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;\n```\na temporary file might look like this:\n```\n/spool/nginx/proxy_temp/7/45/00000123457\n```\n\nSee also the `use_temp_path` parameter of the\n[`proxy_cache_path`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path) directive.", "description_html": "

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\n
proxy_temp_path /spool/nginx/proxy_temp 1 2;\n
\n\n

a temporary file might look like this:

\n\n
/spool/nginx/proxy_temp/7/45/00000123457\n
\n\n

See also the use_temp_path parameter of the\nproxy_cache_path directive.

\n" } + ], + "variables": [ + { + "name": "$proxy_host", + "description_md": "name and port of a proxied server as specified in the\n[`proxy_pass`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) directive;", + "description_html": "

name and port of a proxied server as specified in the\nproxy_pass directive;

\n" + }, + { + "name": "$proxy_port", + "description_md": "port of a proxied server as specified in the\n[`proxy_pass`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) directive, or the protocol’s default port;", + "description_html": "

port of a proxied server as specified in the\nproxy_pass directive, or the protocol’s default port;

\n" + }, + { + "name": "$proxy_add_x_forwarded_for", + "description_md": "the \"X-Forwarded-For\" client request header field\nwith the `$remote_addr` variable appended to it, separated by a comma.\nIf the \"X-Forwarded-For\" field is not present in the client\nrequest header, the `$proxy_add_x_forwarded_for` variable is equal\nto the `$remote_addr` variable.", + "description_html": "

the “X-Forwarded-For” client request header field\nwith the $remote_addr variable appended to it, separated by a comma.\nIf the “X-Forwarded-For” field is not present in the client\nrequest header, the $proxy_add_x_forwarded_for variable is equal\nto the $remote_addr variable.

\n" + } ] }, { @@ -6810,6 +7161,18 @@ "description_md": "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\n[`real_ip_header`](https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_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.", "description_html": "

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.

\n" } + ], + "variables": [ + { + "name": "$realip_remote_addr", + "description_md": "keeps the original client address (1.9.7)", + "description_html": "

keeps the original client address (1.9.7)

\n" + }, + { + "name": "$realip_remote_port", + "description_md": "keeps the original client port (1.11.0)", + "description_html": "

keeps the original client port (1.11.0)

\n" + } ] }, { @@ -6867,6 +7230,13 @@ "description_md": "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.\n\nParameters can be as follows:\n- `none`\n\n the \"Referer\" field is missing in the request header;\n- `blocked`\n\n the \"Referer\" field is present in the request header,\n but its value has been deleted by a firewall or proxy server;\n such values are strings that do not start with\n “`http://`” or “`https://`”;\n- `server_names`\n\n the \"Referer\" request header field contains\n one of the server names;\n- arbitrary string\n\n defines a server name and an optional URI prefix.\n A server name can have an “`*`” at the beginning or end.\n During the checking, the server’s port in the \"Referer\" field\n is ignored;\n- regular expression\n\n the first symbol should be a “`~`”.\n It should be noted that an expression will be matched against\n the text starting after the “`http://`”\n or “`https://`”.\n\nExample:\n```\nvalid_referers none blocked server_names\n *.example.com example.* www.example.org/galleries/\n ~\\.google\\.;\n```", "description_html": "

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.

\n\n

Parameters can be as follows:

\n\n
    \n

  • none

    \n\n

    the “Referer” field is missing in the request header;

    • \n\n

  • blocked

    \n\n

    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://”;

    • \n\n

  • server_names

    \n\n

    the “Referer” request header field contains\none of the server names;

    • \n\n

  • arbitrary string

    \n\n

    defines 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;

    • \n\n

  • regular expression

    \n\n

    the first symbol should be a “~”.\nIt should be noted that an expression will be matched against\nthe text starting after the “http://”\nor “https://”.

    • \n
\n\n

Example:

\n\n
valid_referers none blocked server_names\n               *.example.com example.* www.example.org/galleries/\n               ~\\.google\\.;\n
\n" } + ], + "variables": [ + { + "name": "$invalid_referer", + "description_md": "Empty string, if the \"Referer\" request header field\nvalue is considered\n[valid](https://nginx.org/en/docs/http/ngx_http_referer_module.html#valid_referers), otherwise “`1`”.", + "description_html": "

Empty string, if the “Referer” request header field\nvalue is considered\nvalid, otherwise “1”.

\n" + } ] }, { @@ -7875,6 +8245,18 @@ "description_md": "Defines a secret *`word`* used to check authenticity\nof requested links.\n\nThe full URI of a requested link looks as follows:\n```\n/*`prefix`*/*`hash`*/*`link`*\n```\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.\n\nIf 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.\n\nExample:\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}\n```\nA request of “`/p/5e814704a28d9bc1914ff19fa0c4a00a/link`”\nwill be internally redirected to\n“`/secure/link`”.\n\nOn UNIX, the hash value for this example can be obtained as:\n```\necho -n 'linksecret' | openssl md5 -hex\n```", "description_html": "

Defines a secret word used to check authenticity\nof requested links.

\n\n

The full URI of a requested link looks as follows:

\n\n
/*`prefix`*/*`hash`*/*`link`*\n
\n\n

where 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.

\n\n

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.

\n\n

Example:

\n\n
location /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}\n
\n\n

A request of “/p/5e814704a28d9bc1914ff19fa0c4a00a/link”\nwill be internally redirected to\n“/secure/link”.

\n\n

On UNIX, the hash value for this example can be obtained as:

\n\n
echo -n 'linksecret' | openssl md5 -hex\n
\n" } + ], + "variables": [ + { + "name": "$secure_link", + "description_md": "The status of a link check.\nThe specific value depends on the selected operation mode.", + "description_html": "

The status of a link check.\nThe specific value depends on the selected operation mode.

\n" + }, + { + "name": "$secure_link_expires", + "description_md": "The lifetime of a link passed in a request;\nintended to be used only in the\n[`secure_link_md5`](https://nginx.org/en/docs/http/ngx_http_secure_link_module.html#secure_link_md5) directive.", + "description_html": "

The lifetime of a link passed in a request;\nintended to be used only in the\nsecure_link_md5 directive.

\n" + } ] }, { @@ -7931,6 +8313,18 @@ "description_md": "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\n`timeout` (by default, 30 seconds).\nOnce a session is no longer active, it is written to the log.\n\nThe `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.\n\nThe `format` parameter sets the custom session log\nformat configured by the [`session_log_format`](https://nginx.org/en/docs/http/ngx_http_session_log_module.html#session_log_format) directive.\nIf `format` is not specified, the predefined\n“`combined`” format is used.", "description_html": "

Sets the path to a log file and configures the shared memory zone that is used\nto store currently active sessions.

\n\n

A 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.

\n\n

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.

\n\n

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.

\n" } + ], + "variables": [ + { + "name": "$session_log_id", + "description_md": "current session ID;", + "description_html": "

current session ID;

\n" + }, + { + "name": "$session_log_binary_id", + "description_md": "current session ID in binary form (16 bytes).", + "description_html": "

current session ID in binary form (16 bytes).

\n" + } ] }, { @@ -7955,6 +8349,13 @@ "description_md": "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.\n\nIn order for a subrequest to return the required range,\nthe `$slice_range` variable should be\n[passed](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) to\nthe proxied server as the `Range` request header field.\nIf\n[caching](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache)\nis enabled, `$slice_range` should be added to the\n[cache key](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_key)\nand caching of responses with 206 status code should be\n[enabled](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid).", "description_html": "

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.

\n\n

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.

\n" } + ], + "variables": [ + { + "name": "$slice_range", + "description_md": "the current slice range in\n[HTTP byte range](https://datatracker.ietf.org/doc/html/rfc7233#section-2.1) format,\nfor example, `bytes=0-1048575`.", + "description_html": "

the current slice range in\nHTTP byte range format,\nfor example, bytes=0-1048575.

\n" + } ] }, { @@ -8092,6 +8493,18 @@ "description_md": "Sets the maximum length of parameter values in SSI commands.", "description_html": "

Sets the maximum length of parameter values in SSI commands.

\n" } + ], + "variables": [ + { + "name": "$date_local", + "description_md": "current time in the local time zone.\nThe format is set by the `config` command\nwith the `timefmt` parameter.", + "description_html": "

current time in the local time zone.\nThe format is set by the config command\nwith the timefmt parameter.

\n" + }, + { + "name": "$date_gmt", + "description_md": "current time in GMT.\nThe format is set by the `config` command\nwith the `timefmt` parameter.", + "description_html": "

current time in GMT.\nThe format is set by the config command\nwith the timefmt parameter.

\n" + } ] }, { @@ -8591,6 +9004,123 @@ "description_md": "Sets the verification depth in the client certificates chain.", "description_html": "

Sets the verification depth in the client certificates chain.

\n" } + ], + "variables": [ + { + "name": "$ssl_alpn_protocol", + "description_md": "returns the protocol selected by ALPN during the SSL handshake,\nor an empty string otherwise (1.21.4);", + "description_html": "

returns the protocol selected by ALPN during the SSL handshake,\nor an empty string otherwise (1.21.4);

\n" + }, + { + "name": "$ssl_cipher", + "description_md": "returns the name of the cipher used\nfor an established SSL connection;", + "description_html": "

returns the name of the cipher used\nfor an established SSL connection;

\n" + }, + { + "name": "$ssl_ciphers", + "description_md": "returns the list of ciphers supported by the client (1.11.7).\nKnown ciphers are listed by names, unknown are shown in hexadecimal,\nfor example:\n```\nAES128-SHA:AES256-SHA:0x00ff\n```\n> The variable is fully supported only when using OpenSSL version 1.0.2 or higher.\n> With older versions, the variable is available\n> only for new sessions and lists only known ciphers.", + "description_html": "

returns the list of ciphers supported by the client (1.11.7).\nKnown ciphers are listed by names, unknown are shown in hexadecimal,\nfor example:

\n\n
AES128-SHA:AES256-SHA:0x00ff\n
\n\n
\n

The variable is fully supported only when using OpenSSL version 1.0.2 or higher.\nWith older versions, the variable is available\nonly for new sessions and lists only known ciphers.

\n
\n" + }, + { + "name": "$ssl_client_escaped_cert", + "description_md": "returns the client certificate in the PEM format (urlencoded)\nfor an established SSL connection (1.13.5);", + "description_html": "

returns the client certificate in the PEM format (urlencoded)\nfor an established SSL connection (1.13.5);

\n" + }, + { + "name": "$ssl_client_cert", + "description_md": "returns the client certificate in the PEM format\nfor an established SSL connection, with each line except the first\nprepended with the tab character;\nthis is intended for the use in the\n[`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive;\n> The variable is deprecated,\n> the `$ssl_client_escaped_cert` variable should be used instead.", + "description_html": "

returns the client certificate in the PEM format\nfor an established SSL connection, with each line except the first\nprepended with the tab character;\nthis is intended for the use in the\nproxy_set_header directive;

\n\n
\n

The variable is deprecated,\nthe $ssl_client_escaped_cert variable should be used instead.

\n
\n" + }, + { + "name": "$ssl_client_fingerprint", + "description_md": "returns the SHA1 fingerprint of the client certificate\nfor an established SSL connection (1.7.1);", + "description_html": "

returns the SHA1 fingerprint of the client certificate\nfor an established SSL connection (1.7.1);

\n" + }, + { + "name": "$ssl_client_i_dn", + "description_md": "returns the “issuer DN” string of the client certificate\nfor an established SSL connection according to\n[RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253) (1.11.6);", + "description_html": "

returns the “issuer DN” string of the client certificate\nfor an established SSL connection according to\nRFC 2253 (1.11.6);

\n" + }, + { + "name": "$ssl_client_i_dn_legacy", + "description_md": "returns the “issuer DN” string of the client certificate\nfor an established SSL connection;\n> Prior to version 1.11.6, the variable name was `$ssl_client_i_dn`.", + "description_html": "

returns the “issuer DN” string of the client certificate\nfor an established SSL connection;

\n\n
\n

Prior to version 1.11.6, the variable name was $ssl_client_i_dn.

\n
\n" + }, + { + "name": "$ssl_client_raw_cert", + "description_md": "returns the client certificate in the PEM format\nfor an established SSL connection;", + "description_html": "

returns the client certificate in the PEM format\nfor an established SSL connection;

\n" + }, + { + "name": "$ssl_client_s_dn", + "description_md": "returns the “subject DN” string of the client certificate\nfor an established SSL connection according to\n[RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253) (1.11.6);", + "description_html": "

returns the “subject DN” string of the client certificate\nfor an established SSL connection according to\nRFC 2253 (1.11.6);

\n" + }, + { + "name": "$ssl_client_s_dn_legacy", + "description_md": "returns the “subject DN” string of the client certificate\nfor an established SSL connection;\n> Prior to version 1.11.6, the variable name was `$ssl_client_s_dn`.", + "description_html": "

returns the “subject DN” string of the client certificate\nfor an established SSL connection;

\n\n
\n

Prior to version 1.11.6, the variable name was $ssl_client_s_dn.

\n
\n" + }, + { + "name": "$ssl_client_serial", + "description_md": "returns the serial number of the client certificate\nfor an established SSL connection;", + "description_html": "

returns the serial number of the client certificate\nfor an established SSL connection;

\n" + }, + { + "name": "$ssl_client_v_end", + "description_md": "returns the end date of the client certificate (1.11.7);", + "description_html": "

returns the end date of the client certificate (1.11.7);

\n" + }, + { + "name": "$ssl_client_v_remain", + "description_md": "returns the number of days\nuntil the client certificate expires (1.11.7);", + "description_html": "

returns the number of days\nuntil the client certificate expires (1.11.7);

\n" + }, + { + "name": "$ssl_client_v_start", + "description_md": "returns the start date of the client certificate (1.11.7);", + "description_html": "

returns the start date of the client certificate (1.11.7);

\n" + }, + { + "name": "$ssl_client_verify", + "description_md": "returns the result of client certificate verification:\n“`SUCCESS`”, “`FAILED:`*`reason`*”,\nand “`NONE`” if a certificate was not present;\n> Prior to version 1.11.7, the “`FAILED`” result\n> did not contain the *`reason`* string.", + "description_html": "

returns the result of client certificate verification:\n“SUCCESS”, “FAILED:*reason*”,\nand “NONE” if a certificate was not present;

\n\n
\n

Prior to version 1.11.7, the “FAILED” result\ndid not contain the reason string.

\n
\n" + }, + { + "name": "$ssl_curve", + "description_md": "returns the negotiated curve used for\nSSL handshake key exchange process (1.21.5).\nKnown curves are listed by names, unknown are shown in hexadecimal,\nfor example:\n```\nprime256v1\n```\n> The variable is supported only when using OpenSSL version 3.0 or higher.\n> With older versions, the variable value will be an empty string.", + "description_html": "

returns the negotiated curve used for\nSSL handshake key exchange process (1.21.5).\nKnown curves are listed by names, unknown are shown in hexadecimal,\nfor example:

\n\n
prime256v1\n
\n\n
\n

The variable is supported only when using OpenSSL version 3.0 or higher.\nWith older versions, the variable value will be an empty string.

\n
\n" + }, + { + "name": "$ssl_curves", + "description_md": "returns the list of curves supported by the client (1.11.7).\nKnown curves are listed by names, unknown are shown in hexadecimal,\nfor example:\n```\n0x001d:prime256v1:secp521r1:secp384r1\n```\n> The variable is supported only when using OpenSSL version 1.0.2 or higher.\n> With older versions, the variable value will be an empty string.\n\n> The variable is available only for new sessions.", + "description_html": "

returns the list of curves supported by the client (1.11.7).\nKnown curves are listed by names, unknown are shown in hexadecimal,\nfor example:

\n\n
0x001d:prime256v1:secp521r1:secp384r1\n
\n\n
\n

The variable is supported only when using OpenSSL version 1.0.2 or higher.\nWith older versions, the variable value will be an empty string.

\n\n

The variable is available only for new sessions.

\n
\n" + }, + { + "name": "$ssl_early_data", + "description_md": "returns “`1`” if\nTLS 1.3 [early data](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_early_data) is used\nand the handshake is not complete, otherwise “” (1.15.3).", + "description_html": "

returns “1” if\nTLS 1.3 early data is used\nand the handshake is not complete, otherwise “” (1.15.3).

\n" + }, + { + "name": "$ssl_protocol", + "description_md": "returns the protocol of an established SSL connection;", + "description_html": "

returns the protocol of an established SSL connection;

\n" + }, + { + "name": "$ssl_server_name", + "description_md": "returns the server name requested through\n[SNI](http://en.wikipedia.org/wiki/Server_Name_Indication)\n(1.7.0);", + "description_html": "

returns the server name requested through\nSNI\n(1.7.0);

\n" + }, + { + "name": "$ssl_session_id", + "description_md": "returns the session identifier of an established SSL connection;", + "description_html": "

returns the session identifier of an established SSL connection;

\n" + }, + { + "name": "$ssl_session_reused", + "description_md": "returns “`r`” if an SSL session was reused,\nor “`.`” otherwise (1.5.11).", + "description_html": "

returns “r” if an SSL session was reused,\nor “.” otherwise (1.5.11).

\n" + } ] }, { @@ -8672,6 +9202,28 @@ "description_md": "The basic status information will be accessible from the surrounding location.\n\n> In versions prior to 1.7.5,\n> the directive syntax required an arbitrary argument, for example,\n> “`stub_status on`”.", "description_html": "

The basic status information will be accessible from the surrounding location.

\n\n
\n

In versions prior to 1.7.5,\nthe directive syntax required an arbitrary argument, for example,\n“stub_status on”.

\n
\n" } + ], + "variables": [ + { + "name": "$connections_active", + "description_md": "same as the `Active connections` value;", + "description_html": "

same as the Active connections value;

\n" + }, + { + "name": "$connections_reading", + "description_md": "same as the `Reading` value;", + "description_html": "

same as the Reading value;

\n" + }, + { + "name": "$connections_writing", + "description_md": "same as the `Writing` value;", + "description_html": "

same as the Writing value;

\n" + }, + { + "name": "$connections_waiting", + "description_md": "same as the `Waiting` value.", + "description_html": "

same as the Waiting value.

\n" + } ] }, { @@ -9124,6 +9676,78 @@ "description_md": "This directive is obsolete since version 1.5.7.\nAn equivalent\n[`sticky`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#sticky) directive with a new syntax should be used instead:\n> `sticky cookie` *`name`*\n> [`expires=`*`time`*]\n> [`domain=`*`domain`*]\n> [`path=`*`path`*];", "description_html": "

This directive is obsolete since version 1.5.7.\nAn equivalent\nsticky directive with a new syntax should be used instead:

\n\n
\n

sticky cookie name\n[expires=time]\n[domain=domain]\n[path=path];

\n
\n" } + ], + "variables": [ + { + "name": "$upstream_addr", + "description_md": "keeps the IP address and port,\nor the path to the UNIX-domain socket of the upstream server.\nIf several servers were contacted during request processing,\ntheir addresses are separated by commas, e.g.\n“`192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock`”.\nIf an internal redirect from one server group to another happens,\ninitiated by\n\"X-Accel-Redirect\" or\n[`error_page`](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page),\nthen the server addresses from different groups are separated by colons, e.g.\n“`192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80`”.\nIf a server cannot be selected,\nthe variable keeps the name of the server group.", + "description_html": "

keeps the IP address and port,\nor the path to the UNIX-domain socket of the upstream server.\nIf several servers were contacted during request processing,\ntheir addresses are separated by commas, e.g.\n“192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock”.\nIf an internal redirect from one server group to another happens,\ninitiated by\n“X-Accel-Redirect” or\nerror_page,\nthen the server addresses from different groups are separated by colons, e.g.\n“192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80”.\nIf a server cannot be selected,\nthe variable keeps the name of the server group.

\n" + }, + { + "name": "$upstream_bytes_received", + "description_md": "number of bytes received from an upstream server (1.11.4).\nValues from several connections\nare separated by commas and colons like addresses in the\n[$upstream_addr](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_addr) variable.", + "description_html": "

number of bytes received from an upstream server (1.11.4).\nValues from several connections\nare separated by commas and colons like addresses in the\n$upstream_addr variable.

\n" + }, + { + "name": "$upstream_bytes_sent", + "description_md": "number of bytes sent to an upstream server (1.15.8).\nValues from several connections\nare separated by commas and colons like addresses in the\n[$upstream_addr](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_addr) variable.", + "description_html": "

number of bytes sent to an upstream server (1.15.8).\nValues from several connections\nare separated by commas and colons like addresses in the\n$upstream_addr variable.

\n" + }, + { + "name": "$upstream_cache_status", + "description_md": "keeps the status of accessing a response cache (0.8.3).\nThe status can be either “`MISS`”,\n“`BYPASS`”, “`EXPIRED`”,\n“`STALE`”, “`UPDATING`”,\n“`REVALIDATED`”, or “`HIT`”.", + "description_html": "

keeps the status of accessing a response cache (0.8.3).\nThe status can be either “MISS”,\n“BYPASS”, “EXPIRED”,\n“STALE”, “UPDATING”,\n“REVALIDATED”, or “HIT”.

\n" + }, + { + "name": "$upstream_connect_time", + "description_md": "keeps time spent on establishing a connection with the upstream server (1.9.1);\nthe time is kept in seconds with millisecond resolution.\nIn case of SSL, includes time spent on handshake.\nTimes of several connections\nare separated by commas and colons like addresses in the\n[$upstream_addr](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_addr) variable.", + "description_html": "

keeps time spent on establishing a connection with the upstream server (1.9.1);\nthe time is kept in seconds with millisecond resolution.\nIn case of SSL, includes time spent on handshake.\nTimes of several connections\nare separated by commas and colons like addresses in the\n$upstream_addr variable.

\n" + }, + { + "name": "$upstream_cookie_NAME", + "description_md": "cookie with the specified *`name`* sent by the upstream server\nin the \"Set-Cookie\" response header field (1.7.1).\nOnly the cookies from the response of the last server are saved.", + "description_html": "

cookie with the specified name sent by the upstream server\nin the “Set-Cookie” response header field (1.7.1).\nOnly the cookies from the response of the last server are saved.

\n" + }, + { + "name": "$upstream_header_time", + "description_md": "keeps time\nspent on receiving the response header from the upstream server (1.7.10);\nthe time is kept in seconds with millisecond resolution.\nTimes of several responses\nare separated by commas and colons like addresses in the\n[$upstream_addr](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_addr) variable.", + "description_html": "

keeps time\nspent on receiving the response header from the upstream server (1.7.10);\nthe time is kept in seconds with millisecond resolution.\nTimes of several responses\nare separated by commas and colons like addresses in the\n$upstream_addr variable.

\n" + }, + { + "name": "$upstream_http_NAME", + "description_md": "keep server response header fields.\nFor example, the \"Server\" response header field\nis available through the `$upstream_http_server` variable.\nThe rules of converting header field names to variable names are the same\nas for the variables that start with the\n“[$http_](https://nginx.org/en/docs/http/ngx_http_core_module.html#var_http_)” prefix.\nOnly the header fields from the response of the last server are saved.", + "description_html": "

keep server response header fields.\nFor example, the “Server” response header field\nis available through the $upstream_http_server variable.\nThe rules of converting header field names to variable names are the same\nas for the variables that start with the\n“$http_” prefix.\nOnly the header fields from the response of the last server are saved.

\n" + }, + { + "name": "$upstream_last_server_name", + "description_md": "keeps the name of last selected upstream server (1.25.3);\nallows passing it\n[through SNI](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_server_name):\n```\nproxy_ssl_server_name on;\nproxy_ssl_name $upstream_last_server_name;\n```\n\n\n> This variable is available as part of our\n> [commercial subscription](https://nginx.com/products/).", + "description_html": "

keeps the name of last selected upstream server (1.25.3);\nallows passing it\nthrough SNI:

\n\n
proxy_ssl_server_name on;\nproxy_ssl_name        $upstream_last_server_name;\n
\n\n
\n

This variable is available as part of our\ncommercial subscription.

\n
\n" + }, + { + "name": "$upstream_queue_time", + "description_md": "keeps time the request spent in the upstream [queue](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#queue)\n(1.13.9);\nthe time is kept in seconds with millisecond resolution.\nTimes of several responses\nare separated by commas and colons like addresses in the\n[$upstream_addr](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_addr) variable.", + "description_html": "

keeps time the request spent in the upstream queue\n(1.13.9);\nthe time is kept in seconds with millisecond resolution.\nTimes of several responses\nare separated by commas and colons like addresses in the\n$upstream_addr variable.

\n" + }, + { + "name": "$upstream_response_length", + "description_md": "keeps the length of the response obtained from the upstream server (0.7.27);\nthe length is kept in bytes.\nLengths of several responses\nare separated by commas and colons like addresses in the\n[$upstream_addr](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_addr) variable.", + "description_html": "

keeps the length of the response obtained from the upstream server (0.7.27);\nthe length is kept in bytes.\nLengths of several responses\nare separated by commas and colons like addresses in the\n$upstream_addr variable.

\n" + }, + { + "name": "$upstream_response_time", + "description_md": "keeps time spent on receiving the response from the upstream server;\nthe time is kept in seconds with millisecond resolution.\nTimes of several responses\nare separated by commas and colons like addresses in the\n[$upstream_addr](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_addr) variable.", + "description_html": "

keeps time spent on receiving the response from the upstream server;\nthe time is kept in seconds with millisecond resolution.\nTimes of several responses\nare separated by commas and colons like addresses in the\n$upstream_addr variable.

\n" + }, + { + "name": "$upstream_status", + "description_md": "keeps status code of the response obtained from the upstream server.\nStatus codes of several responses\nare separated by commas and colons like addresses in the\n[$upstream_addr](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#var_upstream_addr) variable.\nIf a server cannot be selected,\nthe variable keeps the 502 (Bad Gateway) status code.", + "description_html": "

keeps status code of the response obtained from the upstream server.\nStatus codes of several responses\nare separated by commas and colons like addresses in the\n$upstream_addr variable.\nIf a server cannot be selected,\nthe variable keeps the 502 (Bad Gateway) status code.

\n" + }, + { + "name": "$upstream_trailer_NAME", + "description_md": "keeps fields from the end of the response\nobtained from the upstream server (1.13.10).", + "description_html": "

keeps fields from the end of the response\nobtained from the upstream server (1.13.10).

\n" + } ] }, { @@ -9292,6 +9916,23 @@ "description_md": "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.", "description_html": "

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.

\n" } + ], + "variables": [ + { + "name": "$uid_got", + "description_md": "The cookie name and received client identifier.", + "description_html": "

The cookie name and received client identifier.

\n" + }, + { + "name": "$uid_reset", + "description_md": "If the variable is set to a non-empty string that is not “`0`”,\nthe client identifiers are reset.\nThe special value “`log`” additionally leads to the output of\nmessages about the reset identifiers to the\n[`error_log`](https://nginx.org/en/docs/ngx_core_module.html#error_log).", + "description_html": "

If the variable is set to a non-empty string that is not “0”,\nthe client identifiers are reset.\nThe special value “log” additionally leads to the output of\nmessages about the reset identifiers to the\nerror_log.

\n" + }, + { + "name": "$uid_set", + "description_md": "The cookie name and sent client identifier.", + "description_html": "

The cookie name and sent client identifier.

\n" + } ] }, { @@ -10604,6 +11245,13 @@ "description_md": "> This directive is obsolete since version 1.19.7.\n> The [`client_header_timeout`](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_header_timeout)\n> directive should be used instead.\n\nSets the timeout for expecting more data from the client,\nafter which the connection is closed.", "description_html": "
\n

This directive is obsolete since version 1.19.7.\nThe client_header_timeout\ndirective should be used instead.

\n
\n\n

Sets the timeout for expecting more data from the client,\nafter which the connection is closed.

\n" } + ], + "variables": [ + { + "name": "$http2", + "description_md": "negotiated protocol identifier:\n“`h2`” for HTTP/2 over TLS,\n“`h2c`” for HTTP/2 over cleartext TCP,\nor an empty string otherwise.", + "description_html": "

negotiated protocol identifier:\n“h2” for HTTP/2 over TLS,\n“h2c” for HTTP/2 over cleartext TCP,\nor an empty string otherwise.

\n" + } ] }, { @@ -10762,6 +11410,13 @@ "description_md": "Enables the\n[QUIC Address Validation](https://datatracker.ietf.org/doc/html/rfc9000#name-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.", "description_html": "

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.

\n" } + ], + "variables": [ + { + "name": "$http3", + "description_md": "negotiated protocol identifier:\n“`h3`” for HTTP/3 connections,\n“`hq`” for hq connections,\nor an empty string otherwise.", + "description_html": "

negotiated protocol identifier:\n“h3” for HTTP/3 connections,\n“hq” for hq connections,\nor an empty string otherwise.

\n" + } ] }, { @@ -12688,6 +13343,28 @@ "description_md": "Adds a custom OTel span attribute.\nThe value can contain variables.", "description_html": "

Adds a custom OTel span attribute.\nThe value can contain variables.

\n" } + ], + "variables": [ + { + "name": "$otel_trace_id", + "description_md": "the identifier of the trace the current span belongs to,\nfor example, `56552bc4daa3bf39c08362527e1dd6c4`", + "description_html": "

the identifier of the trace the current span belongs to,\nfor example, 56552bc4daa3bf39c08362527e1dd6c4

\n" + }, + { + "name": "$otel_span_id", + "description_md": "the identifier of the current span,\nfor example, `4c0b8531ec38ca59`", + "description_html": "

the identifier of the current span,\nfor example, 4c0b8531ec38ca59

\n" + }, + { + "name": "$otel_parent_id", + "description_md": "the identifier of the parent span,\nfor example, `dc94d281b0f884ea`", + "description_html": "

the identifier of the parent span,\nfor example, dc94d281b0f884ea

\n" + }, + { + "name": "$otel_parent_sampled", + "description_md": "the “`sampled`” flag of the parent span,\ncan be “`1`” or “`0`”", + "description_html": "

the “sampled” flag of the parent span,\ncan be “1” or “0”

\n" + } ] }, { @@ -12964,6 +13641,118 @@ "description_md": "Sets the maximum *`size`* of the variables hash table.\nThe details of setting up hash tables are provided in a separate\n[document](https://nginx.org/en/docs/hash.html).", "description_html": "

Sets the maximum size of the variables hash table.\nThe details of setting up hash tables are provided in a separate\ndocument.

\n" } + ], + "variables": [ + { + "name": "$binary_remote_addr", + "description_md": "client address in a binary form, value’s length is always 4 bytes\nfor IPv4 addresses or 16 bytes for IPv6 addresses", + "description_html": "

client address in a binary form, value’s length is always 4 bytes\nfor IPv4 addresses or 16 bytes for IPv6 addresses

\n" + }, + { + "name": "$bytes_received", + "description_md": "number of bytes received from a client (1.11.4)", + "description_html": "

number of bytes received from a client (1.11.4)

\n" + }, + { + "name": "$bytes_sent", + "description_md": "number of bytes sent to a client", + "description_html": "

number of bytes sent to a client

\n" + }, + { + "name": "$connection", + "description_md": "connection serial number", + "description_html": "

connection serial number

\n" + }, + { + "name": "$hostname", + "description_md": "host name", + "description_html": "

host name

\n" + }, + { + "name": "$msec", + "description_md": "current time in seconds with the milliseconds resolution", + "description_html": "

current time in seconds with the milliseconds resolution

\n" + }, + { + "name": "$nginx_version", + "description_md": "nginx version", + "description_html": "

nginx version

\n" + }, + { + "name": "$pid", + "description_md": "PID of the worker process", + "description_html": "

PID of the worker process

\n" + }, + { + "name": "$protocol", + "description_md": "protocol used to communicate with the client:\n`TCP` or `UDP` (1.11.4)", + "description_html": "

protocol used to communicate with the client:\nTCP or UDP (1.11.4)

\n" + }, + { + "name": "$proxy_protocol_addr", + "description_md": "client address from the PROXY protocol header (1.11.4)\n\nThe PROXY protocol must be previously enabled by setting the\n`proxy_protocol` parameter\nin the [`listen`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#listen) directive.", + "description_html": "

client address from the PROXY protocol header (1.11.4)

\n\n

The PROXY protocol must be previously enabled by setting the\nproxy_protocol parameter\nin the listen directive.

\n" + }, + { + "name": "$proxy_protocol_port", + "description_md": "client port from the PROXY protocol header (1.11.4)\n\nThe PROXY protocol must be previously enabled by setting the\n`proxy_protocol` parameter\nin the [`listen`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#listen) directive.", + "description_html": "

client port from the PROXY protocol header (1.11.4)

\n\n

The PROXY protocol must be previously enabled by setting the\nproxy_protocol parameter\nin the listen directive.

\n" + }, + { + "name": "$proxy_protocol_server_addr", + "description_md": "server address from the PROXY protocol header (1.17.6)\n\nThe PROXY protocol must be previously enabled by setting the\n`proxy_protocol` parameter\nin the [`listen`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#listen) directive.", + "description_html": "

server address from the PROXY protocol header (1.17.6)

\n\n

The PROXY protocol must be previously enabled by setting the\nproxy_protocol parameter\nin the listen directive.

\n" + }, + { + "name": "$proxy_protocol_server_port", + "description_md": "server port from the PROXY protocol header (1.17.6)\n\nThe PROXY protocol must be previously enabled by setting the\n`proxy_protocol` parameter\nin the [`listen`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#listen) directive.", + "description_html": "

server port from the PROXY protocol header (1.17.6)

\n\n

The PROXY protocol must be previously enabled by setting the\nproxy_protocol parameter\nin the listen directive.

\n" + }, + { + "name": "$proxy_protocol_tlv_NAME", + "description_md": "TLV from the PROXY Protocol header (1.23.2).\nThe `name` can be a TLV type name or its numeric value.\nIn the latter case, the value is hexadecimal\nand should be prefixed with `0x`:\n\n```\n$proxy_protocol_tlv_alpn\n$proxy_protocol_tlv_0x01\n```\nSSL TLVs can also be accessed by TLV type name or its numeric value,\nboth prefixed by `ssl_`:\n```\n$proxy_protocol_tlv_ssl_version\n$proxy_protocol_tlv_ssl_0x21\n```\n\n\nThe following TLV type names are supported:\n- `alpn` (`0x01`)—\n upper layer protocol used over the connection\n- `authority` (`0x02`)—\n host name value passed by the client\n- `unique_id` (`0x05`)—\n unique connection id\n- `netns` (`0x30`)—\n name of the namespace\n- `ssl` (`0x20`)—\n binary SSL TLV structure\n\n\n\n\nThe following SSL TLV type names are supported:\n- `ssl_version` (`0x21`)—\n SSL version used in client connection\n- `ssl_cn` (`0x22`)—\n SSL certificate Common Name\n- `ssl_cipher` (`0x23`)—\n name of the used cipher\n- `ssl_sig_alg` (`0x24`)—\n algorithm used to sign the certificate\n- `ssl_key_alg` (`0x25`)—\n public-key algorithm\n\n\n\n\nAlso, the following special SSL TLV type name is supported:\n- `ssl_verify`—\n client SSL certificate verification result,\n zero if the client presented a certificate\n and it was successfully verified, and non-zero otherwise\n\n\n\n\nThe PROXY protocol must be previously enabled by setting the\n`proxy_protocol` parameter\nin the [`listen`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#listen) directive.", + "description_html": "

TLV from the PROXY Protocol header (1.23.2).\nThe name can be a TLV type name or its numeric value.\nIn the latter case, the value is hexadecimal\nand should be prefixed with 0x:

\n\n
$proxy_protocol_tlv_alpn\n$proxy_protocol_tlv_0x01\n
\n\n

SSL TLVs can also be accessed by TLV type name or its numeric value,\nboth prefixed by ssl_:

\n\n
$proxy_protocol_tlv_ssl_version\n$proxy_protocol_tlv_ssl_0x21\n
\n\n

The following TLV type names are supported:

\n\n
    \n
  • alpn (0x01)—\nupper layer protocol used over the connection
    • \n
  • authority (0x02)—\nhost name value passed by the client
    • \n
  • unique_id (0x05)—\nunique connection id
    • \n
  • netns (0x30)—\nname of the namespace
    • \n
  • ssl (0x20)—\nbinary SSL TLV structure
    • \n
\n\n

The following SSL TLV type names are supported:

\n\n
    \n
  • ssl_version (0x21)—\nSSL version used in client connection
    • \n
  • ssl_cn (0x22)—\nSSL certificate Common Name
    • \n
  • ssl_cipher (0x23)—\nname of the used cipher
    • \n
  • ssl_sig_alg (0x24)—\nalgorithm used to sign the certificate
    • \n
  • ssl_key_alg (0x25)—\npublic-key algorithm
    • \n
\n\n

Also, the following special SSL TLV type name is supported:

\n\n
    \n
  • ssl_verify—\nclient SSL certificate verification result,\nzero if the client presented a certificate\nand it was successfully verified, and non-zero otherwise
    • \n
\n\n

The PROXY protocol must be previously enabled by setting the\nproxy_protocol parameter\nin the listen directive.

\n" + }, + { + "name": "$remote_addr", + "description_md": "client address", + "description_html": "

client address

\n" + }, + { + "name": "$remote_port", + "description_md": "client port", + "description_html": "

client port

\n" + }, + { + "name": "$server_addr", + "description_md": "an address of the server which accepted a connection\n\nComputing a value of this variable usually requires one system call.\nTo avoid a system call, the [`listen`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#listen) directives\nmust specify addresses and use the `bind` parameter.", + "description_html": "

an address of the server which accepted a connection

\n\n

Computing a value of this variable usually requires one system call.\nTo avoid a system call, the listen directives\nmust specify addresses and use the bind parameter.

\n" + }, + { + "name": "$server_port", + "description_md": "port of the server which accepted a connection", + "description_html": "

port of the server which accepted a connection

\n" + }, + { + "name": "$session_time", + "description_md": "session duration in seconds with a milliseconds resolution\n(1.11.4);", + "description_html": "

session duration in seconds with a milliseconds resolution\n(1.11.4);

\n" + }, + { + "name": "$status", + "description_md": "session status (1.11.4), can be one of the following:\n- `200`\n\n session completed successfully\n- `400`\n\n client data could not be parsed, for example,\n the [PROXY protocol](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#proxy_protocol) header\n- `403`\n\n access forbidden, for example, when access is limited for\n [certain client addresses](https://nginx.org/en/docs/stream/ngx_stream_access_module.html)\n- `500`\n\n internal server error\n- `502`\n\n bad gateway, for example,\n if an upstream server could not be selected or reached.\n- `503`\n\n service unavailable, for example, when access is limited by the\n [number of connections](https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html)", + "description_html": "

session status (1.11.4), can be one of the following:

\n\n
    \n

  • 200

    \n\n

    session completed successfully

    • \n\n

  • 400

    \n\n

    client data could not be parsed, for example,\nthe PROXY protocol header

    • \n\n

  • 403

    \n\n

    access forbidden, for example, when access is limited for\ncertain client addresses

    • \n\n

  • 500

    \n\n

    internal server error

    • \n\n

  • 502

    \n\n

    bad gateway, for example,\nif an upstream server could not be selected or reached.

    • \n\n

  • 503

    \n\n

    service unavailable, for example, when access is limited by the\nnumber of connections

    • \n
\n" + }, + { + "name": "$time_iso8601", + "description_md": "local time in the ISO 8601 standard format", + "description_html": "

local time in the ISO 8601 standard format

\n" + }, + { + "name": "$time_local", + "description_md": "local time in the Common Log Format", + "description_html": "

local time in the Common Log Format

\n" + } ] }, { @@ -13477,6 +14266,13 @@ "description_md": "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:\n```\nlimit_conn_zone $binary_remote_addr zone=addr:10m;\n```\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> Additionally, as part of our\n> [commercial subscription](https://nginx.com/products/),\n> the\n> [status information](https://nginx.org/en/docs/http/ngx_http_api_module.html#stream_limit_conns_)\n> for each such shared memory zone can be\n> [obtained](https://nginx.org/en/docs/http/ngx_http_api_module.html#getStreamLimitConnZone) or\n> [reset](https://nginx.org/en/docs/http/ngx_http_api_module.html#deleteStreamLimitConnZoneStat)\n> with the [API](https://nginx.org/en/docs/http/ngx_http_api_module.html) since 1.17.7.", "description_html": "

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:

\n\n
limit_conn_zone $binary_remote_addr zone=addr:10m;\n
\n\n

Here, 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
\n

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
\n" } + ], + "variables": [ + { + "name": "$limit_conn_status", + "description_md": "keeps the result of limiting the number of connections (1.17.6):\n`PASSED`,\n`REJECTED`, or\n`REJECTED_DRY_RUN`", + "description_html": "

keeps the result of limiting the number of connections (1.17.6):\nPASSED,\nREJECTED, or\nREJECTED_DRY_RUN

\n" + } ] }, { @@ -13686,6 +14482,18 @@ "description_md": "Enables extracting information from the MQTT CONNECT message at\nthe [preread](https://nginx.org/en/docs/stream/stream_processing.html#preread_phase) phase.", "description_html": "

Enables extracting information from the MQTT CONNECT message at\nthe preread phase.

\n" } + ], + "variables": [ + { + "name": "$mqtt_preread_clientid", + "description_md": "the `clientid` value from the CONNECT message", + "description_html": "

the clientid value from the CONNECT message

\n" + }, + { + "name": "$mqtt_preread_username", + "description_md": "the `username` value from the CONNECT message", + "description_html": "

the username value from the CONNECT message

\n" + } ] }, { @@ -14246,6 +15054,18 @@ "description_md": "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.", "description_html": "

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.

\n" } + ], + "variables": [ + { + "name": "$realip_remote_addr", + "description_md": "keeps the original client address", + "description_html": "

keeps the original client address

\n" + }, + { + "name": "$realip_remote_port", + "description_md": "keeps the original client port", + "description_html": "

keeps the original client port

\n" + } ] }, { @@ -14675,6 +15495,103 @@ "description_md": "Sets the verification depth in the client certificates chain.", "description_html": "

Sets the verification depth in the client certificates chain.

\n" } + ], + "variables": [ + { + "name": "$ssl_alpn_protocol", + "description_md": "returns the protocol selected by ALPN during the SSL handshake,\nor an empty string otherwise (1.21.4);", + "description_html": "

returns the protocol selected by ALPN during the SSL handshake,\nor an empty string otherwise (1.21.4);

\n" + }, + { + "name": "$ssl_cipher", + "description_md": "returns the name of the cipher used\nfor an established SSL connection;", + "description_html": "

returns the name of the cipher used\nfor an established SSL connection;

\n" + }, + { + "name": "$ssl_ciphers", + "description_md": "returns the list of ciphers supported by the client (1.11.7).\nKnown ciphers are listed by names, unknown are shown in hexadecimal,\nfor example:\n```\nAES128-SHA:AES256-SHA:0x00ff\n```\n> The variable is fully supported only when using OpenSSL version 1.0.2 or higher.\n> With older versions, the variable is available\n> only for new sessions and lists only known ciphers.", + "description_html": "

returns the list of ciphers supported by the client (1.11.7).\nKnown ciphers are listed by names, unknown are shown in hexadecimal,\nfor example:

\n\n
AES128-SHA:AES256-SHA:0x00ff\n
\n\n
\n

The variable is fully supported only when using OpenSSL version 1.0.2 or higher.\nWith older versions, the variable is available\nonly for new sessions and lists only known ciphers.

\n
\n" + }, + { + "name": "$ssl_client_cert", + "description_md": "returns the client certificate in the PEM format\nfor an established SSL connection, with each line except the first\nprepended with the tab character (1.11.8);", + "description_html": "

returns the client certificate in the PEM format\nfor an established SSL connection, with each line except the first\nprepended with the tab character (1.11.8);

\n" + }, + { + "name": "$ssl_client_fingerprint", + "description_md": "returns the SHA1 fingerprint of the client certificate\nfor an established SSL connection (1.11.8);", + "description_html": "

returns the SHA1 fingerprint of the client certificate\nfor an established SSL connection (1.11.8);

\n" + }, + { + "name": "$ssl_client_i_dn", + "description_md": "returns the “issuer DN” string of the client certificate\nfor an established SSL connection according to\n[RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253) (1.11.8);", + "description_html": "

returns the “issuer DN” string of the client certificate\nfor an established SSL connection according to\nRFC 2253 (1.11.8);

\n" + }, + { + "name": "$ssl_client_raw_cert", + "description_md": "returns the client certificate in the PEM format\nfor an established SSL connection (1.11.8);", + "description_html": "

returns the client certificate in the PEM format\nfor an established SSL connection (1.11.8);

\n" + }, + { + "name": "$ssl_client_s_dn", + "description_md": "returns the “subject DN” string of the client certificate\nfor an established SSL connection according to\n[RFC 2253](https://datatracker.ietf.org/doc/html/rfc2253) (1.11.8);", + "description_html": "

returns the “subject DN” string of the client certificate\nfor an established SSL connection according to\nRFC 2253 (1.11.8);

\n" + }, + { + "name": "$ssl_client_serial", + "description_md": "returns the serial number of the client certificate\nfor an established SSL connection (1.11.8);", + "description_html": "

returns the serial number of the client certificate\nfor an established SSL connection (1.11.8);

\n" + }, + { + "name": "$ssl_client_v_end", + "description_md": "returns the end date of the client certificate (1.11.8);", + "description_html": "

returns the end date of the client certificate (1.11.8);

\n" + }, + { + "name": "$ssl_client_v_remain", + "description_md": "returns the number of days\nuntil the client certificate expires (1.11.8);", + "description_html": "

returns the number of days\nuntil the client certificate expires (1.11.8);

\n" + }, + { + "name": "$ssl_client_v_start", + "description_md": "returns the start date of the client certificate (1.11.8);", + "description_html": "

returns the start date of the client certificate (1.11.8);

\n" + }, + { + "name": "$ssl_client_verify", + "description_md": "returns the result of client certificate verification (1.11.8):\n“`SUCCESS`”, “`FAILED:`*`reason`*”,\nand “`NONE`” if a certificate was not present;", + "description_html": "

returns the result of client certificate verification (1.11.8):\n“SUCCESS”, “FAILED:*reason*”,\nand “NONE” if a certificate was not present;

\n" + }, + { + "name": "$ssl_curve", + "description_md": "returns the negotiated curve used for\nSSL handshake key exchange process (1.21.5).\nKnown curves are listed by names, unknown are shown in hexadecimal,\nfor example:\n```\nprime256v1\n```\n> The variable is supported only when using OpenSSL version 3.0 or higher.\n> With older versions, the variable value will be an empty string.", + "description_html": "

returns the negotiated curve used for\nSSL handshake key exchange process (1.21.5).\nKnown curves are listed by names, unknown are shown in hexadecimal,\nfor example:

\n\n
prime256v1\n
\n\n
\n

The variable is supported only when using OpenSSL version 3.0 or higher.\nWith older versions, the variable value will be an empty string.

\n
\n" + }, + { + "name": "$ssl_curves", + "description_md": "returns the list of curves supported by the client (1.11.7).\nKnown curves are listed by names, unknown are shown in hexadecimal,\nfor example:\n```\n0x001d:prime256v1:secp521r1:secp384r1\n```\n> The variable is supported only when using OpenSSL version 1.0.2 or higher.\n> With older versions, the variable value will be an empty string.\n\n> The variable is available only for new sessions.", + "description_html": "

returns the list of curves supported by the client (1.11.7).\nKnown curves are listed by names, unknown are shown in hexadecimal,\nfor example:

\n\n
0x001d:prime256v1:secp521r1:secp384r1\n
\n\n
\n

The variable is supported only when using OpenSSL version 1.0.2 or higher.\nWith older versions, the variable value will be an empty string.

\n\n

The variable is available only for new sessions.

\n
\n" + }, + { + "name": "$ssl_protocol", + "description_md": "returns the protocol of an established SSL connection;", + "description_html": "

returns the protocol of an established SSL connection;

\n" + }, + { + "name": "$ssl_server_name", + "description_md": "returns the server name requested through\n[SNI](http://en.wikipedia.org/wiki/Server_Name_Indication);", + "description_html": "

returns the server name requested through\nSNI;

\n" + }, + { + "name": "$ssl_session_id", + "description_md": "returns the session identifier of an established SSL connection;", + "description_html": "

returns the session identifier of an established SSL connection;

\n" + }, + { + "name": "$ssl_session_reused", + "description_md": "returns “`r`” if an SSL session was reused,\nor “`.`” otherwise.", + "description_html": "

returns “r” if an SSL session was reused,\nor “.” otherwise.

\n" + } ] }, { @@ -14698,6 +15615,23 @@ "description_md": "Enables extracting information from the ClientHello message at\nthe [preread](https://nginx.org/en/docs/stream/stream_processing.html#preread_phase) phase.", "description_html": "

Enables extracting information from the ClientHello message at\nthe preread phase.

\n" } + ], + "variables": [ + { + "name": "$ssl_preread_protocol", + "description_md": "the highest SSL protocol version supported by the client (1.15.2)", + "description_html": "

the highest SSL protocol version supported by the client (1.15.2)

\n" + }, + { + "name": "$ssl_preread_server_name", + "description_md": "server name requested through SNI", + "description_html": "

server name requested through SNI

\n" + }, + { + "name": "$ssl_preread_alpn_protocols", + "description_md": "list of protocols advertised by the client through ALPN (1.13.10).\nThe values are separated by commas.", + "description_html": "

list of protocols advertised by the client through ALPN (1.13.10).\nThe values are separated by commas.

\n" + } ] }, { @@ -14919,6 +15853,38 @@ "description_md": "Sets a timeout for name resolution, for example:\n```\nresolver_timeout 5s;\n```\n\n> This directive is available as part of our\n> [commercial subscription](https://nginx.com/products/).", "description_html": "

Sets a timeout for name resolution, for example:

\n\n
resolver_timeout 5s;\n
\n\n
\n

This directive is available as part of our\ncommercial subscription.

\n
\n" } + ], + "variables": [ + { + "name": "$upstream_addr", + "description_md": "keeps the IP address and port,\nor the path to the UNIX-domain socket of the upstream server (1.11.4).\nIf several servers were contacted during proxying,\ntheir addresses are separated by commas, e.g.\n“`192.168.1.1:12345, 192.168.1.2:12345, unix:/tmp/sock`”.\nIf a server cannot be selected,\nthe variable keeps the name of the server group.", + "description_html": "

keeps the IP address and port,\nor the path to the UNIX-domain socket of the upstream server (1.11.4).\nIf several servers were contacted during proxying,\ntheir addresses are separated by commas, e.g.\n“192.168.1.1:12345, 192.168.1.2:12345, unix:/tmp/sock”.\nIf a server cannot be selected,\nthe variable keeps the name of the server group.

\n" + }, + { + "name": "$upstream_bytes_received", + "description_md": "number of bytes received from an upstream server (1.11.4).\nValues from several connections\nare separated by commas like addresses in the\n[$upstream_addr](https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#var_upstream_addr) variable.", + "description_html": "

number of bytes received from an upstream server (1.11.4).\nValues from several connections\nare separated by commas like addresses in the\n$upstream_addr variable.

\n" + }, + { + "name": "$upstream_bytes_sent", + "description_md": "number of bytes sent to an upstream server (1.11.4).\nValues from several connections\nare separated by commas like addresses in the\n[$upstream_addr](https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#var_upstream_addr) variable.", + "description_html": "

number of bytes sent to an upstream server (1.11.4).\nValues from several connections\nare separated by commas like addresses in the\n$upstream_addr variable.

\n" + }, + { + "name": "$upstream_connect_time", + "description_md": "time to connect to the upstream server (1.11.4);\nthe time is kept in seconds with millisecond resolution.\nTimes of several connections\nare separated by commas like addresses in the\n[$upstream_addr](https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#var_upstream_addr) variable.", + "description_html": "

time to connect to the upstream server (1.11.4);\nthe time is kept in seconds with millisecond resolution.\nTimes of several connections\nare separated by commas like addresses in the\n$upstream_addr variable.

\n" + }, + { + "name": "$upstream_first_byte_time", + "description_md": "time to receive the first byte of data (1.11.4);\nthe time is kept in seconds with millisecond resolution.\nTimes of several connections\nare separated by commas like addresses in the\n[$upstream_addr](https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#var_upstream_addr) variable.", + "description_html": "

time to receive the first byte of data (1.11.4);\nthe time is kept in seconds with millisecond resolution.\nTimes of several connections\nare separated by commas like addresses in the\n$upstream_addr variable.

\n" + }, + { + "name": "$upstream_session_time", + "description_md": "session duration in seconds with millisecond resolution (1.11.4).\nTimes of several connections\nare separated by commas like addresses in the\n[$upstream_addr](https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#var_upstream_addr) variable.", + "description_html": "

session duration in seconds with millisecond resolution (1.11.4).\nTimes of several connections\nare separated by commas like addresses in the\n$upstream_addr variable.

\n" + } ] }, { @@ -15283,5 +16249,5 @@ ] } ], - "version": "https://hg.nginx.org:80/nginx.org/rev/d3b2c35a7ea4" + "version": "https://github.com/nginx/nginx.org/commit/f5cea0fff718819832c358a7c6d183343deb1f0b" } diff --git a/reference-lib/tests/index.test.ts b/reference-lib/tests/index.test.ts index 751eb1e..fac1728 100644 --- a/reference-lib/tests/index.test.ts +++ b/reference-lib/tests/index.test.ts @@ -1,4 +1,11 @@ -import { find, Format, getDirectives, Directive} from '../index'; +import { + find, + Format, + getDirectives, + getVariables, + Variable, + Directive, +} from '../index' import mockReference from '../src/__mocks__/reference_mock.json' describe('Directive Helper', () => { @@ -8,26 +15,26 @@ describe('Directive Helper', () => { const actual = find('allow', 'ngx_http_access_module', Format.HTML) const expected = directive?.description_html expect(actual).toBe(expected) - }); + }) test('without module', () => { const actual = find('allow', undefined, Format.HTML) const expected = directive?.description_html expect(actual).toBe(expected) - }); + }) test('returns undefined if not found', () => { const actual = find('listen', '', Format.HTML) expect(actual).toBeUndefined - }); + }) test('returns HTML', () => { const actual = find('allow', '', Format.HTML) const expected = directive?.description_html expect(actual).toBe(expected) - }); + }) test('returns Markdown', () => { const actual = find('allow', '', Format.Markdown) const expected = directive?.description_md expect(actual).toBe(expected) - }); + }) }) describe('getDirectives', () => { @@ -35,27 +42,60 @@ describe('Directive Helper', () => { const directive = module?.directives.at(0) test('returns HTML', () => { const actual = getDirectives(Format.HTML) - const expected = [{ name: directive?.name, - module: module?.name, - description: directive?.description_html, - syntax: directive?.syntax_html, - contexts: directive?.contexts, - isBlock: directive?.isBlock, - default: directive?.default, - } as Directive ] + const expected = [ + { + name: directive?.name, + module: module?.name, + description: directive?.description_html, + syntax: directive?.syntax_html, + contexts: directive?.contexts, + isBlock: directive?.isBlock, + default: directive?.default, + } as Directive, + ] expect(actual).toStrictEqual(expected) - }); + }) test('returns Markdown', () => { const actual = getDirectives(Format.Markdown) - const expected = [{ name: directive?.name, - module: module?.name, - description: directive?.description_md, - syntax: directive?.syntax_md, - contexts: directive?.contexts, - isBlock: directive?.isBlock, - default: directive?.default, - } as Directive ] + const expected = [ + { + name: directive?.name, + module: module?.name, + description: directive?.description_md, + syntax: directive?.syntax_md, + contexts: directive?.contexts, + isBlock: directive?.isBlock, + default: directive?.default, + } as Directive, + ] expect(actual).toStrictEqual(expected) - }); + }) + }) + + describe('getVariables', () => { + const module = mockReference.modules.at(0)! + const variable = module?.variables.at(0)! + + test('returns HTML', () => { + const actual = getVariables() + expect([ + { + name: variable.name, + description: variable.description_html, + module: module.name, + } as Variable, + ]).toStrictEqual(actual) + }) + + test('returns Markdown', () => { + const actual = getVariables(Format.Markdown) + expect([ + { + name: variable.name, + description: variable.description_md, + module: module.name, + } as Variable, + ]).toStrictEqual(actual) + }) }) }) From f7961acdd4770a87ef93e4f05264fbc830a3cb42 Mon Sep 17 00:00:00 2001 From: Ryan Davis Date: Tue, 11 Jun 2024 09:52:36 -0400 Subject: [PATCH 3/3] chore: update changelog --- CHANGELOG.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5d9701d..5a045c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,9 @@ # Changelog -## 1.0.0 (Month Date, Year) +## 1.0.14 (June 6, 2024) -Initial release of the NGINX template repository. +Changed source and version from the Mercurial repository to the GitHub one. -## 1.0.14 (June 6, 2024) +## 1.1 (June, 11 2024) -Changed source and version from the Mercurial repository to the GitHub one. \ No newline at end of file +Added NGINX variables (e.g. `$binary_remote_addr`) to the dataset.