From e0d03e88520e84114a7b7cac0fa0c07a4d858e40 Mon Sep 17 00:00:00 2001 From: ryepup <40441+ryepup@users.noreply.github.com> Date: Thu, 15 Oct 2026 14:20:15 +0000 Subject: [PATCH] update reference.json --- reference-lib/package-lock.json | 4 +- reference-lib/package.json | 2 +- reference-lib/src/reference.json | 601 ++++++++++++++++++++++++++++++- 3 files changed, 601 insertions(+), 6 deletions(-) diff --git a/reference-lib/package-lock.json b/reference-lib/package-lock.json index fc660d3..1cc6c28 100644 --- a/reference-lib/package-lock.json +++ b/reference-lib/package-lock.json @@ -1,12 +1,12 @@ { "name": "@nginx/reference-lib", - "version": "1.1.43", + "version": "1.1.44", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@nginx/reference-lib", - "version": "1.1.43", + "version": "1.1.44", "license": "Apache-2.0", "devDependencies": { "@rollup/plugin-json": "^6.1.0", diff --git a/reference-lib/package.json b/reference-lib/package.json index 7900ed8..4a4d826 100644 --- a/reference-lib/package.json +++ b/reference-lib/package.json @@ -1,6 +1,6 @@ { "name": "@nginx/reference-lib", - "version": "1.1.43", + "version": "1.1.44", "description": "", "main": "dist/index.js", "type": "module", diff --git a/reference-lib/src/reference.json b/reference-lib/src/reference.json index 604e05a..f6dd499 100644 --- a/reference-lib/src/reference.json +++ b/reference-lib/src/reference.json @@ -2827,6 +2827,585 @@ } ] }, + { + "id": "/en/docs/http/ngx_http_db_module.html", + "name": "ngx_http_db_module", + "directives": [ + { + "name": "db_auth", + "default": "", + "contexts": [ + "location", + "if in location" + ], + "syntax_md": [ + "*`string`*" + ], + "syntax_html": [ + "

string

\n" + ], + "isBlock": false, + "description_md": "Specifies the password string\nused to authenticate connections to a database server.\nAn empty value disables authentication.\nAuthentication with a separate username and password arguments\nis not supported.\n```\nlocation /db/ {\n db_pass redis_backend;\n db_auth secret;\n db_get $arg_key;\n}\n```\n\nFor the Redis backend, the password is passed as a single argument\nto the `AUTH` command.\n\nThe directive is inherited from the previous configuration level\nif and only if there are no `db_auth` directives\ndefined on the current level.\n\nTo protect the password, enable SSL/TLS connections to the database server\nusing the [`db_ssl`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_ssl) directive.", + "description_html": "

Specifies the password string\nused to authenticate connections to a database server.\nAn empty value disables authentication.\nAuthentication with a separate username and password arguments\nis not supported.

\n\n
location /db/ {\n    db_pass redis_backend;\n    db_auth secret;\n    db_get  $arg_key;\n}\n
\n\n

For the Redis backend, the password is passed as a single argument\nto the AUTH command.

\n\n

The directive is inherited from the previous configuration level\nif and only if there are no db_auth directives\ndefined on the current level.

\n\n

To protect the password, enable SSL/TLS connections to the database server\nusing the db_ssl directive.

\n" + }, + { + "name": "db_bind", + "default": "", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`address`* [`transparent`] | `off`" + ], + "syntax_html": [ + "

address [transparent] | off

\n" + ], + "isBlock": false, + "description_md": "Makes outgoing connections to a database server originate\nfrom the specified local IP address with an optional port.\nParameter value can contain variables.\nThe special value `off` cancels the effect\nof the `db_bind` directive\ninherited from the previous configuration level, which allows the\nsystem to auto-assign the local IP address and port.\nExample:\n```\ndb_bind $server_addr;\n```\n\nThe `transparent` parameter allows\noutgoing connections to a database server originate\nfrom a non-local IP address,\nfor example, from a real IP address of a client:\n```\ndb_bind $remote_addr transparent;\n```\nIn order for this parameter to work,\nit is usually necessary to run nginx worker processes with the\n[superuser](https://nginx.org/en/docs/ngx_core_module.html#user) privileges.\nOn Linux it is not required as if\nthe `transparent` parameter is specified, worker processes\ninherit the `CAP_NET_RAW` capability from the master process.\nIt is also necessary to configure kernel routing table\nto intercept network traffic from the database server.", + "description_html": "

Makes outgoing connections to a database server originate\nfrom the specified local IP address with an optional port.\nParameter value can contain variables.\nThe special value off cancels the effect\nof the db_bind directive\ninherited from the previous configuration level, which allows the\nsystem to auto-assign the local IP address and port.\nExample:

\n\n
db_bind $server_addr;\n
\n\n

The transparent parameter allows\noutgoing connections to a database server originate\nfrom a non-local IP address,\nfor example, from a real IP address of a client:

\n\n
db_bind $remote_addr transparent;\n
\n\n

In order for this parameter to work,\nit is usually necessary to run nginx worker processes with the\nsuperuser privileges.\nOn Linux it is not required as if\nthe transparent parameter is specified, worker processes\ninherit the CAP_NET_RAW capability from the master process.\nIt is also necessary to configure kernel routing table\nto intercept network traffic from the database server.

\n" + }, + { + "name": "db_buffer_size", + "default": "4k|8k", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`size`*" + ], + "syntax_html": [ + "

size

\n" + ], + "isBlock": false, + "description_md": "Sets the size of the buffer used for reading the database response.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.\nIt can be made smaller, however.\n\nThe buffer is also used when parsing database protocol replies.\nA protocol reply header that does not fit in the buffer\ncannot be processed successfully.\n\nDatabase response bodies are processed without upstream response buffering.", + "description_html": "

Sets the size of the buffer used for reading the database response.\nBy default, the buffer size is equal to one memory page.\nThis is either 4K or 8K, depending on a platform.\nIt can be made smaller, however.

\n\n

The buffer is also used when parsing database protocol replies.\nA protocol reply header that does not fit in the buffer\ncannot be processed successfully.

\n\n

Database response bodies are processed without upstream response buffering.

\n" + }, + { + "name": "db_cache", + "default": "", + "contexts": [ + "location", + "if in location" + ], + "syntax_md": [ + "*`zone`* [`timeout`=*`time`*] [`max_size`=*`size`*] [`not_found`=`on`|`off`|*`time`*]" + ], + "syntax_html": [ + "

zone [timeout=time] [max_size=size] [not_found=on|off|time]

\n" + ], + "isBlock": false, + "description_md": "Enables caching of database lookup results in a shared memory zone\ndefined by the\n[`keyval_zone`](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone) directive.\nThe cache key is the value of the [`db_get`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_get) directive,\nevaluated for the current request.\nIf a cached result is found,\nit is returned without connecting to the database server.\n\nThe [`db_pass`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_pass) directive must be specified\nin the same configuration context.\n\nThe following parameters are supported:\n- `timeout`=*`time`*\n\n sets the lifetime of cached values.\n The parameter defaults to `0`.\n A nonzero effective timeout should be configured using this parameter\n or the zone's `timeout` parameter.\n With an effective timeout of zero, entries may be removed\n by unrelated writes to the zone.\n- `max_size`=*`size`*\n\n sets the maximum value size eligible for caching.\n By default, the size is `64k`.\n Values exceeding this limit are returned to the client but are not cached.\n- `not_found`=`off` | `on` | `time`\n\n Enables or disables caching of `not found` results.\n By default, such results are not cached.\n The value `on` uses the same timeout as for database values.\n A time value specifies a separate lifetime\n for `not found` results.\n\nFor example:\n```\nhttp {\n keyval_zone zone=db_cache:10m timeout=1m;\n\n upstream redis_backend {\n db_type redis;\n server 127.0.0.1:6379;\n }\n\n server {\n location /db/ {\n db_pass redis_backend;\n db_get $arg_key;\n\n db_cache db_cache timeout=30s max_size=128k not_found=5s;\n }\n }\n}\n```\n\nThe evaluated [`db_get`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_get) value is used as the cache key.\nA cached value is returned without contacting the database.\nA cached missing-key result returns\n404 (Not Found)\nif missing-key caching is enabled in the current location.\nOtherwise, the database is queried.\n\nA zero-length value is a successful result and is distinct\nfrom a missing key.\nOnly complete, valid successful responses are cached,\ntogether with missing-key results when enabled.\nFailed, malformed, or incomplete responses are not cached.\n\nLocations sharing a zone must have identical\n[`db_pass`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_pass), [`db_name`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_name),\nand [`db_auth`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_auth) settings.\nA cache zone must not also be used for ordinary keyval data.\nMissing-key caching cannot be combined with the\n`not_found` parameter of\n[`db_next_upstream`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_next_upstream).\n\nA cache lookup error returns\n500 (Internal Server Error).\nFailure to insert a result into the cache does not affect the response.\n\nThe directive is inherited from the previous configuration level\nunless overridden.\n\n> The module does not provide cache invalidation or purge.\n> Database changes may remain invisible until cached entries expire\n> or are evicted.\n> Concurrent cache misses are not combined into a single database request.", + "description_html": "

Enables caching of database lookup results in a shared memory zone\ndefined by the\nkeyval_zone directive.\nThe cache key is the value of the db_get directive,\nevaluated for the current request.\nIf a cached result is found,\nit is returned without connecting to the database server.

\n\n

The db_pass directive must be specified\nin the same configuration context.

\n\n

The following parameters are supported:

\n\n\n\n

For example:

\n\n
http {\n    keyval_zone zone=db_cache:10m timeout=1m;\n\n    upstream redis_backend {\n        db_type redis;\n        server  127.0.0.1:6379;\n    }\n\n    server {\n        location /db/ {\n            db_pass redis_backend;\n            db_get  $arg_key;\n\n            db_cache db_cache timeout=30s max_size=128k not_found=5s;\n        }\n    }\n}\n
\n\n

The evaluated db_get value is used as the cache key.\nA cached value is returned without contacting the database.\nA cached missing-key result returns\n404 (Not Found)\nif missing-key caching is enabled in the current location.\nOtherwise, the database is queried.

\n\n

A zero-length value is a successful result and is distinct\nfrom a missing key.\nOnly complete, valid successful responses are cached,\ntogether with missing-key results when enabled.\nFailed, malformed, or incomplete responses are not cached.

\n\n

Locations sharing a zone must have identical\ndb_pass, db_name,\nand db_auth settings.\nA cache zone must not also be used for ordinary keyval data.\nMissing-key caching cannot be combined with the\nnot_found parameter of\ndb_next_upstream.

\n\n

A cache lookup error returns\n500 (Internal Server Error).\nFailure to insert a result into the cache does not affect the response.

\n\n

The directive is inherited from the previous configuration level\nunless overridden.

\n\n
\n

The module does not provide cache invalidation or purge.\nDatabase changes may remain invisible until cached entries expire\nor are evicted.\nConcurrent cache misses are not combined into a single database request.

\n
\n" + }, + { + "name": "db_connect_timeout", + "default": "60s", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`time`*" + ], + "syntax_html": [ + "

time

\n" + ], + "isBlock": false, + "description_md": "Defines a timeout for establishing a connection with a database server.\nIt should be noted that this timeout cannot usually exceed 75 seconds.", + "description_html": "

Defines a timeout for establishing a connection with a database server.\nIt should be noted that this timeout cannot usually exceed 75 seconds.

\n" + }, + { + "name": "db_get", + "default": "", + "contexts": [ + "location", + "if in location" + ], + "syntax_md": [ + "*`key`*" + ], + "syntax_html": [ + "

key

\n" + ], + "isBlock": false, + "description_md": "Specifies the key to retrieve from the database.\nThe key can contain text, variables, and their combination.\nAn empty key is not allowed.\n\nFor the Redis backend, the key is passed to the `GET` command.\nA successful lookup returns the value as the response body.\n```\nupstream redis_backend {\n db_type redis;\n server 127.0.0.1:6379;\n}\n\nserver {\n location /db/ {\n db_pass redis_backend;\n db_get \"user:$arg_id\";\n }\n}\n```\n\nIf caching is [enabled](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_cache),\nthe evaluated key is also used as the cache key.", + "description_html": "

Specifies the key to retrieve from the database.\nThe key can contain text, variables, and their combination.\nAn empty key is not allowed.

\n\n

For the Redis backend, the key is passed to the GET command.\nA successful lookup returns the value as the response body.

\n\n
upstream redis_backend {\n    db_type redis;\n    server  127.0.0.1:6379;\n}\n\nserver {\n    location /db/ {\n        db_pass redis_backend;\n        db_get  "user:$arg_id";\n    }\n}\n
\n\n

If caching is enabled,\nthe evaluated key is also used as the cache key.

\n" + }, + { + "name": "db_name", + "default": "", + "contexts": [ + "location", + "if in location" + ], + "syntax_md": [ + "*`string`*" + ], + "syntax_html": [ + "

string

\n" + ], + "isBlock": false, + "description_md": "Sets the database to use for lookup requests.\n\nFor the Redis backend, the parameter specifies the database index\npassed to the `SELECT` command. \nIf the directive is not specified or its value is empty,\ndatabase `0` is used:\n```\nlocation /db/ {\n db_pass redis_backend;\n db_name 3;\n db_get $arg_key;\n}\n```", + "description_html": "

Sets the database to use for lookup requests.

\n\n

For the Redis backend, the parameter specifies the database index\npassed to the SELECT command.\nIf the directive is not specified or its value is empty,\ndatabase 0 is used:

\n\n
location /db/ {\n    db_pass redis_backend;\n    db_name 3;\n    db_get  $arg_key;\n}\n
\n" + }, + { + "name": "db_next_upstream", + "default": "error timeout", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "`error` | `timeout` | `invalid_response` | `not_found` `off` ...", + "`off`" + ], + "syntax_html": [ + "

error | timeout | invalid_response | not_found off …

\n", + "

off

\n" + ], + "isBlock": false, + "description_md": "Specifies the conditions under which a request can be passed\nto the next database server:\n- `error`\n\n an error occurred while establishing a connection with the\n server, passing a request to it, or reading the response header;\n- `timeout`\n\n a timeout has occurred while establishing a connection with the\n server, passing a request to it, or reading the response header;\n- `invalid_response`\n\n server returned an invalid response.\n For the Redis backend, this also includes Redis error replies, such as\n authentication failures or key-value mismatch errors;\n- `not_found`\n\n the requested key was not found.\n For the Redis backend, this corresponds to a nil reply\n to the `GET` command;\n \n > The parameter cannot be used when caching of\n > `not_found` results is enabled with the\n > [`db_cache`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_cache) directive.\n- `off`\n\n disables passing a request to the next server.\n\nOne should bear in mind that passing a request to the next server is\nonly possible if nothing has been sent to a client yet.\nThat is, if an error or timeout occurs in the middle of the\ntransferring of a response, fixing this is impossible.\n\nThe directive also defines what is considered an\n[unsuccessful attempt](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails) of communication with a server.\nThe cases of `error` and `timeout`,\nare always considered unsuccessful attempts,\neven if they are not specified in the directive.\nThe case of `invalid_response` is\nconsidered an unsuccessful attempt only if it is specified in the directive.\nThe case of `not_found`\nis never considered an unsuccessful attempt.\n\nPassing a request to the next server can be limited by\n[the number of tries](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_next_upstream_tries)\nand by [time](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_next_upstream_timeout).\n\nThe `not_found` parameter cannot be combined\nwith enabled missing-key caching in [`db_cache`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_cache).", + "description_html": "

Specifies the conditions under which a request can be passed\nto the next database server:

\n\n\n\n

One should bear in mind that passing a request to the next server is\nonly possible if nothing has been sent to a client yet.\nThat is, if an error or timeout occurs in the middle of the\ntransferring of a response, fixing this is impossible.

\n\n

The directive also defines what is considered an\nunsuccessful attempt of communication with a server.\nThe cases of error and timeout,\nare always considered unsuccessful attempts,\neven if they are not specified in the directive.\nThe case of invalid_response is\nconsidered an unsuccessful attempt only if it is specified in the directive.\nThe case of not_found\nis never considered an unsuccessful attempt.

\n\n

Passing a request to the next server can be limited by\nthe number of tries\nand by time.

\n\n

The not_found parameter cannot be combined\nwith enabled missing-key caching in db_cache.

\n" + }, + { + "name": "db_next_upstream_timeout", + "default": "0", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`time`*" + ], + "syntax_html": [ + "

time

\n" + ], + "isBlock": false, + "description_md": "Limits the time during which a request can be passed to the\n[next server](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_next_upstream).\nThe `0` value turns off this limitation.", + "description_html": "

Limits the time during which a request can be passed to the\nnext server.\nThe 0 value turns off this limitation.

\n" + }, + { + "name": "db_next_upstream_tries", + "default": "0", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`number`*" + ], + "syntax_html": [ + "

number

\n" + ], + "isBlock": false, + "description_md": "Limits the number of possible tries for passing a request to the\n[next server](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_next_upstream).\nThe limit includes the initial attempt.\nThe `0` value turns off this limitation.", + "description_html": "

Limits the number of possible tries for passing a request to the\nnext server.\nThe limit includes the initial attempt.\nThe 0 value turns off this limitation.

\n" + }, + { + "name": "db_pass", + "default": "", + "contexts": [ + "location", + "if in location" + ], + "syntax_md": [ + "*`name`*" + ], + "syntax_html": [ + "

name

\n" + ], + "isBlock": false, + "description_md": "Specifies the upstream group used for database lookups:\n```\ndb_pass redis_backend;\n```\nThe group must be configured with [`db_type`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_type).\nA server address cannot be specified directly.\n\nThe [`db_get`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_get) directive must also be configured,\neither in the current configuration or inherited from a parent location.\n\nOnly `GET` and `HEAD` requests\nare accepted.\nOther methods return\n405 (Method Not Allowed).\nThe client request body is discarded.\nClient headers and the request body are not forwarded to the database.\n\nThe response content type is determined by the\n[`types`](https://nginx.org/en/docs/http/ngx_http_core_module.html#types) and\n[`default_type`](https://nginx.org/en/docs/http/ngx_http_core_module.html#default_type)\ndirectives.", + "description_html": "

Specifies the upstream group used for database lookups:

\n\n
db_pass redis_backend;\n
\n\n

The group must be configured with db_type.\nA server address cannot be specified directly.

\n\n

The db_get directive must also be configured,\neither in the current configuration or inherited from a parent location.

\n\n

Only GET and HEAD requests\nare accepted.\nOther methods return\n405 (Method Not Allowed).\nThe client request body is discarded.\nClient headers and the request body are not forwarded to the database.

\n\n

The response content type is determined by the\ntypes and\ndefault_type\ndirectives.

\n" + }, + { + "name": "db_read_timeout", + "default": "60s", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`time`*" + ], + "syntax_html": [ + "

time

\n" + ], + "isBlock": false, + "description_md": "Defines a timeout for reading data from a database server.\nThe timeout is set only between two successive read operations,\nnot for the transmission of the whole response.\nIf the database server does not transmit anything within this time,\nthe connection is closed.", + "description_html": "

Defines a timeout for reading data from a database server.\nThe timeout is set only between two successive read operations,\nnot for the transmission of the whole response.\nIf the database server does not transmit anything within this time,\nthe connection is closed.

\n" + }, + { + "name": "db_send_timeout", + "default": "60s", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`time`*" + ], + "syntax_html": [ + "

time

\n" + ], + "isBlock": false, + "description_md": "Defines a timeout for sending data to a database server.", + "description_html": "

Defines a timeout for sending data to a database server.

\n" + }, + { + "name": "db_socket_keepalive", + "default": "off", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "`on` | `off`" + ], + "syntax_html": [ + "

on | off

\n" + ], + "isBlock": false, + "description_md": "Configures the “TCP keepalive” behavior\nfor outgoing connections to a database server.\nIf enabled, the `SO_KEEPALIVE` socket option is turned on.\n\nThis is distinct from caching idle upstream connections,\nwhich is configured using the\n[`keepalive`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive) directive.", + "description_html": "

Configures the “TCP keepalive” behavior\nfor outgoing connections to a database server.\nIf enabled, the SO_KEEPALIVE socket option is turned on.

\n\n

This is distinct from caching idle upstream connections,\nwhich is configured using the\nkeepalive directive.

\n" + }, + { + "name": "db_ssl", + "default": "off", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "`on` | `off`" + ], + "syntax_html": [ + "

on | off

\n" + ], + "isBlock": false, + "description_md": "Enables TLS for connections to database servers.\n\n> Server certificate verification is disabled by default.\n> Verification is configured separately by\n> [`db_ssl_verify`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_ssl_verify).", + "description_html": "

Enables TLS for connections to database servers.

\n\n
\n

Server certificate verification is disabled by default.\nVerification is configured separately by\ndb_ssl_verify.

\n
\n" + }, + { + "name": "db_ssl_certificate", + "default": "", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`file`*" + ], + "syntax_html": [ + "

file

\n" + ], + "isBlock": false, + "description_md": "Specifies a *`file`* with the certificate in the PEM format\nused for authentication to a database server.\nThe corresponding [`db_ssl_certificate_key`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_ssl_certificate_key)\nmust also be configured.\n\nThe parameter value can contain variables:\n```\ndb_ssl_certificate /etc/nginx/client-certs/$host.crt;\n```", + "description_html": "

Specifies a file with the certificate in the PEM format\nused for authentication to a database server.\nThe corresponding db_ssl_certificate_key\nmust also be configured.

\n\n

The parameter value can contain variables:

\n\n
db_ssl_certificate /etc/nginx/client-certs/$host.crt;\n
\n" + }, + { + "name": "db_ssl_certificate_cache", + "default": "off", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "`off`", + "`max`=*`number`* [`inactive`=*`time`*] [`valid`=*`time`*]" + ], + "syntax_html": [ + "

off

\n", + "

max=number [inactive=time] [valid=time]

\n" + ], + "isBlock": false, + "description_md": "Defines a cache that stores\n[SSL certificates](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_ssl_certificate) and\n[secret keys](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_ssl_certificate_key)\nspecified with [variables](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_ssl_certificate_key_variables).\n\nThe directive has the following parameters:\n- `max`\n\n sets the maximum number of elements in the cache;\n on cache overflow the least recently used (LRU) elements are removed;\n- `inactive`\n\n defines a time after which an element is removed from the cache\n if it has not been accessed during this time;\n by default, it is 10 seconds;\n- `valid`\n\n defines a time during which\n an element in the cache is considered valid\n and can be reused;\n by default, it is 60 seconds.\n Certificates that exceed this time will be reloaded or revalidated;\n- `off`\n\n disables the cache.\n\nExample:\n```\ndb_ssl_certificate_cache max=1000 inactive=20s valid=1m;\n```", + "description_html": "

Defines a cache that stores\nSSL certificates and\nsecret keys\nspecified with variables.

\n\n

The directive has the following parameters:

\n\n\n\n

Example:

\n\n
db_ssl_certificate_cache max=1000 inactive=20s valid=1m;\n
\n" + }, + { + "name": "db_ssl_certificate_key", + "default": "", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`file`*" + ], + "syntax_html": [ + "

file

\n" + ], + "isBlock": false, + "description_md": "Specifies a *`file`* with the secret key in the PEM format\nfor the certificate configured by the\n[`db_ssl_certificate`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_ssl_certificate) directive.\n\nThe parameter value can contain variables:\n```\ndb_ssl_certificate_key /etc/nginx/client-certs/$host.key;\n```", + "description_html": "

Specifies a file with the secret key in the PEM format\nfor the certificate configured by the\ndb_ssl_certificate directive.

\n\n

The parameter value can contain variables:

\n\n
db_ssl_certificate_key /etc/nginx/client-certs/$host.key;\n
\n" + }, + { + "name": "db_ssl_ciphers", + "default": "DEFAULT", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`ciphers`*" + ], + "syntax_html": [ + "

ciphers

\n" + ], + "isBlock": false, + "description_md": "Specifies the enabled ciphers for connections to database servers.\nThe ciphers are specified in the format understood by the OpenSSL library.", + "description_html": "

Specifies the enabled ciphers for connections to database servers.\nThe ciphers are specified in the format understood by the OpenSSL library.

\n" + }, + { + "name": "db_ssl_conf_command", + "default": "", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`name`* *`value`*" + ], + "syntax_html": [ + "

name value

\n" + ], + "isBlock": false, + "description_md": "Sets arbitrary OpenSSL configuration\n[commands](https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html)\nwhen establishing a connection with the database server.\n\nSeveral `db_ssl_conf_command` directives\ncan be specified on the same level.\nThese directives are inherited from the previous configuration level\nif and only if there are\nno `db_ssl_conf_command` directives\ndefined on the current level.\n\n> Note that configuring OpenSSL directly\n> might result in unexpected behavior.", + "description_html": "

Sets arbitrary OpenSSL configuration\ncommands\nwhen establishing a connection with the database server.

\n\n

Several db_ssl_conf_command directives\ncan be specified on the same level.\nThese directives are inherited from the previous configuration level\nif and only if there are\nno db_ssl_conf_command directives\ndefined on the current level.

\n\n
\n

Note that configuring OpenSSL directly\nmight result in unexpected behavior.

\n
\n" + }, + { + "name": "db_ssl_crl", + "default": "", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`file`*" + ], + "syntax_html": [ + "

file

\n" + ], + "isBlock": false, + "description_md": "Specifies a *`file`* with revoked certificates (CRL)\nin the PEM format used to [verify](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_ssl_verify)\nthe certificate of the database server.\nWhen using intermediate certificates, their CRLs should be\nspecified in the same file.", + "description_html": "

Specifies a file with revoked certificates (CRL)\nin the PEM format used to verify\nthe certificate of the database server.\nWhen using intermediate certificates, their CRLs should be\nspecified in the same file.

\n" + }, + { + "name": "db_ssl_key_log", + "default": "", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`file`*" + ], + "syntax_html": [ + "

file

\n" + ], + "isBlock": false, + "description_md": "Enables logging of database server connection SSL keys\nand specifies the path to the key log file.\nKeys are logged in the\n[SSLKEYLOGFILE](https://datatracker.ietf.org/doc/html/rfc9850)\nformat compatible with Wireshark.\n\n> TLS key logs contain sensitive material that can enable decryption\n> of captured traffic.\n> Protect these files and enable logging only when needed.", + "description_html": "

Enables logging of database server connection SSL keys\nand specifies the path to the key log file.\nKeys are logged in the\nSSLKEYLOGFILE\nformat compatible with Wireshark.

\n\n
\n

TLS key logs contain sensitive material that can enable decryption\nof captured traffic.\nProtect these files and enable logging only when needed.

\n
\n" + }, + { + "name": "db_ssl_name", + "default": "", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`name`*" + ], + "syntax_html": [ + "

name

\n" + ], + "isBlock": false, + "description_md": "Allows overriding the server name used to\n[verify](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_ssl_verify)\nthe database server certificate and to be\n[passed through SNI](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_ssl_server_name)\nwhen establishing a connection with the database server.", + "description_html": "

Allows overriding the server name used to\nverify\nthe database server certificate and to be\npassed through SNI\nwhen establishing a connection with the database server.

\n" + }, + { + "name": "db_ssl_password_file", + "default": "", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`file`*" + ], + "syntax_html": [ + "

file

\n" + ], + "isBlock": false, + "description_md": "Specifies a *`file`* with passphrases for\n[secret keys](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_ssl_certificate_key)\nwhere each passphrase is specified on a separate line.\nPassphrases are tried in turn when loading the key.", + "description_html": "

Specifies a file with passphrases for\nsecret keys\nwhere each passphrase is specified on a separate line.\nPassphrases are tried in turn when loading the key.

\n" + }, + { + "name": "db_ssl_protocols", + "default": "TLSv1.2 TLSv1.3", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "[`SSLv2`] [`SSLv3`] [`TLSv1`] [`TLSv1.1`] [`TLSv1.2`] [`TLSv1.3`]" + ], + "syntax_html": [ + "

[SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]

\n" + ], + "isBlock": false, + "description_md": "Enables the specified protocols for connections to database servers.", + "description_html": "

Enables the specified protocols for connections to database servers.

\n" + }, + { + "name": "db_ssl_server_name", + "default": "off", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "`on` | `off`" + ], + "syntax_html": [ + "

on | off

\n" + ], + "isBlock": false, + "description_md": "Enables or disables passing of the\n[server name](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_ssl_name) through\n[TLS Server Name Indication extension](http://en.wikipedia.org/wiki/Server_Name_Indication) (SNI, RFC 6066)\nwhen establishing a connection with the database server.", + "description_html": "

Enables or disables passing of the\nserver name through\nTLS Server Name Indication extension (SNI, RFC 6066)\nwhen establishing a connection with the database server.

\n" + }, + { + "name": "db_ssl_session_reuse", + "default": "on", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "`on` | `off`" + ], + "syntax_html": [ + "

on | off

\n" + ], + "isBlock": false, + "description_md": "Determines whether SSL sessions can be reused when working with\nthe database server.\nIf the errors\n“`digest check failed`”\nappear in the logs, try disabling session reuse.", + "description_html": "

Determines whether SSL sessions can be reused when working with\nthe database server.\nIf the errors\n“digest check failed”\nappear in the logs, try disabling session reuse.

\n" + }, + { + "name": "db_ssl_trusted_certificate", + "default": "", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`file`*" + ], + "syntax_html": [ + "

file

\n" + ], + "isBlock": false, + "description_md": "Specifies a *`file`* with trusted CA certificates in the PEM format\nused to [verify](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_ssl_verify)\nthe certificate of the database server.", + "description_html": "

Specifies a file with trusted CA certificates in the PEM format\nused to verify\nthe certificate of the database server.

\n" + }, + { + "name": "db_ssl_verify", + "default": "off", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "`on` | `off`" + ], + "syntax_html": [ + "

on | off

\n" + ], + "isBlock": false, + "description_md": "Enables or disables verification of the database server certificate.\nThe [`db_ssl_trusted_certificate`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_ssl_trusted_certificate) directive\nmust also be configured.\nThe directive is required when [`db_ssl_verify`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_ssl_verify) is enabled.", + "description_html": "

Enables or disables verification of the database server certificate.\nThe db_ssl_trusted_certificate directive\nmust also be configured.\nThe directive is required when db_ssl_verify is enabled.

\n" + }, + { + "name": "db_ssl_verify_depth", + "default": "1", + "contexts": [ + "http", + "server", + "location" + ], + "syntax_md": [ + "*`number`*" + ], + "syntax_html": [ + "

number

\n" + ], + "isBlock": false, + "description_md": "Sets the verification depth in the database server certificate chain.\nThe directive is required when [`db_ssl_verify`](https://nginx.org/en/docs/http/ngx_http_db_module.html#db_ssl_verify) is enabled.", + "description_html": "

Sets the verification depth in the database server certificate chain.\nThe directive is required when db_ssl_verify is enabled.

\n" + }, + { + "name": "db_type", + "default": "", + "contexts": [ + "upstream" + ], + "syntax_md": [ + "*`type`*" + ], + "syntax_html": [ + "

type

\n" + ], + "isBlock": false, + "description_md": "Sets the database protocol used by the upstream group.\nCurrently, only `redis` is supported:\n```\nupstream redis_backend {\n server 127.0.0.1:6379;\n db_type redis;\n}\n```\nThe protocol name is case-insensitive.", + "description_html": "

Sets the database protocol used by the upstream group.\nCurrently, only redis is supported:

\n\n
upstream redis_backend {\n    server  127.0.0.1:6379;\n    db_type redis;\n}\n
\n\n

The protocol name is case-insensitive.

\n" + }, + { + "name": "db_var", + "default": "", + "contexts": [ + "server", + "location", + "if in location" + ], + "syntax_md": [ + "*`$variable`* `location`=*`URI`* `query`=*`string`* [`default`=*`string`*]" + ], + "syntax_html": [ + "

$variable location=URI query=string [default=string]

\n" + ], + "isBlock": false, + "description_md": "Creates a variable whose value is obtained\nfrom the response body of a subrequest.\nThe `location` parameter sets the subrequest URI.\nThe `query` parameter sets its query string.\nAn empty query string can be specified explicitly:\n```\ndb_var $configuration /_configuration \"\";\n```\nThe parameter values can contain text, variables, and their combination.\n\nIf the subrequest returns the 200 (OK),\nits response body is assigned to the variable.\nAn empty response body is a valid value.\n\nIf the subrequest returns the 404 (Not Found),\nthe value specified by the `default` parameter\nis assigned to the variable.\nThe parameter value can contain variables.\nIf no `default` parameter is specified,\nthe variable is marked as not found.\n\nVariables are populated during the pre-access phase, not when first evaluated.\nThey should be consumed in subsequent processing phases,\nsuch as access or content processing.\nReading them earlier, for example in rewrite-phase\n[`if`](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#if),\n[`set`](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#set), or\n[`return`](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#return) processing,\ndoes not initiate a lookup.", + "description_html": "

Creates a variable whose value is obtained\nfrom the response body of a subrequest.\nThe location parameter sets the subrequest URI.\nThe query parameter sets its query string.\nAn empty query string can be specified explicitly:

\n\n
db_var $configuration /_configuration "";\n
\n\n

The parameter values can contain text, variables, and their combination.

\n\n

If the subrequest returns the 200 (OK),\nits response body is assigned to the variable.\nAn empty response body is a valid value.

\n\n

If the subrequest returns the 404 (Not Found),\nthe value specified by the default parameter\nis assigned to the variable.\nThe parameter value can contain variables.\nIf no default parameter is specified,\nthe variable is marked as not found.

\n\n

Variables are populated during the pre-access phase, not when first evaluated.\nThey should be consumed in subsequent processing phases,\nsuch as access or content processing.\nReading them earlier, for example in rewrite-phase\nif,\nset, or\nreturn processing,\ndoes not initiate a lookup.

\n" + } + ] + }, { "id": "/en/docs/http/ngx_http_empty_gif_module.html", "name": "ngx_http_empty_gif_module", @@ -6901,6 +7480,22 @@ "description_md": "Specifies a custom\n[key-value database](https://nginx.org/en/docs/http/ngx_http_keyval_module.html#keyval_zone)\nthat stores session data.\nBy default, an 8-megabyte key-value database named \n`oidc_default_store_`\nis created automatically.\n> A separate key-value database should be configured for each Provider\n> to prevent session reuse across providers.", "description_html": "

Specifies a custom\nkey-value database\nthat stores session data.\nBy default, an 8-megabyte key-value database named\noidc_default_store_<provider name>\nis created automatically.

\n\n
\n

A separate key-value database should be configured for each Provider\nto prevent session reuse across providers.

\n
\n" }, + { + "name": "session_sync_leeway", + "default": "0", + "contexts": [ + "oidc_provider" + ], + "syntax_md": [ + "*`time`*" + ], + "syntax_html": [ + "

time

\n" + ], + "isBlock": false, + "description_md": "Sets the maximum wait time for a session to appear in the\n[key-value zone](https://nginx.org/en/docs/http/ngx_http_oidc_module.html#session_store)\nif a request contains a session cookie\nbut the corresponding session is not found.\nThis allows for session\n[synchronization](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html)\ndelays between cluster nodes.\n\nThe value must be in the range from `0` to\n`5s`.\nThe default value of `0` disables waiting.\nIt is recommended to set the smallest possible value.", + "description_html": "

Sets the maximum wait time for a session to appear in the\nkey-value zone\nif a request contains a session cookie\nbut the corresponding session is not found.\nThis allows for session\nsynchronization\ndelays between cluster nodes.

\n\n

The value must be in the range from 0 to\n5s.\nThe default value of 0 disables waiting.\nIt is recommended to set the smallest possible value.

\n" + }, { "name": "session_timeout", "default": "8h", @@ -13330,8 +13925,8 @@ "

on | off

\n" ], "isBlock": false, - "description_md": "Enables routing of QUIC packets using\n[eBPF](https://ebpf.io/).\nWhen enabled, this allows supporting QUIC connection migration.\n\n> The directive is only supported on Linux 5.7+.", - "description_html": "

Enables routing of QUIC packets using\neBPF.\nWhen enabled, this allows supporting QUIC connection migration.

\n\n
\n

The directive is only supported on Linux 5.7+.

\n
\n" + "description_md": "Enables routing of QUIC packets using\n[eBPF](https://ebpf.io/).\nWhen enabled, this allows supporting QUIC connection migration.\nSince 1.31.7, this also allows established QUIC connections\nto be preserved during\n[configuration reloads](https://nginx.org/en/docs/control.html#reconfiguration)\nand during [live upgrade](https://nginx.org/en/docs/control.html#upgrade).\n\n> The directive value cannot be changed during a configuration reload.\n> To change the directive value, nginx must be restarted.\n> The directive cannot be disabled during the live upgrade\n> if QUIC BPF maps are inherited from the previous nginx instance.\n\n> The directive is only supported on Linux 5.7+.", + "description_html": "

Enables routing of QUIC packets using\neBPF.\nWhen enabled, this allows supporting QUIC connection migration.\nSince 1.31.7, this also allows established QUIC connections\nto be preserved during\nconfiguration reloads\nand during live upgrade.

\n\n
\n

The directive value cannot be changed during a configuration reload.\nTo change the directive value, nginx must be restarted.\nThe directive cannot be disabled during the live upgrade\nif QUIC BPF maps are inherited from the previous nginx instance.

\n\n

The directive is only supported on Linux 5.7+.

\n
\n" }, { "name": "quic_gso", @@ -18679,5 +19274,5 @@ ] } ], - "version": "https://github.com/nginx/nginx.org/commit/03838d44c7bc13bd75cb63fa4308ab7187d4dd9d" + "version": "https://github.com/nginx/nginx.org/commit/0ebe7b53ff30e8c4fbf348881b4c8bcec3cf27cb" }