Risolvere i Crash di Pi-hole FTL: SQLite e Rate Limit

Quando la risoluzione dei nomi di dominio si interrompe all’improvviso all’interno della rete locale, il principale indiziato è spesso il motore interno di blocco e gestione query di Pi-hole. Trovarsi di fronte a un inaspettato crash di Pi-hole FTL paralizza la navigazione di tutti i client collegati, impedendo il caricamento di siti web e l’accesso ai servizi essenziali. Per comprendere a fondo il contesto dell’infrastruttura DNS e isolare le interferenze con i resolver ricorsivi a monte, puoi fare riferimento alla nostra guida al debug di Pi-hole e Unbound.

Che Cos’è FTL e Perché Può Andare in Blocco

FTL (Faster Than Light) è il componente cardine di Pi-hole, introdotto per sostituire la precedente implementazione basata sul server dnsmasq tradizionale integrato via script shell. FTL è un demone compilato in C che estende dnsmasq, garantendo tempi di risposta rapidissimi alle query, interfacciamento in memoria con le blacklist e memorizzazione persistente delle statistiche delle richieste.

A differenza di un server DNS leggero e stateless, Pi-hole FTL deve gestire contemporaneamente una tabella in memoria volatile per le statistiche in tempo reale e un database persistente su disco, situato tipicamente in /etc/pihole/pihole-FTL.db. Questa complessità espone il servizio a due criticità strutturali ben note: l’integrità del database SQLite a seguito di interruzioni di corrente o usura dei supporti di memorizzazione flash, e il superamento delle soglie predefinite di query per secondo (rate limiting), che può congelare le risposte o causare deadlock nei thread del demone.

Diagnosi Preliminare: Individuare lo Stato del Servizio

Prima di applicare qualsiasi modifica ai file di configurazione, è indispensabile accertarsi se il demone sia completamente fermo, in stato di loop continuo oppure incapace di scrivere su disco. Accedi alla console del tuo server tramite SSH ed esegui i comandi diagnostici di base per raccogliere informazioni preliminari.

Verifica lo stato del demone con systemctl:

sudo systemctl status pihole-FTL.service

Se il servizio risulta failed o activating (auto-restart), esamina immediatamente gli ultimi eventi registrati nel log dedicato:

sudo tail -n 50 /var/log/pihole/FTL.log

Nei log di FTL puoi riscontrare messaggi chiari che indicano la radice dell’anomalia. Tra i più frequenti figurano:

  • FATAL: SQLite3: database disk image is malformed: indica chiaramente che il file del database a lungo termine è corrotto.
  • Rate-limiting client 192.168.1.XX for at least 60 seconds: segnala che un client ha saturato la capacità di ricezione del demone.
  • ERROR: Disk full or read-only file system: spesso indice di scheda microSD usurata o partizione di root satura al 100%.

Risoluzione della Corruzione del Database SQLite

L’integrità del database è vitale: se SQLite rileva pagine di memoria illeggibili o blocchi non coerenti dovuti a uno spegnimento improvviso del sistema (molto frequente su Raspberry Pi alimentati senza UPS), il demone rifiuta di avviarsi per prevenire ulteriori danni logici. Questo scenario rappresenta una delle origini più diffuse del crash di Pi-hole FTL.

Verifica dell’Integrità con il Client SQLite

Installa lo strumento a riga di comando per SQLite qualora non fosse presente sul sistema:

sudo apt-get update && sudo apt-get install -y sqlite3

Ferma il servizio FTL prima di operare direttamente sul file:

sudo systemctl stop pihole-FTL.service

Avvia la verifica di consistenza logica del database con il comando pragma di SQLite:

sudo sqlite3 /etc/pihole/pihole-FTL.db "PRAGMA integrity_check;"

Se l’output restituisce ok, il database è integro e la causa del guasto risiede altrove. In caso compaiano stringhe di errore con pagine orfane o descrittori malformati, è necessario intervenire per riparare il file o rigenerarlo da zero.

Tentativo di Ripristino e Dump del Database

È possibile tentare di salvare lo storico delle query estraendo i dati leggibili e rigenerando un file pulito:

  1. Crea una copia di sicurezza del file danneggiato:
    sudo mv /etc/pihole/pihole-FTL.db /etc/pihole/pihole-FTL.db.corrupted
  2. Esegui il dump verso un nuovo file database:
    sudo sqlite3 /etc/pihole/pihole-FTL.db.corrupted ".recover" | sudo sqlite3 /etc/pihole/pihole-FTL.db
  3. Assegna i corretti permessi al nuovo database in modo che il demone pihole possa leggerlo e scriverlo:
    sudo chown pihole:pihole /etc/pihole/pihole-FTL.db
sudo chmod 664 /etc/pihole/pihole-FTL.db
  4. Riavvia il servizio:
    sudo systemctl start pihole-FTL.service
