Restaurer Pi-hole depuis une sauvegarde

Méthode 1 : Restauration depuis Borg UI

Cette procédure s’applique à une stack Pi-hole v6 sauvegardée via Borg UI, avec :

• un script pre-backup qui déclenche l’export natif Teleporter (pihole-FTL --teleporter), produisant une archive zip cohérente contenant la configuration (pihole.toml) et le contenu de la base de blocage (gravity.db), sans jamais lire les fichiers SQLite live directement ;
• une source Borg couvrant cet export ainsi que le dossier dnsmasq.d (configuration DNS personnalisée statique).

Étapes de restauration

#

1. Arrêter la stack Pi-hole

#

cd /home/olivier/stacks/pihole
docker compose down

2. Restaurer l’archive vers un dossier temporaire

#

Dans Borg UI : Archives → sélectionnez le repository Pi-hole → choisissez l’archive voulue → Restore vers un dossier temporaire :

/local/restore-pihole

3. Redémarrer Pi-hole avec sa configuration existante

#

Contrairement à Nextcloud/Immich/Vaultwarden, il n’est pas nécessaire d’écraser le dossier data (/etc/pihole) avant de redémarrer : le Teleporter s’importe après coup, via l’interface web, sur une instance Pi-hole déjà démarrée (même une installation fraîche).

docker compose up -d

Remettez en place dnsmasq.d si nécessaire :

cp -a /home/olivier/backups/.../restore-pihole/local/pihole/dnsmasq.d/* \
      /home/olivier/stacks/pihole/dnsmasq.d/
docker compose restart pihole

4. Importer l’archive Teleporter via l’interface web

#

Connectez-vous à https://pihole.colmaris.fr, allez dans Settings → Teleporter, section Restore, et téléversez le fichier pihole-teleporter-latest.zip récupéré à l’étape 2.

5. Vérifier que tout fonctionne

#

Vérifiez que vos listes de blocage personnalisées, vos exceptions (whitelist/blacklist) et vos réglages DNS amont sont bien de retour. Testez une résolution DNS depuis un appareil du réseau, et vérifiez qu’un domaine publicitaire connu est bien bloqué.

Points critiques à retenir

#

• Le Teleporter ne restaure pas l’historique de requêtes — c’est normal, ce n’est pas son rôle.
• L’import se fait après le démarrage, pas avant — contrairement aux autres stacks où on remet les fichiers en place puis on démarre.
• dnsmasq.d reste un dossier de fichiers bruts : une simple copie suffit, pas de traitement particulier.
• Testez cette procédure au moins une fois « à froid » avant d’en avoir besoin en situation réelle.

Pour un crash total (serveur détruit, Borg UI indisponible), consultez Restaurer Pi-hole sans Borg UI.

Restauration en mode dégradé (sans borgui)

#

Cette procédure s’applique quand Borg UI lui-même n’est plus disponible : serveur détruit, disque mort, tout scénario où vous repartez d’une machine vierge. Elle utilise uniquement le CLI Borg.

Pour une restauration simple (Borg UI toujours fonctionnel), consultez Restaurer Pi-hole depuis une sauvegarde Borg UI.

Prérequis indispensables

#

1. La passphrase du repository Borg, stockée en dehors du serveur.
2. Le docker-compose.yml et le .env de la stack Pi-hole, versionnés séparément (dépôt Git privé).
3. L’emplacement du repository (chemin local, hôte SSH, ou remote cloud).

Étapes de restauration

#

1. Préparer la nouvelle machine

#

sudo apt update
sudo apt install -y borgbackup

2. Récupérer l’accès au repository

#

export BORG_REPO=/chemin/ou/ssh/vers/le/repo/pihole
export BORG_PASSPHRASE='votre-passphrase-ici'

borg list "$BORG_REPO"

3. Extraire l’archive

#

mkdir -p /home/olivier/restore-pihole
cd /home/olivier/restore-pihole
borg extract "$BORG_REPO"::NOM-DE-L-ARCHIVE

Vous récupérez local/pihole/teleporter/pihole-teleporter-latest.zip et local/pihole/dnsmasq.d/.

4. Reconstituer la stack Pi-hole

#

mkdir -p /home/olivier/stacks/pihole
cd /home/olivier/stacks/pihole
# Récupérez ici votre docker-compose.yml et votre .env
mkdir -p data dnsmasq.d teleporter
cp -a /home/olivier/restore-pihole/local/pihole/dnsmasq.d/* ./dnsmasq.d/

5. Démarrer Pi-hole

#

docker compose up -d

Une installation fraîche de Pi-hole démarre avec une configuration par défaut — c’est normal, l’étape suivante la remplace.

6. Importer l’archive Teleporter

#

Connectez-vous à l’interface web de Pi-hole (attention : sur un nouveau serveur, l’adresse IP a peut-être changé — vérifiez votre configuration Traefik/DNS), puis Settings → Teleporter → Restore, et téléversez pihole-teleporter-latest.zip.

Pour un restore scriptable sans interface web, utilisez pihole_restore.

7. Mettre à jour la résolution DNS du réseau

#

Si l’adresse IP du nouveau serveur diffère de l’ancienne, mettez à jour la configuration DNS de votre routeur/box pour pointer vers la nouvelle IP de Pi-hole.

8. Réinstaller Borg UI et reconfigurer les Backup Plans

#

Une fois Pi-hole vérifié et fonctionnel, redéployez Borg UI et reconfigurez le Backup Plan Pi-hole.

Points critiques à retenir

#

• La passphrase Borg est le point de défaillance numéro un — stockez-la en dehors du serveur qu’elle protège.
• docker-compose.yml et .env ne sont pas dans la sauvegarde Borg — prévoyez un dépôt Git privé séparé.
• Coupure DNS pendant la restauration : prévoyez un DNS de secours temporaire pour le réseau.
• Testez cette procédure de bout en bout au moins une fois, idéalement sur une VM isolée.