Guida Completa al Debug Pi-hole e Unbound su Linux

Quando la risoluzione dei nomi della rete domestica o aziendale smette improvvisamente di funzionare, diventa prioritario eseguire un accurato debug Pi-hole e Unbound per individuare il collo di bottiglia che impedisce ai client di navigare su Internet. L’accoppiata formata da Pi-hole come DNS sinkhole e Unbound come resolver ricorsivo locale rappresenta una delle soluzioni più solide ed efficaci per tutelare la propria privacy ed eliminare il tracciamento pubblicitario. Tuttavia, l’interazione tra questi due componenti software può presentare criticità complesse legate a timeout DNS, mancate sincronizzazioni temporali, corruzione delle chiavi DNSSEC o conflitti di porte sul socket di rete.

Architettura della Connessione tra Pi-hole e Unbound

Per comprendere l’origine dei guasti, occorre visualizzare chiaramente la catena di risoluzione: i dispositivi client inviano le richieste DNS sulla porta standard 53 al servizio pihole-FTL. Quest’ultimo applica le liste di blocco e inoltra le query lecite all’istanza locale di Unbound, solitamente in ascolto sull’indirizzo di loopback 127.0.0.1#5335. Unbound, agendo come resolver ricorsivo autonomo, non interroga server upstream commerciali come Google o Cloudflare, ma scende lungo la gerarchia della rete partendo dai root server DNS, passando per i server TLD fino ai nameserver autoritativi di ciascun dominio.

Un’interruzione nella comunicazione tra Pi-hole e Unbound genera immediatamente un errore generale di risoluzione (NXDOMAIN o SERVFAIL), rendendo la navigazione impossibile per tutti i nodi della LAN configurati per utilizzare il resolver locale.

Verifica Preliminare dello Stato dei Demoni di Rete

Il primo passo operativo richiede l’accesso tramite terminale SSH al sistema Linux ospitante. È necessario interrogare systemd per conoscere lo stato di entrambi i servizi:

sudo systemctl status pihole-FTL
sudo systemctl status unbound

Se entrambi i servizi risultano attivi ed in esecuzione (active (running)), l’attenzione deve spostarsi sull’effettivo binding delle porte di rete tramite l’utilità ss:

sudo ss -tulpn | grep -E ':(53|5335)'

Se l’output non evidenzia Unbound in ascolto sul socket 127.0.0.1:5335, il problema risiede quasi certamente in un errore di sintassi all’interno dei file di configurazione o in un crash silente del demone all’avvio.

Analisi dei Log e Sintassi di Configurazione

I problemi di avvio o le interruzioni inattese sono documentati nei registri di sistema. È fondamentale, durante la sessione di debug Pi-hole e Unbound, analizzare le righe generate dal file di configurazione specifico, solitamente posizionato in /etc/unbound/unbound.conf.d/pi-hole.conf. Per scovare errori formali prima ancora di riavviare il servizio, si utilizza l’apposito strumento di convalida fornito con il pacchetto Unbound:

sudo unbound-checkconf

Se il comando restituisce un messaggio del tipo unbound-checkconf: no errors in /etc/unbound/unbound.conf, la sintassi è formalmente corretta. In caso contrario, l’output indicherà con precisione la riga e la direttiva che impediscono il caricamento del file.

Aumentare la Verbosità del Logging di Unbound

Di default, Unbound opera con un livello di logging minimo per preservare le prestazioni della memoria e limitare le scritture su disco (particolarmente critiche sulle schede microSD dei Raspberry Pi). Per diagnosticare query interrotte o errori critici, conviene elevare temporaneamente il valore del parametro di verbosità editando il file /etc/unbound/unbound.conf.d/pi-hole.conf:

server:
    verbosity: 2
    log-queries: yes
    logfile: "/var/log/unbound/unbound.log"

Dopo aver salvato la modifica e riavviato il processo con sudo systemctl restart unbound, è possibile monitorare le query in tempo reale aprendo un terminale secondario con il comando sudo tail -f /var/log/unbound/unbound.log oppure esaminando il log aggregato con sudo journalctl -u unbound -e.

Risolvere l’Errore SERVFAIL e le Anomalie DNSSEC

L’errore più comune e insidioso che si riscontra nei resolver ricorsivi è il codice di risposta SERVFAIL. Tale errore si manifesta tipicamente quando Unbound non riesce a stabilire la catena di fiducia crittografica per un dominio protetto da DNSSEC. Quando si affronta il debug Pi-hole e Unbound in presenza di risposte SERVFAIL, la causa scatenante è quasi sempre riconducibile a uno sfasamento temporale dell’orologio di sistema (clock drift) o a una chiave di root obsoleta.

Sincronizzazione dell’Orario di Sistema (NTP)

