Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_v3_module.xml @ 2970:203f32f53734
Linux packages: removed Ubuntu 18.04 'bionic' due to EOL.
author | Konstantin Pavlov <thresh@nginx.com> |
---|---|
date | Wed, 31 May 2023 14:50:50 -0700 |
parents | 23eedf89fd5d |
children |
line wrap: on
line source
<?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="2"> <section id="summary"> <para> The <literal>ngx_http_v3_module</literal> module (1.25.0) 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" id="http_v3_module"><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> </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_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_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_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>