How to enable HTTP/3 (QUIC) support on Caddy

You will configure Caddy to support HTTP/3 using the QUIC protocol. These steps target Linux distributions like Ubuntu 24.04 or Debian 12 running Caddy v2.9.0 or later.

Prerequisites

• Operating System: Ubuntu 24.04, Debian 12, or AlmaLinux 9
• Web Server: Caddy v2.9.0 or later installed via official repository
• Go Environment: Go 1.22.x installed for module installation
• Privileges: Root or sudo access to install packages and modify system files
• Network: Active internet connection to download the quic-go module

Step 1: Install the quic-go module

Caddy relies on the quic-go library to handle HTTP/3 traffic. You must install this module to enable the QUIC transport layer. Run the following command to download and install the specific version of the module compatible with your Caddy build.

go install github.com/caddyserver/caddy/v2/cmd/caddy@latest

Wait for the download to complete. You will see a progress bar indicating the module is being fetched from the Go proxy.

go: downloading github.com/caddyserver/caddy/v2 v2.9.0
go: downloading github.com/quic-go/quic-go v0.55.0
go: downloading github.com/caddyserver/certmagic v0.24.0

This command updates your local Caddy binary with the latest code, including the necessary HTTP/3 dependencies.

Step 2: Update the Caddy configuration file

Open your Caddy configuration file located at /etc/caddy/Caddyfile. Add the `quic` directive to the site block to enable HTTP/3. Ensure your domain name is correctly listed in the address field.

sudo nano /etc/caddy/Caddyfile

Locate the site block for your domain. Modify the configuration to include the `quic` flag. The updated block should look like this:

example.com {
    respond "Hello, World!"
    quic
}

Save the file and exit the text editor. The `quic` directive tells Caddy to listen on UDP port 443 for QUIC traffic in addition to standard TCP port 443.

Step 3: Restart the Caddy service

Apply the changes by restarting the Caddy service. This ensures the new configuration is loaded and the QUIC module is active.

sudo systemctl restart caddy

Check the status of the service to confirm it started without errors.

sudo systemctl status caddy

You should see "active (running)" in the output. If the service fails to start, review the logs at /var/log/caddy/caddy.log for specific error messages.

Verify the installation

Test the HTTP/3 support using the curl command with the --http3 flag. This forces the client to use the QUIC protocol. Run the following command to verify the connection is established over HTTP/3.

curl --http3 -I https://example.com

You will see a response header indicating the protocol used. The output should contain the line "HTTP/3.0 200 OK". If you see this, the QUIC stack is functioning correctly.

HTTP/3.0 200 OK
date: Mon, 01 Jan 2024 12:00:00 GMT
content-length: 13
content-type: text/plain

Alternatively, use a browser with developer tools enabled to inspect the network tab. Look for "h3" in the protocol column of the request headers.

Troubleshooting

If you encounter issues enabling HTTP/3, review the following common errors and their fixes.

1. Error: "curl: unsupported option --http3"

This occurs when running curl on an older version that does not support HTTP/3. Update your curl package to a version that includes QUIC support. Run sudo apt install curl on Debian/Ubuntu or sudo yum update curl on AlmaLinux.

2. Error: "failed to listen: listen udp: address :443: bind: address already in use"

HTTP/3 uses UDP port 443. If another service is using this port, Caddy cannot bind to it. Check for conflicts using sudo ss -ulnp | grep 443. Ensure no other process is holding the port.

3. Error: "quic: failed to start: listen udp: address :443: bind: permission denied"

Caddy must run as root to bind to port 443. Ensure the Caddy service is running with elevated privileges. Check the systemd unit file at /etc/systemd/system/caddy.service to confirm the User field is set to root.

4. Error: "certificate verification failed"

QUIC requires TLS 1.3. If your browser or client rejects the connection, verify that your system supports TLS 1.3. Run openssl version to check your OpenSSL version. Update OpenSSL if it is older than 1.1.1.

After resolving these issues, restart the Caddy service again to apply the fixes. Verify the connection once more using the curl command with the --http3 flag.