<?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>