Support for QUIC and HTTP/3

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Support for QUIC and HTTP/3

Building from sources
Configuration tips
Troubleshooting

Support for
QUIC
and
HTTP/3
protocols is available since 1.25.0, it is included in
Linux binary packages.
Please refer to the
ngx_http_v3_module
documentation.

Building from sources

The build is configured using the configure command.
Please refer to Building nginx from Sources for details.

The OpenSSL library
version 3.5.1 or higher is recommended to build nginx with QUIC support.
Otherwise, the OpenSSL
compatibility layer will be used that does not support
early data.
Alternatively,
BoringSSL,
LibreSSL, or
QuicTLS
prebuilt libraries can be used.

Use the following command to configure nginx with
BoringSSL:

./configure
--with-debug
--with-http_v3_module
--with-cc-opt="-I../boringssl/include"
--with-ld-opt="-L../boringssl/build -lstdc++"

Alternatively, nginx can be configured with
QuicTLS:

./configure
--with-debug
--with-http_v3_module
--with-cc-opt="-I../quictls/build/include"
--with-ld-opt="-L../quictls/build/lib"

Alternatively, nginx can be configured with
LibreSSL:

./configure
--with-debug
--with-http_v3_module
--with-cc-opt="-I../libressl/build/include"
--with-ld-opt="-L../libressl/build/lib"

After configuration,
nginx is compiled and installed using make.

Configuration tips

The listen directive in
ngx_http_core_module
module got a new parameter
quic
which enables HTTP/3 over QUIC on the specified port.

Along with the quic parameter
it is also possible to specify the
reuseport
parameter to make it work properly with multiple workers.

To enable
address validation:

quic_retry on;

To enable
0-RTT:

ssl_early_data on;

To enable
GSO (Generic Segmentation Offloading):

quic_gso on;

To set
host key for various tokens:

quic_host_key <filename>;

QUIC requires TLSv1.3 protocol version which is enabled by default
in the ssl_protocols directive.

By default,
GSO Linux-specific optimization
is disabled.
Enable it in case a corresponding network interface is configured
to support GSO.

Troubleshooting

Tips that may help to identify problems:

Ensure nginx is built with the proper SSL library.

Ensure nginx is using the proper SSL library in runtime
(the nginx -V shows what it is currently used).

Ensure a client is actually sending requests over QUIC.
It is recommended to start with a simple console client such as
ngtcp2
to ensure the server is configured properly before trying
with real browsers that may be quite picky with certificates.

Build nginx with debug support
and check the debug log.
It should contain all details about the connection and why it failed.
All related messages contain the “quic” prefix
and can be easily filtered out.

For a deeper investigation, additional debugging can be enabled
using the following macros:
NGX_QUIC_DEBUG_PACKETS,
NGX_QUIC_DEBUG_FRAMES,
NGX_QUIC_DEBUG_ALLOC,
NGX_QUIC_DEBUG_CRYPTO.

./configure
--with-http_v3_module
--with-debug
--with-cc-opt="-DNGX_QUIC_DEBUG_PACKETS -DNGX_QUIC_DEBUG_CRYPTO"