Abilitare HTTP/3 su NGINX e Ubuntu 24.04: pacchetti, configurazione e verifica con curl

Perché i pacchetti della distribuzione non bastano

Il supporto a QUIC e HTTP/3 in NGINX è disponibile dalla versione 1.25.0 ed è incluso nei pacchetti binari ufficiali pubblicati da nginx.org. Chi installa NGINX dai repository universe di Ubuntu rischia di trovarsi con una build più vecchia, priva del modulo ngx_http_v3_module: su un server già in produzione il controllo si fa con nginx -v, e se il numero è sotto 1.25.0 il modulo semplicemente non c'è. La via pulita, su Ubuntu 24.04 "noble", è passare al repository ufficiale di nginx.org, che compila già il modulo v3 nei pacchetti distribuiti: chi parte invece da una build da sorgente deve aggiungere esplicitamente il flag --with-http_v3_module in fase di configure, perché il modulo non viene incluso di default.

Passo 1: il repository ufficiale nginx.org

Ubuntu 24.04 "noble" è una delle versioni supportate ufficialmente dal repository nginx.org, sia su x86_64 sia su aarch64/arm64. I comandi, presi dalla guida ufficiale ai pacchetti Linux, sono:

sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring

curl https://nginx.org/keys/nginx_signing.key \
 | gpg --dearmor \
 | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
https://nginx.org/packages/ubuntu $(lsb_release -cs) nginx" \
 | sudo tee /etc/apt/sources.list.d/nginx.list

sudo apt update
sudo apt install nginx

Chi preferisce la versione mainline (più recente, stesso ramo che riceve prima le novità su QUIC) sostituisce l'URL con https://nginx.org/packages/mainline/ubuntu.

Passo 2: verificare che il modulo ci sia davvero

Prima di toccare la configurazione, un controllo:

nginx -V 2>&1 | grep -o with-http_v3_module

Se il comando non restituisce nulla, il binario installato non supporta HTTP/3 e nessuna direttiva in nginx.conf lo farà funzionare: va cambiato il pacchetto, non la configurazione.

Passo 3: le direttive nel blocco server

Le direttive principali, documentate nel modulo ngx_http_v3_module, sono il parametro quic sul listen e, se si usano più worker, reuseport insieme ad esso. Per l'indirizzamento duale e la compatibilità con i client che non supportano ancora QUIC, nginx.org consiglia di usare la stessa porta sia per HTTP/3 sia per HTTPS:

server {
 listen 443 ssl;
 listen 443 quic reuseport;
 listen [::]:443 ssl;
 listen [::]:443 quic reuseport;

 http2 on;
 http3 on;

 server_name example.com;

 ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
 ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
 ssl_protocols TLSv1.3;

 add_header Alt-Svc 'h3=":443"; ma=86400' always;

 quic_retry on;
 ssl_early_data on;

 root /var/www/example.com;
 index index.html;
}

QUIC richiede obbligatoriamente TLSv1.3, anche se la connessione TCP di fallback continua ad accettare TLSv1.2. La direttiva http3 ha valore di default on nel contesto http/server una volta che il modulo è compilato, ma scriverla esplicitamente rende la configurazione più leggibile. quic_retry on abilita la validazione dell'indirizzo contro gli attacchi di amplificazione; ssl_early_data on abilita lo 0-RTT, ma la libreria OpenSSL versione 3.5.1 o superiore è consigliata per costruire NGINX con pieno supporto QUIC: sotto quella soglia viene usato uno strato di compatibilità che non supporta lo 0-RTT.

Dopo la modifica, test e reload:

sudo nginx -t
sudo systemctl reload nginx

Passo 4: la porta UDP nel firewall

HTTP/3 viaggia su UDP, non su TCP: la regola che chi gestisce il server dimentica più spesso è proprio quella sulla porta UDP, perché la 443 TCP è già aperta per HTTPS da tempo. Con ufw:

sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw reload

Senza la regola UDP il browser prova HTTP/3, non riceve risposta e ripiega su HTTP/2 senza errori visibili: il sito continua a funzionare, ma non sta usando QUIC.

Passo 5: verificare con curl --http3

Qui si inciampa spesso: il curl installato da apt su Ubuntu 24.04 normalmente non supporta HTTP/3. Secondo la documentazione ufficiale di curl.se, il supporto richiede una build collegata a ngtcp2 e nghttp3 insieme a una libreria TLS compatibile con QUIC (OpenSSL 3.5.0 o superiore, oppure BoringSSL, LibreSSL, quictls o wolfSSL con patch QUIC). Il controllo si fa così:

curl -V | grep -i HTTP3

Se la riga delle feature non contiene HTTP3, il binario va sostituito con una build che lo includa prima di procedere. Una volta disponibile un curl adatto, la verifica sul server è:

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

Nell'output, la riga iniziale della risposta deve indicare la versione del protocollo negoziata; con --http3-only la richiesta fallisce esplicitamente se QUIC non va a buon fine, utile per un test secco senza il fallback automatico a HTTP/2 o HTTP/1.1 che curl applica di default con --http3.

Un avviso di sicurezza da conoscere

Il modulo QUIC di NGINX resta sperimentale. La CVE-2024-24989, che riguarda proprio il modulo HTTP/3 QUIC e può causare la terminazione dei processi worker a fronte di richieste non divulgate pubblicamente, risulta "Not affected" per il pacchetto nginx di Ubuntu 24.04 LTS noble nel registro di sicurezza Ubuntu — un buon motivo per tenere comunque sotto controllo gli avvisi di sicurezza quando si abilita un modulo etichettato come sperimentale in produzione.

Tabella dei requisiti

Componente	Versione minima richiesta	Dove si verifica
NGINX	1.25.0, con pacchetto nginx.org (modulo v3 già compilato) o build propria con --with-http_v3_module	nginx -V | grep http_v3_module
OpenSSL	1.1.1 o superiore per QUIC di base; 3.5.1 o superiore per lo 0-RTT (ssl_early_data)	openssl version
TLS nel blocco server	TLSv1.3 obbligatorio	direttiva ssl_protocols
Ubuntu	24.04 "noble", piattaforma ufficialmente supportata dai pacchetti nginx.org	lsb_release -cs
curl per il test	build con ngtcp2 + nghttp3 e TLS compatibile QUIC	curl -V | grep HTTP3
Firewall	porta UDP 443 aperta, oltre alla TCP 443	sudo ufw status