La firma digitale dei record DNSSEC ha una finestra di validità temporale estremamente rigorosa. Se l’orologio del sistema Linux è arretrato o anticipato anche solo di poche ore rispetto al tempo coordinato universale (UTC), tutte le firme risulteranno non valide, costringendo Unbound a rifiutare la risposta per motivi di sicurezza.

• Verificare lo stato dell’orologio con: timedatectl status
• Assicurarsi che la voce NTP service: active sia presente.
• Forzare la sincronizzazione temporale tramite sudo systemctl restart systemd-timesyncd o riavviando il demone chrony.

Aggiornamento delle Chiavi di Root (Trust Anchor)

La chiave radice per la convalida DNSSEC viene gestita dal tool unbound-anchor. Se il file root.key è corrotto o privo dei corretti permessi di lettura per l’utente di sistema unbound, la convalida fallisce sistematicamente. Per ripristinarlo manualmente, si eseguono le seguenti istruzioni:

sudo -u unbound unbound-anchor -a /var/lib/unbound/root.key
sudo systemctl restart unbound

Per testare se il motore di validazione opera correttamente, si possono effettuare due interrogazioni distinte tramite dig puntando direttamente a Unbound:

# Questo test DEVE restituire status: NOERROR
dig sigok.verteiltesysteme.net @127.0.0.1 -p 5335

# Questo test DEVE fallire restituendo status: SERVFAIL
dig sigfail.verteiltesysteme.net @127.0.0.1 -p 5335

Se entrambi i comandi restituiscono il codice atteso, il motore DNSSEC è perfettamente allineato e funzionante.

Risoluzione dei Conflitti di Rete e Ottimizzazione EDNS

Nei sistemi Linux moderni, un altro ostacolo frequente è rappresentato dalla presenza di resolver locali integrati, come systemd-resolved. Se entrambi i servizi tentano di ascoltare sulla medesima interfaccia o se si verificano collisioni di indirizzamento, Pi-hole non riuscirà a contattare Unbound. Uno step cruciale nel debug Pi-hole e Unbound consiste nel verificare se un processo terzo sta occupando la porta o intercettando i pacchetti diretti a localhost.

Disattivare il Listener Stub di systemd-resolved

Se systemd-resolved interferisce con la porta 53 o con l’inoltro dei pacchetti, è necessario modificarne la configurazione in /etc/systemd/resolved.conf:

[Resolve]
DNS=127.0.0.1
DNSStubListener=no

Quindi, ripristinare il collegamento simbolico corretto del file resolv.conf per consentire al sistema operativo stesso di risolvere i domini tramite Pi-hole:

sudo rm /etc/resolv.conf
sudo ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf
sudo systemctl restart systemd-resolved

Dimensione del Buffer EDNS e Frammentazione dei Pacchetti UDP

In passato, le risposte DNS che eccedevano la dimensione di 512 byte venivano frammentate o inoltrate via TCP. Molti router casalinghi o firewall dotati di packet inspection scartano i pacchetti UDP frammentati con flag EDNS di grandi dimensioni, bloccando silenziosamente la risposta di Unbound verso i client. Per prevenire cadute di connessione o blocchi durante la navigazione, la direttiva consigliata per i buffer UDP è 1232 byte:

server:
    edns-buffer-size: 1232
    so-rcvbuf: 4m
    so-sndbuf: 4m

Questa impostazione assicura che le risposte DNS rientrino nell’MTU standard della rete locale ed evita frammentazioni a livello IP che comprometterebbero l’affidabilità delle risposte inviate a Pi-hole.

Test di Carico e Monitoraggio Continuo

Una volta risolti i blocchi immediati, occorre verificare che la latenza delle query sia accettabile. Le prime richieste di domini non ancora salvati in cache richiedono solitamente tra i 200ms e gli 800ms, poiché Unbound deve interrogare l’intera catena autoritativa globale. Tuttavia, le successive richieste per lo stesso record devono essere erogate in tempi inferiori a 2ms direttamente dalla cache di Unbound o da quella di Pi-hole.

Per monitorare le prestazioni complessive e le metriche di Unbound in tempo reale, è possibile invocare l’utility integrata unbound-control:

sudo unbound-control stats_noreset | grep -E '(total.num.queries|cache.hits|cache.miss)'

Per mantenere un’infrastruttura di rete sana, si consiglia di consultare anche le linee guida relative alla sicurezza della rete locale e di impostare una corretta configurazione del server DNS con backup regolari delle directory /etc/pihole e /etc/unbound.

In conclusione, portare a termine con successo il debug Pi-hole e Unbound garantisce una rete domestica o d’ufficio non solo priva di annunci invasivi, ma completamente autonoma rispetto ai server DNS dei grandi fornitori esterni, consolidando la protezione dei dati personali e migliorando la resilienza di tutti i dispositivi connessi.