+ +

+ + +QUIC +and +HTTP/3 +protocols are supported since 1.23.4 and are available +as a separate nginx-quic +prebult Linux package +or as part of our +commercial subscription +in a separate nginx-plus-http3 package. + + + + +The QUIC and HTTP/3 support is experimental, caveat emptor applies. + + + +

+ + +

+ + +For Linux, nginx-quic packages +from nginx.org can be used. +The packages +are available for the following Linux distributions and +versions: + + + +RHEL 9 and derivatives: amd64, arm64 + + + +Ubuntu 22.04: amd64, arm64 + + + + + + +The nginx-quic packages are dynamically linked with the +QuicTLS library. +It will be installed as a runtime dependency +alongside system-wide OpenSSL packages. +QuicTLS differs from operating system-provided OpenSSL package in the following: + + + +does not follow system-wide crypto policies + + + +does not have distribution-specific patches applied + + + +uses configuration from /etc/pki/quictls (RHEL9) +or /etc/quictls (Ubuntu 22.04) + + + + + + +The nginx-quic packages +cannot be installed alongside nginx or nginx-plus packages. + + + +Please back up your configuration files +before installing nginx-quic: + +sudo cp -a /etc/nginx /etc/nginx-quic-backup + + + + +

+ + +The nginx-quic package and be installed on +Red Hat Enterprise Linux and its derivatives such as +CentOS, Oracle Linux, Rocky Linux, AlmaLinux. + + + +Install the prerequisites: + +sudo dnf install yum-utils + + +To set up the yum repository, create the file named +/etc/yum.repos.d/nginx-quic.repo +with the following contents: + + +[nginx-quic] +name=nginx-quic repo +baseurl=https://packages.nginx.org/nginx-quic/rhel/9/$basearch/ +gpgcheck=1 +enabled=1 +gpgkey=https://nginx.org/keys/nginx_signing.key + + +To install nginx-quic, run the following commands: + +sudo dnf install nginx-quic + + +When prompted to accept the GPG key, verify that the fingerprint matches +573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62, +and if so, accept it. + + +

+ + +

+ + +Install the prerequisites: + +sudo apt update && sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring + + + + +Import an official nginx signing key so apt could verify the packages +authenticity. +Fetch the key: + +curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \ + | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null + + +To set up the apt repository for nginx-quic packages, run the following command: + +echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ + https://packages.nginx.org/nginx-quic/ubuntu `lsb_release -cs` nginx-quic" \ + | sudo tee /etc/apt/sources.list.d/nginx-quic.list + + + + +To install nginx-quic, run the following commands: + +sudo apt update +sudo apt install nginx-quic + + + +

+ +

+ + +

+ + +The build is configured using the configure command. +Please refer to for details. + + + +When configuring nginx, it is possible to enable QUIC and HTTP/3 +using the following configuration options: + + + + +--with-http_v3_module
+ + +enables QUIC and HTTP/3. + + + + + + +An SSL library that provides QUIC support is recommended to build nginx, such as +BoringSSL, +LibreSSL, or +QuicTLS. +Otherwise, the OpenSSL +compatibility layer will be used that does not support +early data. + + + +Use the following command to configure nginx with +BoringSSL: + +./auto/configure --with-debug --with-http_v3_module \ + --with-cc-opt="-I../boringssl/include" \ + --with-ld-opt="-L../boringssl/build/ssl \ + -L../boringssl/build/crypto" + + + + +Alternatively, nginx can be configured with +QuicTLS: + +./auto/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 a modern version of +LibreSSL: + +./auto/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. + + +

+ + +

+ + +The 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 limit +maximum UDP payload size on receive path: + +quic_mtu <size>; + + +To set +host key for various tokens: + +quic_host_key <filename>; + + + + + +QUIC requires TLSv1.3 protocol version which is enabled by default +in the directive. + + + +By default, +GSO Linux-specific optimization +is disabled. +Enable it in case a corresponding network interface is configured +to support GSO. + + +

+ + +

+ + + +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 quic and https + listen 8443 quic reuseport; + listen 8443 ssl; + + ssl_certificate certs/example.com.crt; + ssl_certificate_key certs/example.com.key; + + location / { + # required for browsers to direct them into quic port + add_header Alt-Svc 'h3=":8443"; ma=86400'; + } + } +} + + + +

+ + +

+ + +For the list of directives, please refer to +ngx_http_v3_module +module documentation. + + +

+ + +

+ + +Tips that may help to identify problems: + + + +Ensure nginx is built with the proper SSL library that supports QUIC. + + + +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 +(see the Clients section +for information about browsers and cache). +We recommend starting 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, please enable additional debugging in +src/event/quic/ngx_event_quic_connection.h: + + + +#define NGX_QUIC_DEBUG_PACKETS +#define NGX_QUIC_DEBUG_FRAMES +#define NGX_QUIC_DEBUG_ALLOC +#define NGX_QUIC_DEBUG_CRYPTO + + + + + + + +

+ + +

+ + +Please refer to . + + +

+ +