1.0 | 1.1
1.0 | 1.1 | 2
Sets the HTTP protocol version for proxying.\nBy default, version 1.0 is used.\nVersion 1.1 is recommended for use with\nkeepalive\nconnections and\nNTLM authentication.
Sets the HTTP protocol version for proxying.\nBy default, version 1.0 is used.\nVersion 1.1 or 2 (1.29.4) is recommended for use with\nkeepalive\nconnections and\nNTLM authentication.
on | off
Enables or disables buffering of a client request body.
\n\nWhen buffering is enabled, the entire request body is\nread\nfrom the client before sending the request to a proxied server.
\n\nWhen buffering is disabled, the request body is sent to the proxied server\nimmediately as it is received.\nIn this case, the request cannot be passed to the\nnext server\nif nginx already started sending the request body.
\n\nWhen HTTP/1.1 chunked transfer encoding is used\nto send the original request body,\nthe request body will be buffered regardless of the directive value unless\nHTTP/1.1 is enabled for proxying.
\n" + "description_md": "Enables or disables buffering of a client request body.\n\nWhen buffering is enabled, the entire request body is\n[read](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size)\nfrom the client before sending the request to a proxied server.\n\nWhen buffering is disabled, the request body is sent to the proxied server\nimmediately as it is received.\nIn this case, the request cannot be passed to the\n[next server](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream)\nif nginx already started sending the request body.\n\nWhen HTTP/1.1 chunked transfer encoding is used\nto send the original request body,\nthe request body will be buffered regardless of the directive value unless\nHTTP/1.1 or HTTP/2 is [enabled](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_http_version) for proxying.", + "description_html": "Enables or disables buffering of a client request body.
\n\nWhen buffering is enabled, the entire request body is\nread\nfrom the client before sending the request to a proxied server.
\n\nWhen buffering is disabled, the request body is sent to the proxied server\nimmediately as it is received.\nIn this case, the request cannot be passed to the\nnext server\nif nginx already started sending the request body.
\n\nWhen HTTP/1.1 chunked transfer encoding is used\nto send the original request body,\nthe request body will be buffered regardless of the directive value unless\nHTTP/1.1 or HTTP/2 is enabled for proxying.
\n" }, { "name": "proxy_request_dynamic", @@ -7838,8 +7838,8 @@ "field value
Allows redefining or appending fields to the request header\npassed to the proxied server.\nThe value can contain text, variables, and their combinations.\nThese directives are inherited from the previous configuration level\nif and only if there are no proxy_set_header directives\ndefined on the current level.\nBy default, only two fields are redefined:
proxy_set_header Host $proxy_host;\nproxy_set_header Connection close;\nIf caching is enabled, the header fields\n“If-Modified-Since”,\n“If-Unmodified-Since”,\n“If-None-Match”,\n“If-Match”,\n“Range”,\nand\n“If-Range”\nfrom the original request are not passed to the proxied server.
\n\nAn unchanged “Host” request header field can be passed like this:
\n\nproxy_set_header Host $http_host;\nHowever, if this field is not present in a client request header then\nnothing will be passed.\nIn such a case it is better to use the $host variable—its\nvalue equals the server name in the “Host” request header\nfield or the primary server name if this field is not present:
proxy_set_header Host $host;\nIn addition, the server name can be passed together with the port of the\nproxied server:
\n\nproxy_set_header Host $host:$proxy_port;\nIf the value of a header field is an empty string then this\nfield will not be passed to a proxied server:
\n\nproxy_set_header Accept-Encoding "";\nAllows redefining or appending fields to the request header\npassed to the proxied server.\nThe value can contain text, variables, and their combinations.\nThese directives are inherited from the previous configuration level\nif and only if there are no proxy_set_header directives\ndefined on the current level.
By default, the header fields\n“Host”\nand\n“Connection”\nfrom the original request are not passed to the proxied server.\nIf HTTP/1.0 or HTTP/1.1 is\nenabled for proxying,\nthese fields are redefined:
\n\nproxy_set_header Host $proxy_host;\nproxy_set_header Connection close;\nFor HTTP/2, the\n“:authority”\npseudo-header field with the\n$proxy_host\nvalue is sent by default,\nunless it is replaced with an explicit “Host” header field.
If caching is enabled, the header fields\n“If-Modified-Since”,\n“If-Unmodified-Since”,\n“If-None-Match”,\n“If-Match”,\n“Range”,\nand\n“If-Range”\nfrom the original request are not passed to the proxied server.
\n\nAn unchanged “Host” request header field can be passed like this:
\n\nproxy_set_header Host $http_host;\nHowever, if this field is not present in a client request header then\nnothing will be passed.\nIn such a case it is better to use the $host variable—its\nvalue equals the server name in the “Host” request header\nfield or the primary server name if this field is not present:
proxy_set_header Host $host;\nIn addition, the server name can be passed together with the port of the\nproxied server:
\n\nproxy_set_header Host $host:$proxy_port;\nIf the value of a header field is an empty string then this\nfield will not be passed to a proxied server:
\n\nproxy_set_header Accept-Encoding "";\nSpecifies a curve for ECDHE ciphers.
When using OpenSSL 1.0.2 or higher,\nit is possible to specify multiple curves (1.11.0), for example:
\n\nssl_ecdh_curve prime256v1:secp384r1;\nThe special value auto (1.11.0) instructs nginx to use\na list built into the OpenSSL library when using OpenSSL 1.0.2 or higher,\nor prime256v1 with older versions.
\n\n" }, + { + "name": "ssl_ech_file", + "default": "", + "contexts": [ + "http", + "server" + ], + "syntax_md": [ + "*`file`*" + ], + "syntax_html": [ + "Prior to version 1.11.0,\nthe
\n\nprime256v1curve was used by default.When using OpenSSL 1.0.2 or higher,\nthis directive sets the list of curves supported by the server.\nThus, in order for ECDSA certificates to work,\nit is important to include the curves used in the certificates.
\n
file
Specifies a file with encrypted ClientHello configuration\n(ECHConfig) in the\nPEM\nformat used to enable TLS 1.3\nECH\nin shared mode.
\n\n" + }, { "name": "ssl_key_log", "default": "", @@ -10354,6 +10371,16 @@ "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": "The directive is currently supported only when using OpenSSL\nECH feature branch.
\n
returns “1” if\nTLS 1.3 early data is used\nand the handshake is not complete, otherwise “” (1.15.3).
returns the public server name requested through\nSNI\nif TLS 1.3 ECH was accepted,\notherwise “” (1.29.4);
\n" + }, + { + "name": "$ssl_ech_status", + "description_md": "returns the result of TLS 1.3 [ECH](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ech_file) processing:\n“`FAILED`”,\n“`BACKEND`”,\n“`GREASE`”,\n“`SUCCESS`”, or\n“`NOT_TRIED`” (1.29.4);\n> The variable is currently supported only when using OpenSSL\n> [ECH feature branch](https://github.com/openssl/openssl/tree/feature/ech)\n> and is therefore subject to change.\n> The variable value will otherwise be an empty string.", + "description_html": "returns the result of TLS 1.3 ECH processing:\n“FAILED”,\n“BACKEND”,\n“GREASE”,\n“SUCCESS”, or\n“NOT_TRIED” (1.29.4);
\n\n" + }, { "name": "$ssl_protocol", "description_md": "returns the protocol of an established SSL connection;", @@ -10975,8 +11002,8 @@ "The variable is currently supported only when using OpenSSL\nECH feature branch\nand is therefore subject to change.\nThe variable value will otherwise be an empty string.
\n
connections
Activates the cache for connections to upstream servers.
\n\nThe connections parameter sets the maximum number of\nidle keepalive connections to upstream servers that are preserved in\nthe cache of each worker process.\nWhen this number is exceeded, the least recently used connections\nare closed.
\n\n\nIt should be particularly noted that the
\n\nkeepalivedirective\ndoes not limit the total number of connections to upstream servers\nthat an nginx worker process can open.\nTheconnectionsparameter should be set to a number small enough\nto let upstream servers process new incoming connections as well.When using load balancing methods other than the default\nround-robin method, it is necessary to activate them before\nthe
\nkeepalivedirective.
Example configuration of memcached upstream with keepalive connections:
\n\nupstream memcached_backend {\n server 127.0.0.1:11211;\n server 10.0.0.2:11211;\n\n keepalive 32;\n}\n\nserver {\n ...\n\n location /memcached/ {\n set $memcached_key $uri;\n memcached_pass memcached_backend;\n }\n\n}\nFor HTTP, the proxy_http_version\ndirective should be set to “1.1”\nand the “Connection” header field should be cleared:
upstream http_backend {\n server 127.0.0.1:8080;\n\n keepalive 16;\n}\n\nserver {\n ...\n\n location /http/ {\n proxy_pass http://http_backend;\n proxy_http_version 1.1;\n proxy_set_header Connection "";\n ...\n }\n}\n\n\n\nAlternatively, HTTP/1.0 persistent connections can be used by passing the\n“Connection: Keep-Alive” header field to an upstream server,\nthough this method is not recommended.
\n
For FastCGI servers, it is required to set\nfastcgi_keep_conn\nfor keepalive connections to work:
upstream fastcgi_backend {\n server 127.0.0.1:9000;\n\n keepalive 8;\n}\n\nserver {\n ...\n\n location /fastcgi/ {\n fastcgi_pass fastcgi_backend;\n fastcgi_keep_conn on;\n ...\n }\n}\n\n\n" + "description_md": "Activates the cache for connections to upstream servers.\n\nThe *`connections`* parameter sets the maximum number of\nidle keepalive connections to upstream servers that are preserved in\nthe cache of each worker process.\nWhen this number is exceeded, the least recently used connections\nare closed.\n> It should be particularly noted that the `keepalive` directive\n> does not limit the total number of connections to upstream servers\n> that an nginx worker process can open.\n> The *`connections`* parameter should be set to a number small enough\n> to let upstream servers process new incoming connections as well.\n\n\n> When using load balancing methods other than the default\n> round-robin method, it is necessary to activate them before\n> the `keepalive` directive.\n\nExample configuration of memcached upstream with keepalive connections:\n```\nupstream memcached_backend {\n server 127.0.0.1:11211;\n server 10.0.0.2:11211;\n\n keepalive 32;\n}\n\nserver {\n ...\n\n location /memcached/ {\n set $memcached_key $uri;\n memcached_pass memcached_backend;\n }\n\n}\n```\n\nFor HTTP, the [`proxy_http_version`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_http_version)\ndirective should be set to “`1.1`” or “`2`”\nand the \"Connection\" header field should be cleared:\n```\nupstream http_backend {\n server 127.0.0.1:8080;\n\n keepalive 16;\n}\n\nserver {\n ...\n\n location /http/ {\n proxy_pass http://http_backend;\n proxy_http_version 1.1;\n proxy_set_header Connection \"\";\n ...\n }\n}\n```\n\n> Alternatively, HTTP/1.0 persistent connections can be used by passing the\n> \"Connection: Keep-Alive\" header field to an upstream server,\n> though this method is not recommended.\n\nFor FastCGI servers, it is required to set\n[`fastcgi_keep_conn`](https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_keep_conn)\nfor keepalive connections to work:\n```\nupstream fastcgi_backend {\n server 127.0.0.1:9000;\n\n keepalive 8;\n}\n\nserver {\n ...\n\n location /fastcgi/ {\n fastcgi_pass fastcgi_backend;\n fastcgi_keep_conn on;\n ...\n }\n}\n```\n\n> SCGI and uwsgi protocols do not have a notion of keepalive connections.", + "description_html": "SCGI and uwsgi protocols do not have a notion of keepalive connections.
\n
Activates the cache for connections to upstream servers.
\n\nThe connections parameter sets the maximum number of\nidle keepalive connections to upstream servers that are preserved in\nthe cache of each worker process.\nWhen this number is exceeded, the least recently used connections\nare closed.
\n\n\nIt should be particularly noted that the
\n\nkeepalivedirective\ndoes not limit the total number of connections to upstream servers\nthat an nginx worker process can open.\nTheconnectionsparameter should be set to a number small enough\nto let upstream servers process new incoming connections as well.When using load balancing methods other than the default\nround-robin method, it is necessary to activate them before\nthe
\nkeepalivedirective.
Example configuration of memcached upstream with keepalive connections:
\n\nupstream memcached_backend {\n server 127.0.0.1:11211;\n server 10.0.0.2:11211;\n\n keepalive 32;\n}\n\nserver {\n ...\n\n location /memcached/ {\n set $memcached_key $uri;\n memcached_pass memcached_backend;\n }\n\n}\nFor HTTP, the proxy_http_version\ndirective should be set to “1.1” or “2”\nand the “Connection” header field should be cleared:
upstream http_backend {\n server 127.0.0.1:8080;\n\n keepalive 16;\n}\n\nserver {\n ...\n\n location /http/ {\n proxy_pass http://http_backend;\n proxy_http_version 1.1;\n proxy_set_header Connection "";\n ...\n }\n}\n\n\n\nAlternatively, HTTP/1.0 persistent connections can be used by passing the\n“Connection: Keep-Alive” header field to an upstream server,\nthough this method is not recommended.
\n
For FastCGI servers, it is required to set\nfastcgi_keep_conn\nfor keepalive connections to work:
upstream fastcgi_backend {\n server 127.0.0.1:9000;\n\n keepalive 8;\n}\n\nserver {\n ...\n\n location /fastcgi/ {\n fastcgi_pass fastcgi_backend;\n fastcgi_keep_conn on;\n ...\n }\n}\n\n\n" }, { "name": "keepalive_requests", @@ -11039,8 +11066,8 @@ "" ], "isBlock": false, - "description_md": "Allows proxying requests with\n[NTLM Authentication](https://en.wikipedia.org/wiki/Integrated_Windows_Authentication).\nThe upstream connection is bound to the client connection\nonce the client sends a request with the \"Authorization\"\nheader field value\nstarting with “`Negotiate`” or “`NTLM`”.\nFurther client requests will be proxied through the same upstream connection,\nkeeping the authentication context.\n\nIn order for NTLM authentication to work,\nit is necessary to enable keepalive connections to upstream servers.\nThe [`proxy_http_version`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_http_version)\ndirective should be set to “`1.1`”\nand the \"Connection\" header field should be cleared:\n```\nupstream http_backend {\n server 127.0.0.1:8080;\n\n ntlm;\n}\n\nserver {\n ...\n\n location /http/ {\n proxy_pass http://http_backend;\n proxy_http_version 1.1;\n proxy_set_header Connection \"\";\n ...\n }\n}\n```\n\n> When using load balancer methods other than the default\n> round-robin method, it is necessary to activate them before\n> the `ntlm` directive.\n\n> This directive is available as part of our\n> [commercial subscription](https://nginx.com/products/).", - "description_html": "SCGI and uwsgi protocols do not have a notion of keepalive connections.
\n
Allows proxying requests with\nNTLM Authentication.\nThe upstream connection is bound to the client connection\nonce the client sends a request with the “Authorization”\nheader field value\nstarting with “Negotiate” or “NTLM”.\nFurther client requests will be proxied through the same upstream connection,\nkeeping the authentication context.
In order for NTLM authentication to work,\nit is necessary to enable keepalive connections to upstream servers.\nThe proxy_http_version\ndirective should be set to “1.1”\nand the “Connection” header field should be cleared:
upstream http_backend {\n server 127.0.0.1:8080;\n\n ntlm;\n}\n\nserver {\n ...\n\n location /http/ {\n proxy_pass http://http_backend;\n proxy_http_version 1.1;\n proxy_set_header Connection "";\n ...\n }\n}\n\n\n" + "description_md": "Allows proxying requests with\n[NTLM Authentication](https://en.wikipedia.org/wiki/Integrated_Windows_Authentication).\nThe upstream connection is bound to the client connection\nonce the client sends a request with the \"Authorization\"\nheader field value\nstarting with “`Negotiate`” or “`NTLM`”.\nFurther client requests will be proxied through the same upstream connection,\nkeeping the authentication context.\n\nIn order for NTLM authentication to work,\nit is necessary to enable keepalive connections to upstream servers.\nThe [`proxy_http_version`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_http_version)\ndirective should be set to “`1.1`” or “`2`”\nand the \"Connection\" header field should be cleared:\n```\nupstream http_backend {\n server 127.0.0.1:8080;\n\n ntlm;\n}\n\nserver {\n ...\n\n location /http/ {\n proxy_pass http://http_backend;\n proxy_http_version 1.1;\n proxy_set_header Connection \"\";\n ...\n }\n}\n```\n\n> When using load balancer methods other than the default\n> round-robin method, it is necessary to activate them before\n> the `ntlm` directive.\n\n> This directive is available as part of our\n> [commercial subscription](https://nginx.com/products/).", + "description_html": "When using load balancer methods other than the default\nround-robin method, it is necessary to activate them before\nthe
\n\nntlmdirective.This directive is available as part of our\ncommercial subscription.
\n
Allows proxying requests with\nNTLM Authentication.\nThe upstream connection is bound to the client connection\nonce the client sends a request with the “Authorization”\nheader field value\nstarting with “Negotiate” or “NTLM”.\nFurther client requests will be proxied through the same upstream connection,\nkeeping the authentication context.
In order for NTLM authentication to work,\nit is necessary to enable keepalive connections to upstream servers.\nThe proxy_http_version\ndirective should be set to “1.1” or “2”\nand the “Connection” header field should be cleared:
upstream http_backend {\n server 127.0.0.1:8080;\n\n ntlm;\n}\n\nserver {\n ...\n\n location /http/ {\n proxy_pass http://http_backend;\n proxy_http_version 1.1;\n proxy_set_header Connection "";\n ...\n }\n}\n\n\n" }, { "name": "least_conn", @@ -17053,6 +17080,23 @@ "description_md": "Specifies a *`curve`* for ECDHE ciphers.\n\nWhen using OpenSSL 1.0.2 or higher,\nit is possible to specify multiple curves (1.11.0), for example:\n```\nssl_ecdh_curve prime256v1:secp384r1;\n```\n\nThe special value `auto` (1.11.0) instructs nginx to use\na list built into the OpenSSL library when using OpenSSL 1.0.2 or higher,\nor `prime256v1` with older versions.\n\n> Prior to version 1.11.0,\n> the `prime256v1` curve was used by default.\n\n> When using OpenSSL 1.0.2 or higher,\n> this directive sets the list of curves supported by the server.\n> Thus, in order for ECDSA certificates to work,\n> it is important to include the curves used in the certificates.", "description_html": "When using load balancer methods other than the default\nround-robin method, it is necessary to activate them before\nthe
\n\nntlmdirective.This directive is available as part of our\ncommercial subscription.
\n
Specifies a curve for ECDHE ciphers.
When using OpenSSL 1.0.2 or higher,\nit is possible to specify multiple curves (1.11.0), for example:
\n\nssl_ecdh_curve prime256v1:secp384r1;\nThe special value auto (1.11.0) instructs nginx to use\na list built into the OpenSSL library when using OpenSSL 1.0.2 or higher,\nor prime256v1 with older versions.
\n\n" }, + { + "name": "ssl_ech_file", + "default": "", + "contexts": [ + "stream", + "server" + ], + "syntax_md": [ + "*`file`*" + ], + "syntax_html": [ + "Prior to version 1.11.0,\nthe
\n\nprime256v1curve was used by default.When using OpenSSL 1.0.2 or higher,\nthis directive sets the list of curves supported by the server.\nThus, in order for ECDSA certificates to work,\nit is important to include the curves used in the certificates.
\n
file
Specifies a file with encrypted ClientHello configuration\n(ECHConfig) in the\nPEM\nformat used to enable TLS 1.3\nECH\nin shared mode.
\n\n" + }, { "name": "ssl_handshake_timeout", "default": "60s", @@ -17475,6 +17519,16 @@ "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": "The directive is currently supported only when using OpenSSL\nECH feature branch.
\n
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\n" }, + { + "name": "$ssl_ech_outer_server_name", + "description_md": "returns the public server name requested through\n[SNI](http://en.wikipedia.org/wiki/Server_Name_Indication)\nif TLS 1.3 [ECH](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html#ssl_ech_file) was accepted,\notherwise “” (1.29.4);", + "description_html": "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\nThe variable is available only for new sessions.
\n
returns the public server name requested through\nSNI\nif TLS 1.3 ECH was accepted,\notherwise “” (1.29.4);
\n" + }, + { + "name": "$ssl_ech_status", + "description_md": "returns the result of TLS 1.3 [ECH](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html#ssl_ech_file) processing:\n“`FAILED`”,\n“`BACKEND`”,\n“`GREASE`”,\n“`SUCCESS`”, or\n“`NOT_TRIED`” (1.29.4);\n> The variable is currently supported only when using OpenSSL\n> [ECH feature branch](https://github.com/openssl/openssl/tree/feature/ech)\n> and is therefore subject to change.\n> The variable value will otherwise be an empty string.", + "description_html": "returns the result of TLS 1.3 ECH processing:\n“FAILED”,\n“BACKEND”,\n“GREASE”,\n“SUCCESS”, or\n“NOT_TRIED” (1.29.4);
\n\n" + }, { "name": "$ssl_protocol", "description_md": "returns the protocol of an established SSL connection;", @@ -18162,5 +18216,5 @@ ] } ], - "version": "https://github.com/nginx/nginx.org/commit/fd2e4792287dc0c4e167a7242dd7c56a38d44e3b" + "version": "https://github.com/nginx/nginx.org/commit/cc7bceb22509727fe8eb25c6def1b01e33671fb7" }The variable is currently supported only when using OpenSSL\nECH feature branch\nand is therefore subject to change.\nThe variable value will otherwise be an empty string.
\n