NaviServer Modules – 5.1.1
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. The HTTP/3 section uses the referenced HTTPS section as a fallback for shared driver and TLS configuration, while values specified in the HTTP/3 section override the corresponding HTTPS values.
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). By default, both modules use the same TLS configuration (certificates, ciphers, protocols, and OCSP settings). Shared network-driver parameters are inherited as well. Administrators can override any such parameter in the HTTP/3 section when TCP and UDP transports require different settings, for example different driver or writer thread counts. 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 true ;# default: false -> control 'persist' flag in Alt-Svc
}
ns_section ns/module/h3 {
ns_param https ns/module/https
# Optional HTTP/3 overrides of inherited driver or TLS parameters
ns_param driverthreads 1
ns_param writerthreads 0
# QUIC-specific parameters
ns_param recvbufsize 8MB
ns_param sendqueuesize 256kB
}
QUIC-specific Parameters for the nsssl module:
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, the client may continue to use the cached HTTP/3 endpoint across browser restarts until the Alt-Svc lifetime expires.
Parameters for the quic module:
Names the fallback configuration section, normally ns/module/https. Parameters explicitly specified in ns/module/h3 take precedence; otherwise shared driver and TLS parameters are read from this section.
Inherited values used by the HTTP/3 driver are materialized in ns/module/h3 for configuration introspection. They are marked as read, not defaulted, and can be inspected with ns_configsection -filter inherited ns/module/h3. Misspelled or otherwise unused parameters remain visible through the unread filter.
Controls QUIC client address validation. When enabled, which is the default, clients that do not present a valid address-validation token receive a Retry packet. This validates the client's network address but adds one network round trip to the initial connection. Repeat clients presenting a valid token previously issued in a NEW_TOKEN frame can connect without this additional round trip.
Disabling validation suppresses Retry packets. This is useful for benchmarks whose client does not retain and reuse NEW_TOKEN tokens: connection times then more closely represent repeat connections made with a valid token. Disabling validation weakens protection against connection floods using spoofed source addresses and is therefore not recommended for normal Internet-facing operation.
Enables detailed HTTP/3 and QUIC diagnostic logging. When enabled, the module reports internal connection and stream state, pollset management, SSL polling events, write scheduling, and cleanup operations using the Debug(quic) log severity.
The option is disabled by default, since the generated output can be very large and may noticeably affect performance. It can be changed at runtime and should normally be enabled only temporarily for troubleshooting or when collecting diagnostics for a bug report.
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 ns/module/https section. Clients that support HTTP/3 will transparently upgrade after the first request.
When h3advertise is enabled, the generated Alt-Svc header uses port_ext. This is useful when the HTTPS and QUIC drivers listen on an internal container port that is published under a different external port. port_ext defaults to the first configured port.
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.
Shared driver and TLS configuration parameters - such as addresses, ports, thread counts, certificates, ciphers, protocols, and OCSP stapling - fall back to the referenced https section. No separate TLS directives are required in ns/module/h3. When a parameter is present in both sections, the value in ns/module/h3 is used. This permits TCP-based HTTPS and UDP-based HTTP/3 drivers to use different transport and concurrency settings while retaining common defaults.
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.