HTTP/3#

Provides HTTP/3 protocol support for client connections, as well as for connections with proxied servers configured using the following Proxy module directives:

When building from the source code, this module isn't built by default; it should be enabled with the ‑‑with‑http_v3_module build option.

In packages and images from our repositories, the module is included in the build.

Configuration 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';
        }
    }
}

Note

Note that accepting HTTP/3 connections over TLS requires the TLSv1.3 protocol support, which is available since OpenSSL version 1.1.1.

Also, the reuseport option can only be specified in one of the listen ... quic directives on a server. All other listen ... quic directives must be specified without it.

Directives#

http3#

Syntax

http3 on | off;

Default

http3 on;

Context

http, server

Enables HTTP/3 protocol negotiation.

http3_hq#

Syntax

http3_hq on | off;

Default

http3_hq off;

Context

http, server

Enables HTTP/0.9 protocol negotiation used in QUIC interoperability tests.

Warning

Enable this mode only to run specialized tests that explicitly require it.

http3_max_concurrent_streams#

Syntax

http3_max_concurrent_streams number;

Default

http3_max_concurrent_streams 128;

Context

http, server

Initializes HTTP/3 and QUIC settings and sets the maximum number of concurrent HTTP/3 request streams in a connection.

http3_max_table_capacity#

Syntax

http3_max_table_capacity number;

Default

http3_max_table_capacity 4096;

Context

http, server

Sets the dynamic table capacity for server connections.

Note

A similar proxy_http3_max_table_capacity directive does this for proxy connections. To avoid errors, dynamic table usage is disabled when proxying with caching is enabled.

http3_stream_buffer_size#

Syntax

http3_stream_buffer_size size;

Default

http3_stream_buffer_size 64k;

Context

http, server

Sets the size of the buffer used for reading and writing of the QUIC streams.

quic_active_connection_id_limit#

Syntax

quic_active_connection_id_limit number;

Default

quic_active_connection_id_limit 2;

Context

http, server

Sets the QUIC active_connection_id_limit transport parameter value. This is the maximum number of connection IDs that can be stored on the server.

quic_bpf#

Syntax

quic_bpf on | off;

Default

quic_bpf off;

Context

main

Enables routing of QUIC packets using eBPF. When enabled, this allows supporting QUIC connection migration.

Note

The directive is only supported on Linux 5.7+.

quic_gso#

Syntax

quic_gso on | off;

Default

quic_gso off;

Context

http, server

Enables sending in optimized batch mode using segmentation offloading.

Note

Optimized sending is supported only on Linux featuring UDP_SEGMENT.

quic_host_key#

Syntax

quic_host_key file;

Default

—

Context

http, server

Sets a file 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.

quic_retry#

Syntax

quic_retry on | off;

Default

quic_retry off;

Context

http, server

Enables the QUIC Address Validation feature. This includes sending a new token in a Retry packet or a NEW_TOKEN frame and validating a token received in the Initial packet.

Built-in Variables#

The http_v3 module supports the following built-in variables:

$http3#

negotiated protocol identifier:

h3

for HTTP/3 connections

hq

for hq connections

""

an empty string otherwise

$quic_connection#

QUIC connection serial number