ngx_http_v3_module

Serve HTTP/3 over QUIC alongside HTTPS on the same port

compiled inBSD-2-Clausesource docs

Overview

ngx_http_v3_module provides experimental support for HTTP/3 (RFC 9114) over QUIC. A server accepts it through a listen socket with the quic parameter, and the docs recommend using the same port for HTTP/3 and HTTPS and advertising it to clients with an Alt-Svc response header.

QUIC needs a TLS library with QUIC support: upstream requires OpenSSL 1.1.1 or higher, 0-RTT needs OpenSSL 3.5.1 or higher (before 1.29.1 it could not be enabled with OpenSSL at all), and BoringSSL, LibreSSL or QuicTLS are the alternatives. The n.wtf build links OpenSSL statically, so the module works regardless of the system libssl. The $http3 variable reports h3 for HTTP/3 connections, hq for hq connections, or an empty string, and quic_bpf can route packets with eBPF on Linux 5.7+ to support connection migration.

It is an official nginx module, present since 1.25.0, and is not built by default upstream, so it needs the --with-http_v3_module configure parameter. The usual deployment is adding a quic listener next to the existing ssl listener so browsers upgrade to HTTP/3 on their next visit.

Key directives

http3Enables HTTP/3 protocol negotiation on quic listen sockets, default on.
http3_max_concurrent_streamsSets the maximum number of concurrent HTTP/3 request streams in a connection, default 128.
http3_stream_buffer_sizeSize of the buffer used for reading and writing QUIC streams, default 64k.
quic_retryEnables QUIC address validation with Retry packets and NEW_TOKEN frames, default off.
quic_gsoSends packets in optimized batch mode using segmentation offloading (Linux UDP_SEGMENT), default off.
quic_host_keyFile with the secret key for stateless reset and address validation tokens; by default a random key per reload.

Example

nginx.conf
server { # for better compatibility use the same port for HTTP/3 and HTTPS listen 443 quic reuseport; listen 443 ssl; server_name example.com; http2 on; http3 on; quic_retry on; ssl_certificate /etc/ssl/example.com.crt; ssl_certificate_key /etc/ssl/example.com.key; location / { # advertise the availability of HTTP/3 add_header Alt-Svc 'h3=":443"; ma=86400'; root /var/www/example.com; } }

Availability

Compiled into every n.wtf nginx binary. Install nginx-extras and the directives above work out of the box, no load_module line needed.