http_v3
module#
Enables HTTP/3 support for client connections, as well as for connections with proxied servers configured using the following http_proxy 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 repos, the module is included in the build.
It’s highly recommended to build the module with an SSL library that fully supports QUIC:
Using BoringSSL:
./configure --with-debug --with-http_v3_module --with-cc-opt="-I../boringssl/include" --with-ld-opt="-L../boringssl/build/ssl -L../boringssl/build/crypto"Using QuicTLS:
./configure --with-debug --with-http_v3_module --with-cc-opt="-I../quictls/build/include" --with-ld-opt="-L../quictls/build/lib"Otherwise, the OpenSSL library will use a compatibility layer that doesn’t support (early data) and some other features, such as session reuse. The resulting build will only interoperate with clients and servers that use the same OpenSSL compatibility layer.
Example Configuration#
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';
}
}
}
Important
Note that accepting HTTP/3 connections over TLS requires the TLSv1.3 protocol support, which is available since OpenSSL version 1.1.1.
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.
http3_max_concurrent_streams#
- Syntax:
http3_max_concurrent_streams
number;- Default:
http3_max_concurrent_streams 128;
- Context:
http, server
Sets the maximum number of concurrent HTTP/3 request streams in a connection.
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 client connection IDs which 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.
Important
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.
Important
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:
|
for HTTP/3 connections |
|
for hq connections |
|
an empty string otherwise |
$quic_connection
#
QUIC connection serial number