Enable HTTP/3 in NGINX 1.21+ – Quick Guide

Add HTTP/3 support to an existing NGINX 1.21+ server: prerequisites, config, verification, and rollback. Ensure OpenSSL 3.0+, a TLS 1.3 cert, UDP 443 open, and use the <code>http3</code> directive. Test with curl and OpenSSL, monitor CPU, and fall back to HTTP/2/TLS 1.3 if needed.

Desired Outcome

Upgrade an existing NGINX web server to support HTTP/3 (QUIC) on top of the current TLS 1.3/TLS 1.2 stack, improving latency for mobile clients while preserving backward compatibility for browsers that lack HTTP/3 support.

Prerequisites

Nginx build: The binary must include the --with-http_v3_module option and be compiled against OpenSSL 3.0+ (see nginx -V 2>&1 | grep http_v3).
TLS certificate: A certificate that supports TLS 1.3 is required. RSA keys of at least 2048 bits or ECDSA keys (P‑256/P‑384) work. The cert must be in PEM format and referenced by ssl_certificate and ssl_certificate_key.
Network: UDP traffic on port 443 must be permitted by firewalls, NATs, and load balancers. Verify with sudo ufw allow 443/udp or equivalent.
Operating system: The OS kernel must support UDP socket options used by QUIC (most modern Linux kernels do).

Configuration Steps

Locate your main nginx.conf (usually /etc/nginx/nginx.conf) and open it for editing with root privileges.

Add the http3 directive inside the http context. Example snippet:

http {
    # Existing TLS settings
    ssl_protocols TLSv1.3;            # enforce TLS 1.3 for HTTP/3
    ssl_prefer_server_ciphers off;   # let OpenSSL choose ciphers

    # HTTP/3 configuration
    http3 on;
    http3_max_field_size 8192;       # optional tuning
    http3_max_header_size 16384;     # optional tuning

    # Optional QUIC tuning block
    quic {
        max_udp_payload_size 1200;    # default is 1200
        initial_max_data 5000000;     # 5 MiB
    }

    # Existing server blocks follow
}

Ensure your server block has listen 443 ssl http2; and also listen 443 quic; if you want explicit UDP listening. Example:

server {
    listen 443 ssl http2;
    listen 443 quic reuseport;   # reuseport for load‑balancing
    server_name example.com;
    ssl_certificate /etc/ssl/certs/example.crt;
    ssl_certificate_key /etc/ssl/private/example.key;
    # ... other directives ...
}

Save the file and test the configuration:
```
sudo nginx -t
```
Reload NGINX to apply changes:
```
sudo systemctl reload nginx
```

Verification

Confirm QUIC module is present:
```
nginx -V 2>&1 | grep http_v3
```

Client‑side test with curl:

curl --http3 -I https://example.com
# Expect a line like: HTTP/3 200

OpenSSL handshake check:

openssl s_client -connect example.com:443 -tls1_3 -status
# Look for "QUIC" in the output or a "Server Hello" that includes QUIC extension

NGINX logs: Inspect /var/log/nginx/access.log for entries that include HTTP/3 or quic.
Performance monitoring: Use top or htop to watch CPU usage. A noticeable increase (<10–20%) may be expected due to QUIC packet processing.

Troubleshooting & Rollback

HTTP/3 not negotiated: Verify that the client supports HTTP/3. Modern Chrome/Firefox versions do. Use curl --http3 as a quick test.
UDP 443 blocked: If clients fall back to HTTP/2/TLS 1.3, check firewall rules. Re‑enable UDP traffic and reload NGINX.
Configuration errors: If nginx -t reports errors, comment out the http3 block and reload to restore TCP functionality.
CPU spike after enabling: Reduce initial_max_data or max_udp_payload_size in the quic block, or consider disabling HTTP/3 temporarily.
Fallback to HTTP/2/TLS 1.3: No action required. Clients that cannot negotiate HTTP/3 will automatically use the existing TCP/TLS stack.

Practical Check

After enabling HTTP/3, run:

curl -I --http3 https://example.com
# Should return "HTTP/3 200".

If you see a 200 with HTTP/3 in the status line, the feature is active. If not, review the steps above.

Enabling HTTP/3 (QUIC) in an Existing NGINX 1.21+ Deployment