Mercurial > hg > nginx-site
diff xml/en/docs/http/ngx_http_v3_module.xml @ 2956:a85e4d126bc7
Updated docs for the upcoming NGINX Plus release.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 02 May 2023 11:39:21 +0100 |
parents | |
children | cebca5ba84d7 |
line wrap: on
line diff
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>