Come riparare database pihole ftl corrotto e risolvere i lock file

Quando l’interfaccia web di amministrazione smette improvvisamente di mostrare le metriche di rete e le query DNS non vengono più memorizzate nella cronologia, la causa risiede spesso nel file SQLite responsabile dello storico. Sapere esattamente come riparare database pihole ftl permette di ristabilire la normale operatività del server DNS senza dover sacrificare l’intera configurazione del sistema o perdere settimane di preziosi log di telemetria.

Perché il database pihole-FTL.db si corrompe o rimane bloccato?

Il motore Pi-hole FTL (Faster Than Light) è un demone personalizzato basato su dnsmasq che memorizza ogni singola risoluzione di dominio all’interno di un database relazionale SQLite situato in /etc/pihole/pihole-FTL.db. In condizioni di forte carico o in caso di spegnimenti improvvisi dell’host (molto frequenti quando Pi-hole gira su schede Raspberry Pi alimentate in modo instabile o con memorie microSD soggette a usura), la struttura dati del file può subire gravi alterazioni logiche.

Se ti sei già scontrato con un’interruzione imprevista del servizio, avrai probabilmente notato che un crash di Pi-hole FTL può essere scatenato non soltanto da anomalie nella risoluzione dei record DNS, ma anche da un fallimento a livello di I/O nel momento in cui il thread principale tenta di scrivere nel database. SQLite gestisce l’accesso concorrente attraverso lock a livello di file: se il demone termina in modo anomalo durante una transazione, i file temporanei con estensione -shm (Shared Memory) e -wal (Write-Ahead Logging) possono rimanere pendenti, impedendo a qualsiasi istanza successiva di ottenere i permessi di scrittura esclusivi.

Un arresto anomalo durante una scrittura su microSD o disco USB non journaling è la causa primaria di corruzione degli header B-tree in SQLite, provocando errori di tipo ‘database disk image is malformed’.

Diagnosi preliminare: identificare errori di integrità e lock

Prima di compiere qualsiasi intervento distruttivo, è fondamentale esaminare i registri e interrogare direttamente il file per verificare la presenza di anomalie fisiche o logiche. È consigliabile fermare preventivamente il demone per evitare che ulteriori query peggiorino lo stato del file:

sudo systemctl stop pihole-FTL

Controlla se ci sono processi orfani che tengono ancora aperto il descrittore del file del database:

sudo lsof /etc/pihole/pihole-FTL.db

Se il comando restituisce uno o più identificativi di processo (PID) residui, puoi terminarli forzatamente con il comando kill -9 <PID>. Subito dopo, procedi alla verifica diagnostica con il client a riga di comando di SQLite:

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

Se il responso restituito è diverso da una semplice stringa contenente ok, significa che la struttura interna ha subito danni irreversibili a livello di blocchi. In questa situazione, diventa indispensabile riparare database pihole ftl estraendo le informazioni sane attraverso una procedura di recupero e ricompattamento delle tabelle.

Procedura guidata per recuperare i dati e rimuovere le anomalie

La strategia più sicura per ricostruire il database consiste nell’esportare il contenuto leggibile in formato SQL testuale grezzo, per poi ricreare da zero una nuova istanza SQLite perfettamente pulita e indicizzata. Questo approccio elimina i puntatori corrotti e rimuove lo spazio fantasma lasciato dalle transazioni incomplete.

1. Creazione di un backup preventivo

Non operare mai direttamente sul file originale senza prima averne conservato una copia speculare su un percorso sicuro:

sudo cp /etc/pihole/pihole-FTL.db /etc/pihole/pihole-FTL.db.bak
sudo cp /etc/pihole/pihole-FTL.db-wal /etc/pihole/pihole-FTL.db-wal.bak 2>/dev/null
sudo cp /etc/pihole/pihole-FTL.db-shm /etc/pihole/pihole-FTL.db-shm.bak 2>/dev/null

2. Dump e rigenerazione tramite sqlite3

Per salvare il maggior numero di record possibile e riallineare gli schemi, esegui il dump del database incanalandolo direttamente verso un nuovo file vergine. Questo passaggio costituisce il nucleo operativo necessario per riparare database pihole ftl senza perdere le metriche storiche dei client:

