Riavviare o ricaricare NGINX su Ubuntu 20.04

Riavvio e ricarica di NGINX non sono la stessa cosa

Su Ubuntu 20.04, quando lavori su NGINX devi distinguere con precisione tra reload e restart. La differenza non è accademica: un reload applica la configurazione senza interrompere il servizio in modo visibile agli utenti, mentre un restart ferma e riavvia il demone, con un impatto molto più alto sul traffico in corso.

© TrgtKLS • Tech, Sicurezza e Strumenti & guide per Webmaster — https://trgtkls.it — tutti i diritti riservati.

Se devi cambiare virtual host, certificati, regole di reverse proxy, gzip, HTTP/2 o limiti di worker, nella maggior parte dei casi il primo tentativo corretto è il reload. Il restart va tenuto per i casi in cui il processo è in stato sporco, la configurazione non viene assorbita correttamente, oppure stai risolvendo un problema che non si chiude con una semplice ricarica.

Su una macchina di produzione, questo dettaglio conta perché la scelta sbagliata cambia il blast radius: un reload ben fatto ha un impatto limitato, un restart può azzerare connessioni attive, interrompere upload, spezzare sessioni WebSocket e creare errori intermittenti difficili da leggere nei log applicativi.

Cosa succede davvero quando fai reload

Con reload, NGINX rilegge la configurazione, apre i nuovi socket se necessari e lascia terminare i worker vecchi mentre i nuovi prendono in carico il traffico. In pratica, il cambio avviene in modo graduale. Questo è il comportamento che vuoi quasi sempre quando modifichi file sotto /etc/nginx/.

Il punto chiave è che il reload non è una magia: se la configurazione è sintatticamente sbagliata, il servizio può rifiutare il cambio. Per questo il comando corretto non è mai “reload alla cieca”, ma prima validazione della configurazione e poi applicazione.

La sequenza minima sana è questa:

1. verificare la sintassi con nginx -t;
2. se l’output è OK, eseguire il reload;
3. controllare log e risposta HTTP dopo il cambio.

Il vantaggio operativo è semplice: riduci il rischio di downtime indotto da manutenzione banale. Se stai aggiornando un certificato TLS o un blocco server, il reload è la scelta naturale, non il restart.

Quando il restart ha senso

Il restart è più aggressivo e va usato solo quando serve davvero. È utile se il processo NGINX ha accumulato uno stato anomalo, se hai cambiato componenti che richiedono una nuova inizializzazione completa, o se il reload non risolve un problema di servizio che persiste nonostante la configurazione sia valida.

Un caso tipico è un ambiente dove il demone è vivo ma non accetta correttamente il nuovo assetto dopo cambi ripetuti, oppure dove vuoi riallineare completamente il processo dopo un aggiornamento di pacchetti o librerie. Anche qui, però, il restart non deve essere la prima mossa: prima osserva stato del servizio, log e sintomi reali.

In produzione, il restart ha un blast radius più ampio. Se NGINX fa da front-end per più siti o API, un riavvio può generare timeout brevi, reset di connessione e spike di errori 502/504 verso i client o verso un bilanciatore a monte. Se stai lavorando dietro CDN o load balancer, il problema può essere mascherato, ma resta.

Comandi corretti su Ubuntu 20.04

Su Ubuntu 20.04 NGINX è gestito da systemd. I comandi più utili sono questi:

sudo nginx -t
sudo systemctl reload nginx
sudo systemctl restart nginx
sudo systemctl status nginx --no-pager

nginx -t controlla sintassi e riferimenti ai file inclusi. Se fallisce, il messaggio indica spesso la riga e il file con il problema. Non ignorarlo: un reload con config rotta può non applicarsi e lasciarti con una falsa sensazione di successo.

systemctl reload nginx applica la nuova configurazione senza stop completo del servizio. systemctl restart nginx invece chiude e riapre il processo. Per troubleshooting serio, controlla anche se il servizio è attivo e se il processo master è quello atteso.

systemctl is-active nginx
systemctl show nginx -p MainPID -p ExecMainStatus
journalctl -u nginx -n 50 --no-pager

Se vuoi capire se il cambio è stato preso, il controllo più diretto è una richiesta HTTP locale o dal client di test:

curl -I http://127.0.0.1
curl -kI https://tuo-dominio.tld

La risposta attesa, in condizioni sane, è un 200, un 301 o comunque un codice coerente con il sito. Se compare un 5xx, il problema non è la semantica del comando ma il layer sotto o sopra NGINX.

Checklist operativa prima di toccare produzione

Quando lavori su un server esposto, la sequenza corretta è più importante del comando singolo. Una checklist minima evita di trasformare un cambio banale in un incidente.

1. Identifica lo stato atteso: quale file hai modificato e quale comportamento deve cambiare.
2. Valida la configurazione con nginx -t.
3. Salva un punto di rollback: copia del file o snippet versionato.
4. Applica un reload, non un restart, se il cambio è configurazionale.
5. Verifica risposta HTTP, log e sintomi utente.

