Mercurial > hg > nginx-site
changeset 2956:a85e4d126bc7
Updated docs for the upcoming NGINX Plus release.
line wrap: on
line diff
--- a/xml/en/GNUmakefile +++ b/xml/en/GNUmakefile @@ -24,6 +24,7 @@ DOCS = \ contributing_changes \ beginners_guide \ configure \ + quic \ FAQ = \ welcome_nginx_facebook \ @@ -61,6 +62,7 @@ REFS = \ http/ngx_http_hls_module \ http/ngx_http_image_filter_module \ http/ngx_http_index_module \ + http/ngx_http_internal_redirect_module \ http/ngx_http_js_module \ http/ngx_http_keyval_module \ http/ngx_http_limit_conn_module \ @@ -94,6 +96,7 @@ REFS = \ http/ngx_http_userid_module \ http/ngx_http_uwsgi_module \ http/ngx_http_v2_module \ + http/ngx_http_v3_module \ http/ngx_http_xslt_module \ mail/ngx_mail_auth_http_module \ mail/ngx_mail_core_module \ @@ -112,6 +115,8 @@ REFS = \ stream/ngx_stream_limit_conn_module \ stream/ngx_stream_log_module \ stream/ngx_stream_map_module \ + stream/ngx_stream_mqtt_filter_module \ + stream/ngx_stream_mqtt_preread_module \ stream/ngx_stream_proxy_module \ stream/ngx_stream_proxy_protocol_vendor_module \ stream/ngx_stream_realip_module \ @@ -125,6 +130,7 @@ REFS = \ stream/ngx_stream_zone_sync_module \ stream/stream_processing \ ngx_google_perftools_module \ + ngx_otel_module \ dev/development_guide \ njs/index \ njs/changes \
--- a/xml/en/docs/configure.xml +++ b/xml/en/docs/configure.xml @@ -239,6 +239,24 @@ This module is not built by default. </tag-desc> <tag-name> +<literal>--with-http_v3_module</literal> +</tag-name> +<tag-desc> +enables building a module that provides support for +<link doc="http/ngx_http_v3_module.xml">HTTP/3</link>. +This module is not built by default. +An SSL library that provides HTTP/3 support +is recommended to build and run this module, such as +<link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>, +<link url="https://www.libressl.org">LibreSSL</link>, or +<link url="https://github.com/quictls/openssl">QuicTLS</link>. +Otherwise, if using the OpenSSL library, +OpenSSL compatibility layer will be used +that does not support QUIC +<link doc="http/ngx_http_ssl_module.xml" id="ssl_early_data">early data</link>. +</tag-desc> + +<tag-name> <literal>--with-http_realip_module</literal> </tag-name> <tag-desc>
--- a/xml/en/docs/http/ngx_http_api_module.xml +++ b/xml/en/docs/http/ngx_http_api_module.xml @@ -208,6 +208,11 @@ redirect</link> happens during request p <list type="bullet"> <listitem> +Detailed failure counters were added to SSL statistics +in <link id="api_version">version</link> 8 (1.23.2). +</listitem> + +<listitem> The <literal>ssl</literal> data for each HTTP <link id="def_nginx_http_upstream">upstream</link>, @@ -215,7 +220,7 @@ for each HTTP and stream <link id="def_nginx_stream_upstream">upstream</link>, <link id="def_nginx_stream_server_zone">server zone</link>, -were added in <link id="api_version">version</link> 8. +were added in <link id="api_version">version</link> 8 (1.21.6). </listitem> <listitem> @@ -3400,7 +3405,7 @@ The ID of the HTTP upstream server. The <literal>server</literal> (<literal>string</literal>) </tag-name> <tag-desc> -Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#address">address</link> parameter of the HTTP upstream server. When adding a server, it is possible to specify it as a domain name. In this case, changes of the IP addresses that correspond to a domain name will be monitored and automatically applied to the upstream configuration without the need of restarting nginx. This requires the <link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver">resolver</link> directive in the “<literal>http</literal>” block. See also the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#resolve">resolve</link> parameter of the HTTP upstream server. +Same as the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">address</link> parameter of the HTTP upstream server. When adding a server, it is possible to specify it as a domain name. In this case, changes of the IP addresses that correspond to a domain name will be monitored and automatically applied to the upstream configuration without the need of restarting nginx. This requires the <link url="https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver">resolver</link> directive in the “<literal>http</literal>” block. See also the <link url="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#resolve">resolve</link> parameter of the HTTP upstream server. </tag-desc> <tag-name> <literal>service</literal> (<literal>string</literal>)
--- a/xml/en/docs/http/ngx_http_api_module_head.xml +++ b/xml/en/docs/http/ngx_http_api_module_head.xml @@ -208,6 +208,11 @@ redirect</link> happens during request p <list type="bullet"> <listitem> +Detailed failure counters were added to SSL statistics +in <link id="api_version">version</link> 8 (1.23.2). +</listitem> + +<listitem> The <literal>ssl</literal> data for each HTTP <link id="def_nginx_http_upstream">upstream</link>, @@ -215,7 +220,7 @@ for each HTTP and stream <link id="def_nginx_stream_upstream">upstream</link>, <link id="def_nginx_stream_server_zone">server zone</link>, -were added in <link id="api_version">version</link> 8. +were added in <link id="api_version">version</link> 8 (1.21.6). </listitem> <listitem>
--- a/xml/en/docs/http/ngx_http_core_module.xml +++ b/xml/en/docs/http/ngx_http_core_module.xml @@ -855,6 +855,7 @@ Internal requests are the following: requests redirected by the <link id="error_page"/>, <link doc="ngx_http_index_module.xml" id="index"/>, +<link doc="ngx_http_internal_redirect_module.xml" id="internal_redirect"/>, <link doc="ngx_http_random_index_module.xml" id="random_index"/>, and <link id="try_files"/> directives; </listitem> @@ -1270,7 +1271,9 @@ The “wait-read-ignore” cycle is repeated, but no longer than specified by the <value>address</value>[:<value>port</value>] [<literal>default_server</literal>] [<literal>ssl</literal>] - [<literal>http2</literal> | <literal>spdy</literal>] + [<literal>http2</literal> | + <literal>quic</literal> | + <literal>spdy</literal>] [<literal>proxy_protocol</literal>] [<literal>setfib</literal>=<value>number</value>] [<literal>fastopen</literal>=<value>number</value>] @@ -1287,7 +1290,9 @@ The “wait-read-ignore” cycle is repeated, but no longer than specified by the <value>port</value> [<literal>default_server</literal>] [<literal>ssl</literal>] - [<literal>http2</literal> | <literal>spdy</literal>] + [<literal>http2</literal> | + <literal>quic</literal> | + <literal>spdy</literal>] [<literal>proxy_protocol</literal>] [<literal>setfib</literal>=<value>number</value>] [<literal>fastopen</literal>=<value>number</value>] @@ -1304,7 +1309,9 @@ The “wait-read-ignore” cycle is repeated, but no longer than specified by the <literal>unix:</literal><value>path</value> [<literal>default_server</literal>] [<literal>ssl</literal>] - [<literal>http2</literal> | <literal>spdy</literal>] + [<literal>http2</literal> | + <literal>quic</literal> | + <literal>spdy</literal>] [<literal>proxy_protocol</literal>] [<literal>backlog</literal>=<value>number</value>] [<literal>rcvbuf</literal>=<value>size</value>] @@ -1382,6 +1389,11 @@ specified as well, but nginx can also be connections without SSL. </para> +<para id="quic"> +The <literal>quic</literal> parameter (1.23.4) configures the port to accept +<link doc="ngx_http_v3_module.xml">QUIC</link> connections. +</para> + <para> The <literal>spdy</literal> parameter (1.3.15-1.9.4) allows accepting <link doc="ngx_http_spdy_module.xml">SPDY</link> connections on this port. @@ -1706,7 +1718,7 @@ the “<literal>/images/1.gif</literal>” request will match configuration D, and the “<literal>/documents/1.jpg</literal>” request will match configuration E. </para> -<para> +<para id="location_named"> The “<literal>@</literal>” prefix defines a named location. Such a location is not used for a regular request processing, but instead used for request redirection. @@ -3490,8 +3502,9 @@ port of the server which accepted a requ request protocol, usually “<literal>HTTP/1.0</literal>”, “<literal>HTTP/1.1</literal>”, +“<link doc="ngx_http_v2_module.xml">HTTP/2.0</link>”, or -“<link doc="ngx_http_v2_module.xml">HTTP/2.0</link>” +“<link doc="ngx_http_v3_module.xml">HTTP/3.0</link>” </tag-desc> <tag-name id="var_status"><var>$status</var></tag-name>
new file mode 100644 --- /dev/null +++ b/xml/en/docs/http/ngx_http_internal_redirect_module.xml @@ -0,0 +1,97 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_http_internal_redirect_module" + link="/en/docs/http/ngx_http_internal_redirect_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_http_internal_redirect_module</literal> module (1.23.4) allows +making an internal redirect. +In contrast to +<link doc="ngx_http_rewrite_module.xml">rewriting URIs</link>, +the redirection is made after checking +<link doc="ngx_http_limit_req_module.xml">request</link> and +<link doc="ngx_http_limit_conn_module.xml">connection</link> processing limits, +and <link doc="ngx_http_access_module.xml">access</link> limits. +</para> + +<para> +<note> +This module is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</note> +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +limit_req_zone $jwt_claim_sub zone=jwt_sub:10m rate=1r/s; + +server { + location / { + auth_jwt "realm"; + auth_jwt_key_file key.jwk; + + internal_redirect @rate_limited; + } + + location @rate_limited { + internal; + + limit_req zone=jwt_sub burst=10; + proxy_pass http://backend; + } +} +</example> +The example implements +<link url="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2">per-user</link> +<link doc="ngx_http_limit_req_module.xml">rate limiting</link>. +Implementation without <link id="internal_redirect">internal_redirect</link> +is vulnerable to DoS attacks by unsigned JWTs, as normally the +<link doc="ngx_http_limit_req_module.xml" id="limit_req">limit_req</link> +check is performed +<link doc="../dev/development_guide.xml" id="http_phases">before</link> +<link doc="ngx_http_auth_jwt_module.xml" id="auth_jwt">auth_jwt</link> check. +Using <link id="internal_redirect">internal_redirect</link> +allows reordering these checks. +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="internal_redirect"> +<syntax><value>uri</value></syntax> +<default/> +<context>server</context> +<context>location</context> + +<para> +Sets the URI for internal redirection of the request. +It is also possible to use a +<link doc="ngx_http_core_module.xml" id="location_named">named location</link> +instead of the URI. +The <value>uri</value> value can contain variables. +If the <value>uri</value> value is empty, +then the redirect will not be made. +</para> + +</directive> + +</section> + +</module>
--- a/xml/en/docs/http/ngx_http_limit_conn_module.xml +++ b/xml/en/docs/http/ngx_http_limit_conn_module.xml @@ -77,7 +77,8 @@ server { </example> allow only one connection per an IP address at a time. <note> -In HTTP/2 and SPDY, each concurrent request is considered a separate connection. +In HTTP/2 and HTTP/3, +each concurrent request is considered a separate connection. </note> </para>
new file mode 100644 --- /dev/null +++ b/xml/en/docs/http/ngx_http_v3_module.xml @@ -0,0 +1,353 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_http_v3_module" + link="/en/docs/http/ngx_http_v3_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_http_v3_module</literal> module (1.23.4) provides +experimental support for +<link url="https://datatracker.ietf.org/doc/html/rfc9114">HTTP/3</link>. +</para> + +<para> +This module is not built by default, it should be enabled with the +<link doc="../configure.xml"><literal>--with-http_v3_module</literal></link> +configuration parameter. +<note> +An SSL library that provides QUIC support +such as +<link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>, +<link url="https://www.libressl.org">LibreSSL</link>, or +<link url="https://github.com/quictls/openssl">QuicTLS</link> +is recommended to build and run this module. +Otherwise, +when using the <link url="https://openssl.org">OpenSSL</link> library, +OpenSSL compatibility layer will be used that does not support +<link doc="ngx_http_ssl_module.xml" id="ssl_early_data">early data</link>. +</note> +</para> + + +<para> +<note> +The module is available as +<literal>nginx-quic</literal> in +<link doc="../quic.xml" id="linux">prebult Linux packages</link>. +The module is also available as part of our +<commercial_version>commercial subscription</commercial_version> +in a separate <literal>nginx-plus-http3</literal> package. +</note> +</para> + +</section> + + +<section id="issues" name="Known Issues"> + +<para> +The module is experimental, caveat emptor applies. +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +http { + log_format quic '$remote_addr - $remote_user [$time_local] ' + '"$request" $status $body_bytes_sent ' + '"$http_referer" "$http_user_agent" "$http3"'; + + access_log logs/access.log quic; + + server { + # for better compatibility it's recommended + # to use the same port for http/3 and https + listen 8443 quic reuseport; + listen 8443 ssl; + + ssl_certificate certs/example.com.crt; + ssl_certificate_key certs/example.com.key; + + location / { + # used to advertise the availability of HTTP/3 + add_header Alt-Svc 'h3=":8443"; ma=86400'; + } + } +} +</example> +Note that accepting HTTP/3 connections over TLS requires +the TLSv1.3 protocol support, which is available since +<link url="http://www.openssl.org">OpenSSL</link> version 1.1.1. +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="http3"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> + +<para> +Enables +<link url="https://datatracker.ietf.org/doc/html/rfc9114">HTTP/3</link> +protocol negotiation. +</para> + +</directive> + + + <directive name="http3_hq"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> + +<para> +Enables HTTP/0.9 protocol negotiation +used in +<link url="https://github.com/marten-seemann/quic-interop-runner">QUIC +interoperability tests</link>. +</para> + +</directive> + + +<directive name="http3_max_concurrent_pushes"> +<syntax><value>number</value></syntax> +<default>10</default> +<context>http</context> +<context>server</context> + +<para> +Limits the maximum number of concurrent +<link id="http3_push">push</link> requests in a connection. +</para> + +</directive> + + +<directive name="http3_max_concurrent_streams"> +<syntax><value>number</value></syntax> +<default>128</default> +<context>http</context> +<context>server</context> + +<para> +Sets the maximum number of concurrent HTTP/3 request streams +in a connection. +</para> + +</directive> + + +<directive name="http3_push"> +<syntax><value>uri</value> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Pre-emptively sends +(<link url="https://datatracker.ietf.org/doc/html/rfc9114#name-server-push">pushes</link>) +a request to the specified <value>uri</value> +along with the response to the original request. +Only relative URIs with absolute path will be processed, +for example: +<example> +http3_push /static/css/main.css; +</example> +The <value>uri</value> value can contain variables. +</para> + +<para> +Several <literal>http3_push</literal> directives +can be specified on the same configuration level. +The <literal>off</literal> parameter cancels the effect +of the <literal>http3_push</literal> directives +inherited from the previous configuration level. +</para> + +</directive> + + +<directive name="http3_push_preload"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Enables automatic conversion of +<link url="https://www.w3.org/TR/preload/#server-push-http-3">preload +links</link> +specified in the <header>Link</header> response header fields into +<link url="https://datatracker.ietf.org/doc/html/rfc9114#name-server-push">push</link> +requests. +</para> + +</directive> + + +<directive name="http3_stream_buffer_size"> +<syntax><value>size</value></syntax> +<default>64k</default> +<context>http</context> +<context>server</context> + +<para> +Sets the size of the buffer used for reading and writing of the +QUIC streams. +</para> + +</directive> + + +<directive name="quic_active_connection_id_limit"> +<syntax><value>number</value></syntax> +<default>2</default> +<context>http</context> +<context>server</context> + +<para> +Sets the +QUIC <literal>active_connection_id_limit</literal> transport parameter value. +This is the maximum number of client connection IDs +which can be stored on the server. +</para> + +</directive> + + +<directive name="quic_bpf"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>main</context> + +<para> +Enables routing of QUIC packets using +<link url="https://ebpf.io/">eBPF</link>. +When enabled, this allows supporting QUIC connection migration. +</para> + +<para> +<note> +The directive is only supported on Linux 5.7+. +</note> +</para> + +</directive> + + +<directive name="quic_gso"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> + +<para> +Enables sending in optimized batch mode +using segmentation offloading. +</para> + +<para> +<note> +Optimized sending is supported only on Linux +featuring <literal>UDP_SEGMENT</literal>. +</note> +</para> + +</directive> + + +<directive name="quic_host_key"> +<syntax><value>file</value></syntax> +<default/> +<context>http</context> +<context>server</context> + +<para> +Sets a <value>file</value> with the secret key used to encrypt +stateless reset and address validation tokens. +By default, a random key is generated on each reload. +Tokens generated with old keys are not accepted. +</para> + +</directive> + + +<directive name="quic_mtu"> +<syntax><value>size</value></syntax> +<default>65527</default> +<context>http</context> +<context>server</context> + +<para> +Sets the +QUIC <literal>max_udp_payload_size</literal> transport parameter value. +This is the maximum UDP payload possible to receive. +</para> + +</directive> + + +<directive name="quic_retry"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> + +<para> +Enables the +<link url="https://datatracker.ietf.org/doc/html/rfc9000#name-address-validation">QUIC +Address Validation</link> feature. +This includes sending a new token in a <literal>Retry</literal> packet +or a <literal>NEW_TOKEN</literal> frame +and +validating a token received in the <literal>Initial</literal> packet. +</para> + +</directive> + +</section> + + +<section id="variables" name="Embedded Variables"> + +<para> +The <literal>ngx_http_v3_module</literal> module +supports the following embedded variables: +<list type="tag" compact="no"> + +<tag-name id="var_http3"><var>$http3</var></tag-name> +<tag-desc> +negotiated protocol identifier: +“<literal>h3</literal>” for HTTP/3 connections, +“<literal>hq</literal>” for hq connections, +or an empty string otherwise. +</tag-desc> + +</list> +</para> + +</section> + +</module>
--- a/xml/en/docs/index.xml +++ b/xml/en/docs/index.xml @@ -65,6 +65,10 @@ <link doc="windows.xml"/> </listitem> +<listitem> +<link doc="quic.xml"/> +</listitem> + </list> <list type="bullet"> @@ -325,6 +329,11 @@ ngx_http_index_module</link> </listitem> <listitem> +<link doc="http/ngx_http_internal_redirect_module.xml"> +ngx_http_internal_redirect_module</link> +</listitem> + +<listitem> <link doc="http/ngx_http_js_module.xml"> ngx_http_js_module</link> </listitem> @@ -490,6 +499,11 @@ ngx_http_v2_module</link> </listitem> <listitem> +<link doc="http/ngx_http_v3_module.xml"> +ngx_http_v3_module</link> +</listitem> + +<listitem> <link doc="http/ngx_http_xslt_module.xml"> ngx_http_xslt_module</link> </listitem> @@ -592,6 +606,16 @@ ngx_stream_map_module</link> </listitem> <listitem> +<link doc="stream/ngx_stream_mqtt_preread_module.xml"> +ngx_stream_mqtt_preread_module</link> +</listitem> + +<listitem> +<link doc="stream/ngx_stream_mqtt_filter_module.xml"> +ngx_stream_mqtt_filter_module</link> +</listitem> + +<listitem> <link doc="stream/ngx_stream_proxy_module.xml"> ngx_stream_proxy_module</link> </listitem> @@ -657,6 +681,11 @@ ngx_stream_zone_sync_module</link> ngx_google_perftools_module</link> </listitem> +<listitem> +<link doc="ngx_otel_module.xml"> +ngx_otel_module</link> +</listitem> + </list> </para>
new file mode 100644 --- /dev/null +++ b/xml/en/docs/ngx_otel_module.xml @@ -0,0 +1,347 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../dtd/module.dtd"> + +<module name="Module ngx_otel_module" + link="/en/docs/ngx_otel_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_otel_module</literal> module (1.23.4) provides +<link url="https://opentelemetry.io">OpenTelemetry</link> +distributed tracing support. +The module supports +<link url="https://w3c.github.io/trace-context">W3C</link> +context propagation and OTLP/gRPC export protocol. +</para> + +<para> +<note> +This module is available as part of our +<commercial_version>commercial subscription</commercial_version> +in <literal>nginx-plus-module-otel</literal> package. +After installation, the module can be loaded +<link doc="../ngx_core_module.xml" id="load_module">dynamically</link>. +</note> +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +load_module modules/ngx_otel_module.so; + +events { +} + +http { + + otel_exporter { + endpoint localhost:4317; + } + + server { + listen 127.0.0.1:8080; + + location / { + otel_trace on; + otel_trace_context inject; + + proxy_pass http://backend; + } + } +} +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="otel_exporter"> +<syntax block="yes"/> +<default/> +<context>http</context> + +<para> +Specifies OTel data export parameters: + +<list type="tag"> + +<tag-name id="endpoint"><literal>endpoint</literal></tag-name> +<tag-desc> +the address of OTLP/gRPC endpoint that will accept telemetry data. +</tag-desc> + +<tag-name id="interval"><literal>interval</literal></tag-name> +<tag-desc> +the maximum interval between two exports, +by default is <literal>5</literal> seconds. +</tag-desc> + +<tag-name id="batch_size"><literal>batch_size</literal></tag-name> +<tag-desc> +the maximum number of spans to be sent in one batch per worker, +by default is <literal>512</literal>. +</tag-desc> + +<tag-name id="batch_count"><literal>batch_count</literal></tag-name> +<tag-desc> +the number of pending batches per worker, +spans exceeding the limit are dropped, +by default is <literal>4</literal>. +</tag-desc> + +</list> +Example: +<example> +otel_exporter { + endpoint localhost:4317; + interval 5s; + batch_size 512; + batch_count 4; +} +</example> +</para> + +</directive> + + +<directive name="otel_service_name"> +<syntax><value>name</value></syntax> +<default>unknown_service:nginx</default> +<context>http</context> + +<para> +Sets the +“<link url="https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/#service"><literal>service.name</literal></link>” +attribute of the OTel resource. +</para> + +</directive> + + +<directive name="otel_trace"> +<syntax><literal>on</literal> | + <literal>off</literal> | + <literal>$variable</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Enables or disables OpenTelemetry tracing. +The directive can also be enabled by specifying a variable: +<example> +split_clients "$otel_trace_id" $ratio_sampler { + 10% on; + * off; +} + +server { + location / { + otel_trace $ratio_sampler; + otel_trace_context inject; + proxy_pass http://backend; + } +} +</example> +</para> + +</directive> + + +<directive name="otel_trace_context"> +<syntax><literal>extract</literal> | + <literal>inject</literal> | + <literal>propagate</literal> | + <literal>ignore</literal></syntax> +<default>ignore</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Specifies how to propagate +<link url="https://www.w3.org/TR/trace-context/#design-overview">traceparent/tracestate</link> headers: + +<list type="tag"> + +<tag-name id="extract"><literal>extract</literal></tag-name> +<tag-desc> +uses an existing trace context from the request, +so that the identifiers of +a <link id="var_otel_trace_id">trace</link> and +the <link id="var_otel_parent_id">parent span</link> +are inherited from the incoming request. +</tag-desc> + +<tag-name id="inject"><literal>inject</literal></tag-name> +<tag-desc> +adds a new context to the request, overwriting existing headers, if any. +</tag-desc> + +<tag-name id="propagate"><literal>propagate</literal></tag-name> +<tag-desc> +updates the existing context +(combines <link id="extract"/> and <link id="inject"/>). +</tag-desc> + +<tag-name id="ignore"><literal>ignore</literal></tag-name> +<tag-desc> +skips context headers processing. +</tag-desc> + +</list> +</para> + +</directive> + + +<directive name="otel_span_name"> +<syntax><value>name</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Defines the name of the OTel +<link url="https://opentelemetry.io/docs/concepts/observability-primer/#spans">span</link>. +By default, it is a name of the location for a request. +The name can contain variables. +</para> + +</directive> + + +<directive name="otel_span_attr"> +<syntax><value>name</value> <value>value</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Adds a custom OTel span attribute. +The value can contain variables. +</para> + +</directive> + +</section> + + +<section id="span" name="Default span attributes"> + +<para> +The following <link url="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md">span attributes</link> +are added automatically: + +<list type="bullet"> + +<listitem> +<literal>http.method</literal> +</listitem> + +<listitem> +<literal>http.target</literal> +</listitem> + +<listitem> +<literal>http.route</literal> +</listitem> + +<listitem> +<literal>http.scheme</literal> +</listitem> + +<listitem> +<literal>http.flavor</literal> +</listitem> + +<listitem> +<literal>http.user_agent</literal> +</listitem> + +<listitem> +<literal>http.request_content_length</literal> +</listitem> + +<listitem> +<literal>http.response_content_length</literal> +</listitem> + +<listitem> +<literal>http.status_code</literal> +</listitem> + +<listitem> +<literal>net.host.name</literal> +</listitem> + +<listitem> +<literal>net.host.port</literal> +</listitem> + +<listitem> +<literal>net.sock.peer.addr</literal> +</listitem> + +<listitem> +<literal>net.sock.peer.port</literal> +</listitem> + +</list> +</para> + +</section> + + +<section id="variables" name="Embedded Variables"> + +<para> +<list type="tag"> + +<tag-name id="var_otel_trace_id"><var>$otel_trace_id</var></tag-name> +<tag-desc> +the identifier of the trace the current span belongs to, +for example, <literal>56552bc4daa3bf39c08362527e1dd6c4</literal> +</tag-desc> + +<tag-name id="var_otel_span_id"><var>$otel_span_id</var></tag-name> +<tag-desc> +the identifier of the current span, +for example, <literal>4c0b8531ec38ca59</literal> +</tag-desc> + +<tag-name id="var_otel_parent_id"><var>$otel_parent_id</var></tag-name> +<tag-desc> +the identifier of the parent span, +for example, <literal>dc94d281b0f884ea</literal> +</tag-desc> + +<tag-name id="var_otel_parent_sampled"><var>$otel_parent_sampled</var></tag-name> +<tag-desc> +the “<literal>sampled</literal>” flag of the parent span, +can be “<literal>1</literal>” or “<literal>0</literal>” +</tag-desc> + +</list> +</para> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/en/docs/quic.xml @@ -0,0 +1,415 @@ +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> + +<article name="Support for QUIC and HTTP/3" + link="/en/docs/quic.html" + lang="en" + rev="1"> + +<section> + +<para> +<link url="https://datatracker.ietf.org/doc/html/rfc9000">QUIC</link> +and +<link url="https://datatracker.ietf.org/doc/html/rfc9114">HTTP/3</link> +protocols are supported since 1.23.4 and are available +as a separate <literal>nginx-quic</literal> +<link id="linux">prebult Linux package</link> +or as part of our +<commercial_version>commercial subscription</commercial_version> +in a separate <literal>nginx-plus-http3</literal> package. +</para> + +<para> +<note> +The QUIC and HTTP/3 support is experimental, caveat emptor applies. +</note> +</para> + +</section> + + +<section id="linux" name="Installation on Linux"> + +<para> +For Linux, <literal>nginx-quic</literal> packages +from nginx.org can be used. +The packages +are available for the following Linux distributions and +versions: +<list type="bullet"> + +<listitem> +<link id="rhel">RHEL 9 and derivatives</link>: amd64, arm64 +</listitem> + +<listitem> +<link id="rhel">Ubuntu 22.04</link>: amd64, arm64 +</listitem> + +</list> +</para> + +<para> +The <literal>nginx-quic</literal> packages are dynamically linked with the +<link url="https://github.com/quictls/openssl">QuicTLS</link> library. +It will be installed as a runtime dependency +alongside system-wide OpenSSL packages. +QuicTLS differs from operating system-provided OpenSSL package in the following: +<list type="bullet"> + +<listitem> +does not follow system-wide crypto policies +</listitem> + +<listitem> +does not have distribution-specific patches applied +</listitem> + +<listitem> +uses configuration from <literal>/etc/pki/quictls</literal> (RHEL9) +or <literal>/etc/quictls</literal> (Ubuntu 22.04) +</listitem> + +</list> +</para> + +<para> +The <literal>nginx-quic</literal> packages +cannot be installed alongside nginx or nginx-plus packages. +</para> + +<para> +Please back up your configuration files +before installing <literal>nginx-quic</literal>: +<programlisting> +sudo cp -a /etc/nginx /etc/nginx-quic-backup +</programlisting> +</para> + + +<section name="RHEL" id="rhel"> + +<para> +The <literal>nginx-quic</literal> package and be installed on +Red Hat Enterprise Linux and its derivatives such as +CentOS, Oracle Linux, Rocky Linux, AlmaLinux. +</para> + +<para> +Install the prerequisites: +<programlisting> +sudo dnf install yum-utils +</programlisting> + +To set up the yum repository, create the file named +<path>/etc/yum.repos.d/nginx-quic.repo </path> +with the following contents: + +<programlisting> +[nginx-quic] +name=nginx-quic repo +baseurl=https://packages.nginx.org/nginx-quic/rhel/9/$basearch/ +gpgcheck=1 +enabled=1 +gpgkey=https://nginx.org/keys/nginx_signing.key +</programlisting> + +To install nginx-quic, run the following commands: +<programlisting> +sudo dnf install nginx-quic +</programlisting> + +When prompted to accept the GPG key, verify that the fingerprint matches +<command>573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62</command>, +and if so, accept it. +</para> + +</section> + + +<section name="Ubuntu" id="ubuntu"> + +<para> +Install the prerequisites: +<programlisting> +sudo apt update && sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring +</programlisting> +</para> + +<para> +Import an official nginx signing key so apt could verify the packages +authenticity. +Fetch the key: +<programlisting> +curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \ + | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null +</programlisting> + +To set up the apt repository for nginx-quic packages, run the following command: +<programlisting> +echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ + https://packages.nginx.org/nginx-quic/ubuntu `lsb_release -cs` nginx-quic" \ + | sudo tee /etc/apt/sources.list.d/nginx-quic.list +</programlisting> +</para> + +<para> +To install nginx-quic, run the following commands: +<programlisting> +sudo apt update +sudo apt install nginx-quic +</programlisting> +</para> + +</section> + +</section> + + +<section id="building" name="Building from sources"> + +<para> +The build is configured using the <command>configure</command> command. +Please refer to <link doc="configure.xml"/> for details. +</para> + +<para> +When configuring nginx, it is possible to enable QUIC and HTTP/3 +using the following configuration options: + +<list type="tag"> + +<tag-name> +<literal>--with-http_v3_module</literal><br/> +</tag-name> +<tag-desc> +enables QUIC and HTTP/3. +</tag-desc> + +</list> +</para> + +<para> +An SSL library that provides QUIC support is recommended to build nginx, such as +<link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>, +<link url="https://www.libressl.org">LibreSSL</link>, or +<link url="https://github.com/quictls/openssl">QuicTLS</link>. +Otherwise, the <link url="https://openssl.org">OpenSSL</link> +compatibility layer will be used that does not support +<link doc="http/ngx_http_ssl_module.xml" id="ssl_early_data">early data</link>. +</para> + +<para> +Use the following command to configure nginx with +<link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>: +<programlisting> +./auto/configure --with-debug --with-http_v3_module \ + --with-cc-opt="-I../boringssl/include" \ + --with-ld-opt="-L../boringssl/build/ssl \ + -L../boringssl/build/crypto" +</programlisting> +</para> + +<para> +Alternatively, nginx can be configured with +<link url="https://github.com/quictls/openssl">QuicTLS</link>: +<programlisting> +./auto/configure --with-debug --with-http_v3_module \ + --with-cc-opt="-I../quictls/build/include" \ + --with-ld-opt="-L../quictls/build/lib" +</programlisting> +</para> + +<para> +Alternatively, nginx can be configured with a modern version of +<link url="https://www.libressl.org">LibreSSL</link>: +<programlisting> +./auto/configure --with-debug --with-http_v3_module \ + --with-cc-opt="-I../libressl/build/include" \ + --with-ld-opt="-L../libressl/build/lib" +</programlisting> +</para> + +<para> +After configuration, +nginx is compiled and installed using <command>make</command>. +</para> + +</section> + + +<section id="configuration" name="Configuration"> + +<para> +The <link doc="http/ngx_http_core_module.xml" id="listen"/> directive in +<link doc="http/ngx_http_core_module.xml">ngx_http_core_module</link> +module got a new parameter +<link doc="http/ngx_http_core_module.xml" id="quic">quic</link> +which enables HTTP/3 over QUIC on the specified port. +</para> + +<para> +Along with the <literal>quic</literal> parameter +it is also possible to specify the +<link doc="http/ngx_http_core_module.xml" id="reuseport">reuseport</link> +parameter to make it work properly with multiple workers. +</para> + +<para> +To <link doc="http/ngx_http_v3_module.xml" id="quic_retry">enable</link> +address validation: +<programlisting> +quic_retry on; +</programlisting> + +To <link doc="http/ngx_http_ssl_module.xml" id="ssl_early_data">enable</link> +0-RTT: +<programlisting> +ssl_early_data on; +</programlisting> + +To <link doc="http/ngx_http_v3_module.xml" id="quic_gso">enable</link> +GSO (Generic Segmentation Offloading): +<programlisting> +quic_gso on; +</programlisting> + +To <link doc="http/ngx_http_v3_module.xml" id="quic_mtu">limit</link> +maximum UDP payload size on receive path: +<programlisting> +quic_mtu <size>; +</programlisting> + +To <link doc="http/ngx_http_v3_module.xml" id="quic_host_key">set</link> +host key for various tokens: +<programlisting> +quic_host_key <filename>; +</programlisting> + +</para> + +<para> +QUIC requires TLSv1.3 protocol version which is enabled by default +in the <link doc="http/ngx_http_ssl_module.xml" id="ssl_protocols"/> directive. +</para> + +<para> +By default, +<link url="http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf">GSO Linux-specific optimization</link> +is disabled. +Enable it in case a corresponding network interface is configured +to support GSO. +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +http { + log_format quic '$remote_addr - $remote_user [$time_local] ' + '"$request" $status $body_bytes_sent ' + '"$http_referer" "$http_user_agent" "$http3"'; + + access_log logs/access.log quic; + + server { + # for better compatibility it's recommended + # to use the same port for quic and https + listen 8443 quic reuseport; + listen 8443 ssl; + + ssl_certificate certs/example.com.crt; + ssl_certificate_key certs/example.com.key; + + location / { + # required for browsers to direct them into quic port + add_header Alt-Svc 'h3=":8443"; ma=86400'; + } + } +} +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<para> +For the list of directives, please refer to +<link doc="http/ngx_http_v3_module.xml">ngx_http_v3_module</link> +module documentation. +</para> + +</section> + + +<section id="troubleshooting " name="Troubleshooting"> + +<para> +Tips that may help to identify problems: +<list type="bullet"> + +<listitem> +Ensure nginx is built with the proper SSL library that supports QUIC. +</listitem> + +<listitem> +Ensure nginx is using the proper SSL library in runtime +(the <literal>nginx -V</literal> shows what it is currently used). +</listitem> + +<listitem> +Ensure a client is actually sending requests over QUIC +(see the <link id="clients">Clients</link> section +for information about browsers and cache). +We recommend starting with a simple console client such as +<link url="https://nghttp2.org/ngtcp2">ngtcp2</link> +to ensure the server is configured properly before trying +with real browsers that may be quite picky with certificates. +</listitem> + +<listitem> +Build nginx with <link doc="debugging_log.xml">debug support</link> +and check the debug log. +It should contain all details about the connection and why it failed. +All related messages contain the “<literal>quic</literal>” prefix +and can be easily filtered out. +</listitem> + +<listitem> +For a deeper investigation, please enable additional debugging in +<literal>src/event/quic/ngx_event_quic_connection.h</literal>: + +<para> +<example> +#define NGX_QUIC_DEBUG_PACKETS +#define NGX_QUIC_DEBUG_FRAMES +#define NGX_QUIC_DEBUG_ALLOC +#define NGX_QUIC_DEBUG_CRYPTO +</example> +</para> +</listitem> + +</list> +</para> + +</section> + + +<section id="contributing" name="Contributing"> + +<para> +Please refer to <link doc="contributing_changes.xml"/>. +</para> + +</section> + +</article>
new file mode 100644 --- /dev/null +++ b/xml/en/docs/stream/ngx_stream_mqtt_filter_module.xml @@ -0,0 +1,108 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_stream_mqtt_filter_module" + link="/en/docs/http/ngx_stream_mqtt_filter_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_stream_mqtt_filter_module</literal> module (1.23.4) provides +support for Message Queuing Telemetry Transport protocol (MQTT) versions +<link url="https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html">3.1.1</link> +and +<link url="https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html">5.0</link>. +</para> + +<para> +<note> +This module is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</note> +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +listen 127.0.0.1:18883; +proxy_pass backend; +proxy_buffer_size 16k; + +mqtt on; +mqtt_set_connect clientid "$client"; +mqtt_set_connect username "$name"; +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="mqtt"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>stream</context> +<context>server</context> + +<para> +Enables the MQTT protocol for the given virtual server. +</para> + +</directive> + +<directive name="mqtt_rewrite_buffer_size"> +<syntax><value>size</value></syntax> +<default>4k|8k</default> +<context>server</context> + +<para> +Sets the <value>size</value> of the buffer +used for writing a modified message. +By default, the buffer size is equal to one memory page. +This is either 4K or 8K, depending on a platform. +It can be made smaller, however. +</para> + +</directive> + +<directive name="mqtt_set_connect"> +<syntax><literal>field</literal> <value>value</value></syntax> +<default/> +<context>server</context> + +<para> +Sets the message <literal>field</literal> +to the given <literal>value</literal> for CONNECT message. +The following fields are supported: +<literal>clientid</literal>, +<literal>username</literal>, and +<literal>password</literal>. +The value can contain text, variables, and their combination. +</para> + +<para> +Several <literal>mqtt_set_connect</literal> directives +can be specified on the same level: +<example> +mqtt_set_connect clientid "$client"; +mqtt_set_connect username "$name"; +</example> +</para> + +</directive> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/en/docs/stream/ngx_stream_mqtt_preread_module.xml @@ -0,0 +1,86 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_stream_mqtt_preread_module" + link="/en/docs/http/ngx_stream_mqtt_preread_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_stream_mqtt_preread_module</literal> module (1.23.4) allows +extracting information from the CONNECT message +of the Message Queuing Telemetry Transport protocol (MQTT) versions +<link url="https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html">3.1.1</link> +and +<link url="https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html">5.0</link>, +for example, a username or a client ID. +</para> + +<para> +<note> +This module is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</note> +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +mqtt_preread on; +return $mqtt_preread_clientid; +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="mqtt_preread"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>stream</context> +<context>server</context> + +<para> +Enables extracting information from the MQTT CONNECT message at +the <link doc="stream_processing.xml" id="preread_phase">preread</link> phase. +</para> + +</directive> + +</section> + + +<section id="variables" name="Embedded Variables"> + +<para> +<list type="tag"> + +<tag-name id="var_mqtt_preread_clientid"><var>$mqtt_preread_clientid</var></tag-name> +<tag-desc> +the <literal>clientid</literal> value from the CONNECT message +</tag-desc> + +<tag-name id="var_mqtt_preread_username"><var>$mqtt_preread_username</var></tag-name> +<tag-desc> +the <literal>username</literal> value from the CONNECT message +</tag-desc> + +</list> +</para> + +</section> + +</module>
--- a/xml/ru/GNUmakefile +++ b/xml/ru/GNUmakefile @@ -49,6 +49,7 @@ REFS = \ http/ngx_http_hls_module \ http/ngx_http_image_filter_module \ http/ngx_http_index_module \ + http/ngx_http_internal_redirect_module \ http/ngx_http_js_module \ http/ngx_http_limit_conn_module \ http/ngx_http_limit_req_module \ @@ -81,6 +82,7 @@ REFS = \ http/ngx_http_userid_module \ http/ngx_http_uwsgi_module \ http/ngx_http_v2_module \ + http/ngx_http_v3_module \ http/ngx_http_xslt_module \ mail/ngx_mail_auth_http_module \ mail/ngx_mail_core_module \ @@ -98,6 +100,8 @@ REFS = \ stream/ngx_stream_limit_conn_module \ stream/ngx_stream_log_module \ stream/ngx_stream_map_module \ + stream/ngx_stream_mqtt_filter_module \ + stream/ngx_stream_mqtt_preread_module \ stream/ngx_stream_proxy_module \ stream/ngx_stream_proxy_protocol_vendor_module \ stream/ngx_stream_realip_module \
--- a/xml/ru/docs/configure.xml +++ b/xml/ru/docs/configure.xml @@ -237,6 +237,25 @@ </tag-desc> <tag-name> +<literal>--with-http_v3_module</literal> +</tag-name> +<tag-desc> +разрешает сборку модуля для работы HTTP-сервера по протоколу +<link doc="http/ngx_http_v3_module.xml">HTTP/3</link>. +По умолчанию модуль не собирается. +Для сборки и работы этого модуля рекомендуется библиотека SSL с поддержкой HTTP/3, +например +<link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>, +<link url="https://www.libressl.org">LibreSSL</link> или +<link url="https://github.com/quictls/openssl">QuicTLS</link>. +Иначе, при использовании библиотеки OpenSSL, +будет использоваться OpenSSL compatibility layer, +в котором не поддерживается QUIC +<link doc="http/ngx_http_ssl_module.xml" id="ssl_early_data">early data</link>. + +</tag-desc> + +<tag-name> <literal>--with-http_realip_module</literal> </tag-name> <tag-desc>
--- a/xml/ru/docs/http/ngx_http_core_module.xml +++ b/xml/ru/docs/http/ngx_http_core_module.xml @@ -848,6 +848,7 @@ error_page 404 =301 http://example.com/n запросы, перенаправленные директивами <link id="error_page"/>, <link doc="ngx_http_index_module.xml" id="index"/>, +<link doc="ngx_http_internal_redirect_module.xml" id="internal_redirect"/>, <link doc="ngx_http_random_index_module.xml" id="random_index"/> и <link id="try_files"/>; </listitem> @@ -1264,7 +1265,9 @@ location /flv/ { <value>адрес</value>[:<value>порт</value>] [<literal>default_server</literal>] [<literal>ssl</literal>] - [<literal>http2</literal> | <literal>spdy</literal>] + [<literal>http2</literal> | + <literal>quic</literal> | + <literal>spdy</literal>] [<literal>proxy_protocol</literal>] [<literal>setfib</literal>=<value>число</value>] [<literal>fastopen</literal>=<value>число</value>] @@ -1281,7 +1284,9 @@ location /flv/ { <value>порт</value> [<literal>default_server</literal>] [<literal>ssl</literal>] - [<literal>http2</literal> | <literal>spdy</literal>] + [<literal>http2</literal> | + <literal>quic</literal> | + <literal>spdy</literal>] [<literal>proxy_protocol</literal>] [<literal>setfib</literal>=<value>число</value>] [<literal>fastopen</literal>=<value>число</value>] @@ -1298,7 +1303,9 @@ location /flv/ { <literal>unix:</literal><value>путь</value> [<literal>default_server</literal>] [<literal>ssl</literal>] - [<literal>http2</literal> | <literal>spdy</literal>] + [<literal>http2</literal> | + <literal>quic</literal> | + <literal>spdy</literal>] [<literal>proxy_protocol</literal>] [<literal>backlog</literal>=<value>число</value>] [<literal>rcvbuf</literal>=<value>размер</value>] @@ -1374,6 +1381,11 @@ id="single_http_https_server">конфигурацию</link> для сервера, HTTP/2-соединений без SSL. </para> +<para id="quic"> +Параметр <literal>quic</literal> (1.23.4) позволяет принимать на этом порту +<link doc="ngx_http_v3_module.xml">QUIC</link>-соединения. +</para> + <para> Параметр <literal>spdy</literal> (1.3.15-1.9.4) позволяет принимать на этом порту <link doc="ngx_http_spdy_module.xml">SPDY</link>-соединения. @@ -1701,7 +1713,7 @@ location ~* \.(gif|jpg|jpeg)$ { а для запроса “<literal>/documents/1.jpg</literal>” — конфигурация Д. </para> -<para> +<para id="location_named"> Префикс “<literal>@</literal>” задаёт именованный location. Такой location не используется при обычной обработке запросов, а предназначен только для перенаправления в него запросов. @@ -3481,9 +3493,10 @@ scgi_pass_request_body off</link> <tag-desc> протокол запроса, обычно “<literal>HTTP/1.0</literal>”, -“<literal>HTTP/1.1</literal>” +“<literal>HTTP/1.1</literal>”, +“<link doc="ngx_http_v2_module.xml">HTTP/2.0</link>” или -“<link doc="ngx_http_v2_module.xml">HTTP/2.0</link>” +“<link doc="ngx_http_v3_module.xml">HTTP/3.0</link>” </tag-desc> <tag-name id="var_status"><var>$status</var></tag-name>
new file mode 100644 --- /dev/null +++ b/xml/ru/docs/http/ngx_http_internal_redirect_module.xml @@ -0,0 +1,99 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Модуль ngx_http_internal_redirect_module" + link="/ru/docs/http/ngx_http_internal_redirect_module.html" + lang="ru" + rev="1"> + +<section id="summary"> + +<para> +Модуль <literal>ngx_http_internal_redirect_module</literal> (1.23.4) позволяет +осуществлять внутреннее перенаправление. +В отличие от +<link doc="ngx_http_rewrite_module.xml">изменения URI</link>, +перенаправление происходит после проверок ограничений +<link doc="ngx_http_limit_req_module.xml">скорости обработки запросов</link>, +<link doc="ngx_http_limit_conn_module.xml">числа соединений</link> +и <link doc="ngx_http_access_module.xml">доступа</link>. +</para> + +<para> +<note> +Модуль доступен как часть +<commercial_version>коммерческой подписки</commercial_version> +</note> +</para> + +</section> + + +<section id="example" name="Пример конфигурации"> + +<para> +<example> +limit_req_zone $jwt_claim_sub zone=jwt_sub:10m rate=1r/s; + +server { + location / { + auth_jwt "realm"; + auth_jwt_key_file key.jwk; + + internal_redirect @rate_limited; + } + + location @rate_limited { + internal; + + limit_req zone=jwt_sub burst=10; + proxy_pass http://backend; + } +} +</example> +В примере +<link doc="ngx_http_limit_req_module.xml">скорость обработки запросов</link> +ограничивается по +<link url="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2">идентификатору +клиента</link>. +Конфигурация без <link id="internal_redirect">internal_redirect</link> +может быть подвержена DoS-атакам при помощи неподписанных JWT, так как проверка +<link doc="ngx_http_limit_req_module.xml" id="limit_req">limit_req</link> +выполняется +<link doc="../dev/development_guide.xml" id="http_phases">перед</link> +проверкой +<link doc="ngx_http_auth_jwt_module.xml" id="auth_jwt">auth_jwt</link>. +Использование <link id="internal_redirect">internal_redirect</link> +позволяет изменить порядок этих проверок. +</para> + +</section> + + +<section id="directives" name="Директивы"> + +<directive name="internal_redirect"> +<syntax><value>uri</value></syntax> +<default/> +<context>server</context> +<context>location</context> + +<para> +Задаёт URI для внутреннего перенаправления запроса. +Вместо URI также можно использовать +<link doc="ngx_http_core_module.xml" id="location_named">именованный location</link>. +В значении <value>uri</value> можно использовать переменные. +Если значение <value>uri</value> пустое, +то перенаправление не осуществляется. +</para> + +</directive> + +</section> + +</module>
--- a/xml/ru/docs/http/ngx_http_limit_conn_module.xml +++ b/xml/ru/docs/http/ngx_http_limit_conn_module.xml @@ -76,7 +76,8 @@ server { разрешают одновременно обрабатывать не более одного соединения с одного IP-адреса. <note> -В HTTP/2 и SPDY каждый параллельный запрос считается отдельным соединением. +В HTTP/2 и HTTP/3 +каждый параллельный запрос считается отдельным соединением. </note> </para>
new file mode 100644 --- /dev/null +++ b/xml/ru/docs/http/ngx_http_v3_module.xml @@ -0,0 +1,352 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Модуль ngx_http_v3_module" + link="/ru/docs/http/ngx_http_v3_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +Модуль <literal>ngx_http_v3_module</literal> (1.23.4) обеспечивает +экспериментальную поддержку +<link url="https://datatracker.ietf.org/doc/html/rfc9114">HTTP/3</link>. +</para> + +<para> +По умолчанию этот модуль не собирается, его сборку необходимо +разрешить с помощью конфигурационного параметра +<link doc="../configure.xml"><literal>--with-http_v3_module</literal></link>. +<note> +Для сборки и работы этого модуля рекомендуется использовать +библиотеку SSL с поддержкой QUIC, например +<link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>, +<link url="https://www.libressl.org">LibreSSL</link>, +<link url="https://github.com/quictls/openssl">QuicTLS</link>. +Иначе, +при использовании библиотеки <link url="https://openssl.org">OpenSSL</link>, +будет использоваться OpenSSL compatibility layer, +в котором не поддерживается +<link doc="ngx_http_ssl_module.xml" id="ssl_early_data">early data</link>. +</note> +</para> + +<para> +<note> +Модуль доступен в виде +<link doc="../quic.xml" id="linux">готовых пакетов</link> +<literal>nginx-quic</literal> для Linux. +Модуль также доступен как часть +<commercial_version>коммерческой подписки</commercial_version> +в виде отдельного пакета <literal>nginx-plus-http3</literal>. + +</note> +</para> + +</section> + + +<section id="issues" name="Известные проблемы"> + +<para> +Модуль экспериментальный, поэтому возможно всё. +</para> + +</section> + + +<section id="example" name="Пример конфигурации"> + +<para> +<example> +http { + log_format quic '$remote_addr - $remote_user [$time_local] ' + '"$request" $status $body_bytes_sent ' + '"$http_referer" "$http_user_agent" "$http3"'; + + access_log logs/access.log quic; + + server { + # для лучшей совместимости рекомендуется + # использовать одинаковый порт для http/3 и https + listen 8443 quic reuseport; + listen 8443 ssl; + + ssl_certificate certs/example.com.crt; + ssl_certificate_key certs/example.com.key; + + location / { + # используется для объявления о поддержке http/3 + add_header Alt-Svc 'h3=":8443"; ma=86400'; + } + } +} +</example> +Чтобы принимать HTTP/3-соединения по TLS, необходимо +наличие поддержки протокола TLSv1.3, появившейся в +<link url="http://www.openssl.org">OpenSSL</link> версии 1.1.1. +</para> + +</section> + + +<section id="directives" name="Директивы"> + +<directive name="http3"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> + +<para> +Разрешает +согласование протокола +<link url="https://datatracker.ietf.org/doc/html/rfc9114">HTTP/3</link>. +</para> + +</directive> + + +<directive name="http3_hq"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> + +<para> +Разрешает согласование протокола HTTP/0.9, +используемого в +<link url="https://github.com/marten-seemann/quic-interop-runner">функциональных +тестах QUIC</link>. +</para> + +</directive> + + +<directive name="http3_max_concurrent_pushes"> +<syntax><value>число</value></syntax> +<default>10</default> +<context>http</context> +<context>server</context> + +<para> +Ограничивает максимальное число параллельных +<link id="http3_push">push</link>-запросов в соединении. +</para> + +</directive> + + +<directive name="http3_max_concurrent_streams"> +<syntax><value>число</value></syntax> +<default>128</default> +<context>http</context> +<context>server</context> + +<para> +Задаёт максимальное число параллельных HTTP/3-потоков +в соединении. +</para> + +</directive> + + +<directive name="http3_push"> +<syntax><value>uri</value> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Заблаговременно отправляет +(<link url="https://datatracker.ietf.org/doc/html/rfc9114#name-server-push">push</link>) запрос +к заданному <value>uri</value> +вместе с ответом на оригинальный запрос. +Будут обработаны только относительные URI с абсолютными путями, +например: +<example> +http3_push /static/css/main.css; +</example> +В значении <value>uri</value> допустимо использование переменных. +</para> + +<para> +На одном уровне конфигурации можно указать несколько +<literal>http3_push</literal> директив. +Параметр <literal>off</literal> отменяет действие +унаследованных с предыдущего уровня конфигурации +директив <literal>http3_push</literal>. +</para> + +</directive> + + +<directive name="http3_push_preload"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Разрешает автоматическое преобразование +<link url="https://www.w3.org/TR/preload/#server-push-http-3">preload +links</link>, +указанных в полях <header>Link</header> заголовка ответа, в +<link url="https://datatracker.ietf.org/doc/html/rfc9114#name-server-push">push</link>-запросы. +</para> + +</directive> + + +<directive name="http3_stream_buffer_size"> +<syntax><value>размер</value></syntax> +<default>64k</default> +<context>http</context> +<context>server</context> + +<para> +Задаёт размер буфера, используемого для чтения и записи +QUIC-потоков. +</para> + +</directive> + + +<directive name="quic_active_connection_id_limit"> +<syntax><value>число</value></syntax> +<default>2</default> +<context>http</context> +<context>server</context> + +<para> +Устанавливает +значение транспортного параметра QUIC <literal>active_connection_id_limit</literal>. +Это максимальное значение ID соединений, +возможное для хранения на сервере. +</para> + +</directive> + + +<directive name="quic_bpf"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>main</context> + +<para> +Разрешает маршрутизацию пакетов QUIC при помощи +<link url="https://ebpf.io/">eBPF</link>. +Если маршрутизация включена, то обеспечивается поддержка миграции QUIC-соединений. +</para> + +<para> +<note> +Директива поддерживается только на Linux 5.7+. +</note> +</para> + +</directive> + + +<directive name="quic_gso"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> + +<para> +Разрешает отправку оптимизированного пакетного режима +при помощи segmentation offloading. +</para> + +<para> +<note> +Оптимизированная отправка поддерживается только на Linux +с поддержкой <literal>UDP_SEGMENT</literal>. +</note> +</para> + +</directive> + + +<directive name="quic_host_key"> +<syntax><value>файл</value></syntax> +<default/> +<context>http</context> +<context>server</context> + +<para> +Задаёт <value>файл</value> с секретным ключом, применяемым при шифровании +stateless reset и address validation токенов. +По умолчанию создаётся случайный ключ при каждой перезагрузке. +Токены, созданные при помощи старых ключей, не принимаются. +</para> + +</directive> + + +<directive name="quic_mtu"> +<syntax><value>размер</value></syntax> +<default>65527</default> +<context>http</context> +<context>server</context> + +<para> +Устанавливает +значение транспортного параметра QUIC <literal>max_udp_payload_size</literal>. +Это максимально возможное значение для получения UDP payload. +</para> + +</directive> + + +<directive name="quic_retry"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> + +<para> +Разрешает функциональность +<link url="https://datatracker.ietf.org/doc/html/rfc9000#name-address-validation">QUIC +Address Validation</link>, +в том числе отправку нового токена в <literal>Retry</literal>-пакете +или <literal>NEW_TOKEN</literal> frame +и +валидацию токена, полученного в <literal>Initial</literal>-пакете. +</para> + +</directive> + +</section> + + +<section id="variables" name="Встроенные переменные"> + +<para> +Модуль <literal>ngx_http_v3_module</literal> +поддерживает следующие встроенные переменные: +<list type="tag" compact="no"> + +<tag-name id="var_http3"><var>$http3</var></tag-name> +<tag-desc> +согласованный идентификатор протокола: +“<literal>h3</literal>” для HTTP/3-соединений, +“<literal>hq</literal>” для hq-соединений, +либо пустая строка. +</tag-desc> + +</list> +</para> + +</section> + +</module>
--- a/xml/ru/docs/index.xml +++ b/xml/ru/docs/index.xml @@ -65,6 +65,10 @@ <link doc="windows.xml"/> </listitem> +<listitem> +<link doc="../../en/docs/quic.xml">Поддержка QUIC и HTTP/3</link> [en] +</listitem> + </list> <list type="bullet"> @@ -330,6 +334,11 @@ ngx_http_index_module</link> </listitem> <listitem> +<link doc="http/ngx_http_internal_redirect_module.xml"> +ngx_http_internal_redirect_module</link> +</listitem> + +<listitem> <link doc="http/ngx_http_js_module.xml"> ngx_http_js_module</link> </listitem> @@ -495,6 +504,12 @@ ngx_http_v2_module</link> </listitem> <listitem> +<link doc="http/ngx_http_v3_module.xml"> +ngx_http_v3_module</link> +</listitem> + + +<listitem> <link doc="http/ngx_http_xslt_module.xml"> ngx_http_xslt_module</link> </listitem> @@ -597,6 +612,16 @@ ngx_stream_map_module</link> </listitem> <listitem> +<link doc="stream/ngx_stream_mqtt_preread_module.xml"> +ngx_stream_mqtt_preread_module</link> +</listitem> + +<listitem> +<link doc="stream/ngx_stream_mqtt_filter_module.xml"> +ngx_stream_mqtt_filter_module</link> +</listitem> + +<listitem> <link doc="stream/ngx_stream_proxy_module.xml"> ngx_stream_proxy_module</link> </listitem> @@ -662,6 +687,11 @@ ngx_stream_zone_sync_module</link> [en] ngx_google_perftools_module</link> </listitem> +<listitem> +<link doc="ngx_otel_module.xml"> +ngx_otel_module [en]</link> +</listitem> + </list> </para>
new file mode 100644 --- /dev/null +++ b/xml/ru/docs/stream/ngx_stream_mqtt_filter_module.xml @@ -0,0 +1,109 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Модуль ngx_stream_mqtt_filter_module" + link="/ru/docs/http/ngx_stream_mqtt_filter_module.html" + lang="ru" + rev="1"> + +<section id="summary"> + +<para> +Модуль <literal>ngx_stream_mqtt_filter_module</literal> (1.23.4) обеспечивает +поддержку протокола Message Queuing Telemetry Transport (MQTT) +версий +<link url="https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html">3.1.1</link> +и +<link url="https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html">5.0</link>. +</para> + +<para> +<note> +Модуль доступен как часть +<commercial_version>коммерческой подписки</commercial_version>. +</note> +</para> + +</section> + + +<section id="example" name="Пример конфигурации"> + +<para> +<example> +listen 127.0.0.1:18883; +proxy_pass backend; +proxy_buffer_size 16k; + +mqtt on; +mqtt_set_connect clientid "$client"; +mqtt_set_connect username "$name"; +</example> +</para> + +</section> + + +<section id="directives" name="Директивы"> + +<directive name="mqtt"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>stream</context> +<context>server</context> + +<para> +Включает протокол MQTT для данного виртуального сервера. +</para> + +</directive> + +<directive name="mqtt_rewrite_buffer_size"> +<syntax><value>размер</value></syntax> +<default>4k|8k</default> +<context>server</context> + +<para> +Задаёт <value>размер</value> буфера, +в который будет записываться модифицированное сообщение. +По умолчанию размер одного буфера равен размеру страницы памяти. +В зависимости от платформы это или 4K, или 8K, +однако его можно сделать меньше. +</para> + +</directive> + +<directive name="mqtt_set_connect"> +<syntax><literal>поле</literal> <value>значение</value></syntax> +<default/> +<context>server</context> + +<para> +Устанавливает <literal>поле</literal> +в заданное <literal>значение</literal> для сообщения CONNECT. +Поддерживаются следующие поля: +<literal>clientid</literal>, +<literal>username</literal> и +<literal>password</literal>. +В качестве значения можно использовать текст, переменные и их комбинации. +</para> + +<para> +На одном уровне может быть указано +несколько директив <literal>mqtt_set_connect</literal>: +<example> +mqtt_set_connect clientid "$client"; +mqtt_set_connect username "$name"; +</example> +</para> + +</directive> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/ru/docs/stream/ngx_stream_mqtt_preread_module.xml @@ -0,0 +1,87 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Модуль ngx_stream_mqtt_preread_module" + link="/ru/docs/http/ngx_stream_mqtt_preread_module.html" + lang="ru" + rev="1"> + +<section id="summary"> + +<para> +Модуль <literal>ngx_stream_mqtt_preread_module</literal> (1.23.4) позволяет +извлекать информацию из сообщения CONNECT +протокола Message Queuing Telemetry Transport (MQTT) +версий +<link url="https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html">3.1.1</link> +и +<link url="https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html">5.0</link>, +например имя пользователя или ID клиента. +</para> + +<para> +<note> +Модуль доступен как часть +<commercial_version>коммерческой подписки</commercial_version>. +</note> +</para> + +</section> + + +<section id="example" name="Пример конфигурации"> + +<para> +<example> +mqtt_preread on; +return $mqtt_preread_clientid; +</example> +</para> + +</section> + + +<section id="directives" name="Директивы"> + +<directive name="mqtt_preread"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>stream</context> +<context>server</context> + +<para> +Разрешает извлечение информации из сообщения СONNECT во время фазы +<link doc="stream_processing.xml" id="preread_phase">предварительного чтения</link>. +</para> + +</directive> + +</section> + + +<section id="variables" name="Встроенные переменные"> + +<para> +<list type="tag"> + +<tag-name id="var_mqtt_preread_clientid"><var>$mqtt_preread_clientid</var></tag-name> +<tag-desc> +значение <literal>clientid</literal> из СONNECT-сообщения +</tag-desc> + +<tag-name id="var_mqtt_preread_username"><var>$mqtt_preread_username</var></tag-name> +<tag-desc> +значение <literal>username</literal> из СONNECT-сообщения +</tag-desc> + +</list> +</para> + +</section> + +</module>
--- a/yaml/nginx_api.yaml +++ b/yaml/nginx_api.yaml @@ -280,7 +280,7 @@ paths: - in: query name: fields type: string - description: Limits which fields of client HTTP requests statistics + description: Limits which fields of client HTTP requests statistics will be output. responses: '200': @@ -3573,7 +3573,7 @@ definitions: server: type: string description: Same as the - <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#address">address</a> + <a href="https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server">address</a> parameter of the HTTP upstream server. When adding a server, it is possible to specify it as a domain name. In this case, changes of the IP addresses