Nota operativa: Se la procedura di recupero fallisce a causa di un deterioramento fisico troppo esteso del file, lascia che Pi-hole crei un database vuoto riavviando il servizio dopo aver rimosso o spostato il file corrotto. Perderai lo storico delle query passate, ma le liste di blocco, i gruppi e le regole personalizzate rimarranno intatte poiché residenti nel file gravity.db.

Gestione del Rate Limiting e Loop di Inoltro

A partire dalle versioni recenti di Pi-hole, gli sviluppatori hanno introdotto una protezione automatica contro i flood di query: di default, se un singolo client invia più di 1000 richieste nell’arco di 60 secondi, FTL rifiuta di elaborare le successive chiamate di quell’indirizzo IP finché la frequenza non scende al di sotto della soglia. Sebbene pensato come barriera difensiva, un meccanismo di rate limiting mal calibrato può innescare instabilità generalizzata fino al crash di Pi-hole FTL per esaurimento della coda di connessione.

Identificare i Loop di Inoltro (Forwarding Loops)

La causa più comune che fa scattare il rate limit non è un attacco informatico, bensì una configurazione ad anello (loop DNS). Ciò si verifica principalmente quando:

  • Hai attivato il Conditional Forwarding puntando al router principale, ma il router ha come server DNS primario l’indirizzo IP di Pi-hole stesso.
  • Un client della rete, spesso un server multimediale o un broker MQTT, non riceve una risposta immediata e tenta decine di migliaia di risoluzioni al minuto in backoff non lineare.
  • Un’istanza di Unbound a monte risponde con errori continui (SERVFAIL), costringendo Pi-hole a reiterare le richieste.

Controlla la frequenza delle chiamate analizzando i client più attivi in tempo reale:

pihole -c

Oppure controlla quali IP sono stati bloccati dal rate limiter:

sudo grep "Rate-limiting" /var/log/pihole/FTL.log

Regolare o Disattivare il Rate Limiting

Se la tua rete domestica o aziendale genera fisiologicamente picchi elevati di traffico DNS legittimo, puoi allentare le restrizioni modificando il file di configurazione /etc/pihole/pihole-FTL.conf:

sudo nano /etc/pihole/pihole-FTL.conf

Aggiungi o modifica la direttiva RATE_LIMIT definendo il numero di query ammesse e la finestra temporale in secondi (es. 2500 query ogni 60 secondi):

RATE_LIMIT=2500/60

Se desideri disattivare completamente il controllo (operazione sconsigliata a meno di test isolati), imposta i parametri a zero:

RATE_LIMIT=0/0

Salva il file con Ctrl+O, esci con Ctrl+X e applica le modifiche riavviando il demone:

sudo systemctl restart pihole-FTL.service

Ottimizzazioni Avanzate per Prevenire il Degrado

Prevenire il ripetersi di un improvviso crash di Pi-hole FTL richiede una gestione meticolosa dell’I/O del disco e della retention dei dati. Su dispositivi compatti come i single-board computer, le continue scritture sincrone sul database affaticano i controller delle memorie NAND flash, portando inevitabilmente a blocchi di sistema.

Configurare il Periodo di Conservazione (MAXDBDAYS)

Di fabbrica, Pi-hole conserva la cronologia delle query per 365 giorni. Nelle reti con molti dispositivi, il database può superare rapidamente diversi gigabyte di dimensione, rallentando le query di ricerca e consumando RAM preziosa. Nel file /etc/pihole/pihole-FTL.conf, limita la conservazione a 30 o 60 giorni:

MAXDBDAYS=30

Per compattare lo spazio occupato su disco e rimuovere i frammenti inutilizzati a seguito di cancellazioni massicce, esegui una manutenzione periodica tramite il comando vacuum:

sudo sqlite3 /etc/pihole/pihole-FTL.db "VACUUM;"

Utilizzare la RAM per i File Temporanei

Se utilizzi Raspberry Pi OS o distribuzioni Debian derivate, assicurati che la cartella /dev/shm (memoria condivisa POSIX) abbia spazio sufficiente. FTL archivia le strutture di lock e la memoria condivisa in RAM proprio per scongiurare colli di bottiglia fisici sul disco. Assicurati che il file system non sia saturato verificando con df -h /dev/shm.

Riepilogo e Buone Pratiche

Mantenere la stabilità del demone DNS richiede un monitoraggio attento delle performance di scrittura e una configurazione corretta delle relazioni tra router, client e resolver a monte. Riconoscere i sintomi della corruzione di SQLite e configurare correttamente i limiti di frequenza delle query permette di prevenire ogni forma di crash di Pi-hole FTL, garantendo una protezione solida e continuativa per tutti i dispositivi della tua rete locale.

Articoli simili