sudo sqlite3 /etc/pihole/pihole-FTL.db ".recover" | sudo sqlite3 /etc/pihole/pihole-FTL_recovered.db

Qualora la versione di SQLite installata sul tuo sistema operativo non dovesse supportare il comando avanzato .recover, puoi affidarti alla sintassi classica del dump SQL:

echo ".dump" | sudo sqlite3 /etc/pihole/pihole-FTL.db | sudo sqlite3 /etc/pihole/pihole-FTL_recovered.db

3. Sostituzione dei file e pulizia dei lock residui

Dopo aver verificato che il nuovo database pihole-FTL_recovered.db abbia una dimensione coerente e risponda positivamente al test di integrità (PRAGMA integrity_check;), puoi sostituire il file corrotto ed eliminare i file di lock pendenti che bloccavano l’accesso:

sudo rm -f /etc/pihole/pihole-FTL.db-wal
sudo rm -f /etc/pihole/pihole-FTL.db-shm
sudo mv /etc/pihole/pihole-FTL_recovered.db /etc/pihole/pihole-FTL.db

Configurazione dei permessi di sistema e del gruppo pihole

Una volta ricostruito il database, una delle cause più frequenti di mancato riavvio del servizio risiede nell’assegnazione errata della proprietà del file. I comandi eseguiti con privilegi di root impostano automaticamente l’utente root:root come proprietario, impedendo all’utente di sistema non privilegiato pihole di accedere in lettura e scrittura.

Per evitare che il demone fallisca subito dopo il recupero, ripristina i permessi corretti mediante il comando:

sudo chown pihole:pihole /etc/pihole/pihole-FTL.db
sudo chmod 664 /etc/pihole/pihole-FTL.db

L’assegnazione dei diritti di gruppo e utente è un requisito imprescindibile se vuoi riparare database pihole ftl in maniera permanente, garantendo che i thread interni del resolver possano creare e cancellare le memorie condivise -wal e -shm a ogni avvio e chiusura del processo.

Misure preventive per preservare l’integrità del database

Prevenire il ripetersi di corruzioni e blocchi prolungati richiede alcuni accorgimenti sistemistici che riducono l’impatto dei cicli di scrittura continui, in particolare se Pi-hole è installato su supporti di memoria flash a stato solido non industriali:

• Limitare l’intervallo di conservazione dei log: Nel file di configurazione /etc/pihole/pihole-FTL.conf, puoi impostare il parametro MAXDBDAYS=30 (o un valore inferiore) per impedire che il database cresca a dismisura, riducendo le dimensioni dei file e i tempi di lettura.
• Ottimizzare l’intervallo di commit del database: La direttiva DBINTERVAL=60 istruisce il demone a raggruppare le transazioni e scrivere su disco soltanto una volta ogni minuto anziché a ogni singola query, limitando drasticamente i rischi di lock concorrenti.
• Configurare un gruppo di continuità (UPS): L’utilizzo di un piccolo UPS dedicato al router e alla scheda di rete azzera il pericolo di blackout improvvisi, principale causa di interruzione delle transazioni SQLite.
• Abilitare la manutenzione automatica: Eseguire periodicamente una query di deframmentazione (VACUUM;) aiuta a compattare le pagine del database e a eliminare eventuali frammenti corrotti non critici.

Risoluzione dei casi estremi: creazione di un nuovo database

Se il livello di danno logico è tale da impedire perfino l’estrazione parziale con il dump di SQLite, la soluzione definitiva consiste nel ricreare da zero il file. È sufficiente arrestare il servizio, rinominare il file danneggiato e riavviare Pi-hole: il demone FTL genererà in totale autonomia un nuovo database vuoto con lo schema tabelle predefinito:

sudo systemctl stop pihole-FTL
sudo mv /etc/pihole/pihole-FTL.db /etc/pihole/pihole-FTL.db.old
sudo systemctl start pihole-FTL

Seguendo con attenzione queste istruzioni diagnostiche e di ripristino strutturale, sarai in grado di riparare database pihole ftl con la minima perdita di informazioni, ristabilendo la stabilità della tua rete domestica o aziendale e garantendo la corretta memorizzazione del filtraggio pubblicitario.

💡 Approfondimento consigliato: https://nicolacasalini.it/debug-pi-hole-e-unbound/