NaviServer Modules – 5.1.0
quic - Network Driver for HTTP/3 (QUIC)
The driver module quic provides support for the HTTP/3 protocol over QUIC (UDP-based, encrypted transport). It integrates closely with nsssl to share TLS configuration parameters and certificate handling, as QUIC relies on TLS 1.3 for encryption and authentication.
The quic driver is the HTTP/3 counterpart of nsssl. While nsssl handles encrypted HTTP/1.x and HTTP/2 traffic over TCP/TLS, the quic driver provides equivalent functionality for HTTP/3 over QUIC (UDP). Both modules share the same TLS configuration (certificates, ciphers, protocols, and OCSP settings) so that administrators can manage all HTTPS and HTTP/3 parameters in a unified way. The driver uses OpenSSL’s native QUIC implementation introduced in OpenSSL 3.1 and integrates it directly into NaviServer’s driver model.
This module requires NaviServer to be built with --with-openssl and OpenSSL 4.0 or newer, as HTTP/3 support is based on the OpenSSL QUIC API introduced in OpenSSL 3.1+, and which is feature complete for this server in OpenSSL 4.0+.
To enable HTTP/3, the QUIC module must be loaded alongside nsssl (used for HTTP/1.x). The two modules share security settings such as certificates, ciphers, and protocols.
ns_section ns/modules {
ns_param https nsssl.so
ns_param h3 quic.so
}
ns_section ns/module/https {
ns_param defaultserver ...
ns_param address ...
ns_param port ...
ns_param hostname ...
ns_param ciphers ...
ns_param protocols ...
ns_param certificate ...
...
# Extra parameters specific to HTTP/3
#ns_param h3advertise true ;# default: false -> advertise Alt-Svc header
#ns_param h3persist false ;# default: true -> control 'persist' flag in Alt-Svc
}
ns_section ns/module/h3 {
ns_param https ns/module/https
}
When set to true, NaviServer automatically advertises the HTTP/3 endpoint to clients using an Alt-Svc header in the HTTP/1.x response. The first connection is served via HTTPS/TCP, and clients that support HTTP/3 will use the advertised Alt-Svc to reconnect over QUIC.
Controls the persist attribute of the generated Alt-Svc header. When true (default), the client may continue to use the cached HTTP/3 endpoint across browser restarts until the Alt-Svc lifetime expires.
The NaviServer HTTP/3 module works best with publicly trusted certificates (e.g., from Let’s Encrypt), especially when the header field Alt-Svc is used to advertise the availability of HTTP/3 in an HTTP/1.* request. Browsers will only attempt QUIC connections for Alt-Svc endpoints whose certificates chain to a trusted public root. Self-signed or private-CA certificates (commonly used for "localhost" testing) are typically rejected for QUIC even if accepted for HTTPS/TCP.
When visiting an HTTPS site such as https://example.org, the initial connection is made via HTTP/1.x or HTTP/2 over TCP. If the server includes an Alt-Svc header such as:
Alt-Svc: h3=":8445"; ma=86400; persist=1
the browser will cache this advertisement and may attempt to reconnect using HTTP/3 on subsequent requests.
Important: acceptance of Alt-Svc advertisements is determined by the browser, not by the server. Most browsers ignore Alt-Svc entries for endpoints with untrusted certificates.
For Chromium-based browsers (Chrome, Brave, Edge), HTTP/3 can be forced manually for specific origins by launching the browser with flags such as:
/Applications/Brave\ Browser.app/Contents/MacOS/Brave\ Browser \ --use-system-default-cert-verifier \ --disable-features=UseChromeRootStore \ --enable-quic \ --origin-to-force-quic-on=localhost:8445
A more robust approach is to use a publicly trusted certificate. For testing, you can create a hostname in a domain you control (for example, test.example.org via a DNS-01 challenge) and map it to 127.0.0.1 in /etc/hosts. This allows Alt-Svc-driven HTTP/3 without special browser flags.
This limitation is due to browser policy, not a restriction of NaviServer’s HTTP/3 implementation. Policies may change over time; if you discover reliable workarounds for e self-signed Alt-Svc testing, please share them with the community.
To enable automatic advertisement of HTTP/3 support, set h3advertise to true in the https section. Clients that support HTTP/3 will transparently upgrade after the first request. To enable HTTP/3 selectively (for example, only for specific client IPs or address ranges), configure h3advertise with false and dynamically add an Alt-Svc header via a Tcl filter:
proc register_alt_svc {args} {
set value [subst {h3=":[ns_conn port]"; ma=86400; persist=1}]
ns_set update [ns_conn outputheaders] alt-svc $value
return -code continue
}
You can restrict advertisement to a specific IP address by using filter constraints:
ns_register_filter -constraints {x-ns-ip 137.208.148.93} \
postauth GET /* register_alt_svc
The QUIC driver depends on the nghttp3 library, which provides the HTTP/3 frame encoding and decoding layer. The build system automatically searches for libnghttp3 and its headers during configuration.
If the library is installed in a non-standard location, its location can be specified using one of the following methods:
# Use a prefix directory ./configure --with-nghttp3=/opt/nghttp3
or, to override the include and library flags directly:
./configure NGHTTP3_CFLAGS="-I$HOME/pfx/include" \ NGHTTP3_LIBS="-L$HOME/pfx/lib -lnghttp3"
If pkg-config cannot locate the appropriate `.pc` file, ensure that PKG_CONFIG_PATH points to the directory containing either libnghttp3.pc or nghttp3.pc (for example, /usr/local/lib/pkgconfig).
When nghttp3 is correctly detected, the quic module will be built automatically as part of the NaviServer build. Otherwise, the driver will be skipped, and a summary message will be displayed at the end of the configuration phase.
HTTP/3 (QUIC) in NaviServer relies on OpenSSL’s QUIC stack, which was introduced in OpenSSL 3.1 and is still under active development. For the QUIC driver to function correctly, NaviServer 5 (or newer) and OpenSSL 4 or later are required, as earlier versions do not provide the necessary QUIC APIs.
All TLS-related configuration parameters - such as certificates, ciphers, protocols, and OCSP stapling - are inherited directly from the referenced https module. No separate TLS directives are required in the ns/module/h3 section.
At this stage, the QUIC driver provides full integration of HTTP/3 within NaviServer’s driver architecture for serving inbound HTTP/3 requests. However, as the implementation is still evolving, it may produce verbose diagnostic output in the server log and expose limitations within the underlying OpenSSL QUIC layer. In particular, occasional instability has been observed when querying the state of existing QUIC streams.
For this reason, production deployment on high-traffic public sites is not yet recommended.
Currently, the QUIC driver implements only the server side of the HTTP/3 protocol. Client-side HTTP/3 support (for example, via ns_http or ns_connchan) is not yet available and will be added once the server-side implementation reaches a stable and mature state.