Per esempio, se hai aggiunto un nuovo host virtuale in /etc/nginx/sites-available/ e il relativo symlink in /etc/nginx/sites-enabled/, il reload è sufficiente nella quasi totalità dei casi. Il restart non aggiunge valore, ma aggiunge rischio.

Se invece hai un problema di socket bloccati, processi zombie o mismatch dopo un upgrade, il restart può essere il passo successivo, ma solo dopo aver letto i log e confermato che il reload non basta.

Validazione della configurazione: il punto che molti saltano

La validazione non è opzionale. NGINX è abbastanza severo: un errore in un file incluso può impedire il caricamento dell’intera configurazione. Il controllo sintattico va fatto prima di qualsiasi azione sul servizio.

sudo nginx -t

Output atteso in caso sano:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Se vedi un errore, il primo obiettivo non è riavviare il servizio ma correggere il file indicato. In molti casi la riga riportata è vicina al punto reale del problema, ma non sempre coincide con l’errore semantico: controlla anche i blocchi inclusi e i file referenziati.

Un dettaglio utile: se lavori con più siti e molti include, tenere la configurazione spezzata per funzione aiuta a isolare il guasto. Un file troppo grande e monolitico rende il debug più lento e aumenta il rischio di errori durante il reload.

Esempio concreto: cambio certificato TLS

Il caso più comune è il rinnovo di un certificato TLS. Hai aggiornato i percorsi in un blocco server, ad esempio ssl_certificate e ssl_certificate_key. In questo scenario il comportamento corretto è quasi sempre:

1. verificare che i nuovi file esistano e abbiano permessi leggibili da NGINX;
2. eseguire nginx -t;
3. eseguire systemctl reload nginx;
4. testare la catena TLS con un client esterno o con curl -Iv https://dominio.

Se il certificato è stato aggiornato ma il browser mostra ancora quello vecchio, il problema non è necessariamente il reload. Può trattarsi di cache lato client, CDN, load balancer o di un file sbagliato puntato dalla configurazione. Qui non si improvvisa: bisogna leggere il certificato effettivamente servito e confrontarlo con quello su disco.

openssl s_client -connect dominio.tld:443 -servername dominio.tld 

Il comando sopra mostra il certificato realmente presentato dal server. È un controllo più affidabile del semplice “ho ricaricato NGINX, quindi deve andare”.

Quando il reload fallisce ma il servizio resta su

Può succedere che il reload fallisca e il servizio continui a servire la vecchia configurazione. Questo comportamento è utile perché evita downtime, ma può anche ingannarti: il sito sembra vivo, però non stai applicando il cambio che pensavi di aver fatto.

In quel caso, non forzare il restart come prima reazione. Prima guarda il log di sistema e i log di NGINX, poi correggi la causa del fallimento. Se il reload è respinto, di solito c’è un errore di sintassi, un file mancante, un permesso errato o un binding già occupato.

journalctl -u nginx -n 100 --no-pager
ls -l /etc/nginx/sites-enabled/
ls -l /etc/nginx/ssl/

Il criterio corretto è semplice: se il problema è di configurazione, risolvi la configurazione; se il problema è del processo, allora valuti il restart. Saltare direttamente al restart sposta il sintomo, non la causa.

Rollback rapido e reversibile

Ogni modifica a NGINX dovrebbe avere un rollback chiaro. Questo non è un optional da manuale, ma una protezione concreta quando lavori su un front-end esposto.

1. Prima del cambio, salva il file modificato: cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak oppure versiona lo snippet.
2. Applica il cambio.
3. Se la verifica post-change fallisce, ripristina il file precedente.
4. Esegui di nuovo nginx -t e poi il reload.

sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
sudo cp /etc/nginx/nginx.conf.bak /etc/nginx/nginx.conf
sudo nginx -t
sudo systemctl reload nginx

Se stai lavorando su più file, il rollback deve includere anche symlink, certificati sostituiti e snippet aggiunti in directory come /etc/nginx/conf.d/ o /etc/nginx/sites-enabled/. Un rollback parziale spesso lascia la configurazione in uno stato incoerente.

Regola pratica da tenere in testa

Se stai cambiando configurazione, prova prima il reload. Se stai recuperando da uno stato anomalo del processo, valuta il restart. Questa distinzione ti evita cambi inutilmente invasivi e ti aiuta a mantenere un profilo di rischio basso.

In sintesi operativa: osserva, valida, applica, verifica. Non invertire l’ordine. Su NGINX la maggior parte degli incidenti non nasce dal comando in sé, ma dal fatto che qualcuno lo esegue senza capire se sta correggendo un file, un processo o una dipendenza a monte.

Assunzione: ambiente Ubuntu 20.04 con NGINX gestito da systemd, accesso root o sudo, e configurazione in /etc/nginx/.