Pi-hole est un serveur DNS qui bloque la publicité et le tracking pour tous les appareils du réseau, sans rien installer sur chaque appareil individuellement. La méthode recommandée en 2026 est le déploiement en conteneur Docker via Docker Compose : plus simple à maintenir, à sauvegarder et à mettre à jour que le script d’installation curl | bash, que la documentation officielle elle-même qualifie de controversé.
L’essentiel
Image : pihole/pihole:latest (release 2026.09.0 du 19 septembre 2026, Pi-hole/FTL v6.7.1, qui corrige des failles de sécurité)
Prérequis : Docker et Docker Compose installés, port 53 libre sur l’hôte
Configuration : variable FTLCONF_webserver_api_password à définir explicitement
Fichiers Compose validés par docker compose config (Compose v5.1.3)
Vérifié le 20 septembre 2026, mis à jour le 23 septembre 2026
Prérequis
Il faut une machine Linux avec Docker et Docker Compose déjà installés. Si ce n’est pas encore le cas, la procédure complète est disponible dans notre guide d’installation de Docker sur Linux.
Deux autres conditions, propres à Pi-hole :
- Le port 53 doit être libre sur l’hôte. C’est la cause la plus fréquente d’échec au démarrage, traitée à l’étape 1.
- Comptez 10 minutes pour l’installation, davantage si le port 53 est occupé par systemd-resolved.
Étape 1 – Libérer le port 53 sur l’hôte
Sur la plupart des distributions récentes (Ubuntu, Debian avec systemd-resolved actif), le port 53 est déjà utilisé par le résolveur DNS système. Docker refusera de démarrer le conteneur avec une erreur du type bind: address already in use.
Vérifiez d’abord si le port est occupé :
# Lister les processus qui écoutent sur le port 53 (sudo affiche le nom du processus)
sudo ss -tulpn | grep ':53 '
Sans sudo, ss n’affiche pas le nom des processus des autres utilisateurs : systemd-resolved resterait invisible. L’espace après :53 écarte le port 5353, qu’Avahi occupe sur de nombreux bureaux et qui ferait croire à tort que le port 53 est pris.
Si systemd-resolved apparaît dans la sortie, désactivez son stub listener sans désactiver systemd-resolved lui-même — la résolution DNS de l’hôte continuera de fonctionner via /run/systemd/resolve/resolv.conf :
# Désactiver le stub listener de systemd-resolved (garde le service actif)
sudo sh -c 'mkdir -p /etc/systemd/resolved.conf.d && printf "[Resolve]\nDNSStubListener=no\n" | tee /etc/systemd/resolved.conf.d/no-stub.conf'
# Garder une copie du lien d'origine, puis faire pointer resolv.conf vers la configuration réelle de systemd-resolved
sudo cp -a /etc/resolv.conf /etc/resolv.conf.backup
sudo sh -c 'rm -f /etc/resolv.conf && ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf'
# Appliquer les changements
sudo systemctl restart systemd-resolved
Vérifiez que le port est libéré avant de continuer :
sudo ss -tulpn | grep ':53 '
# Aucune sortie = port libre, vous pouvez passer à l'étape 2
Étape 2 – Écrire le fichier docker-compose.yml
Créez un dossier de travail puis le fichier docker-compose.yml :
mkdir -p ~/pihole && cd ~/pihole
nano docker-compose.yml
# docker-compose.yml — Pi-hole v6 (FTL 6.7)
services:
pihole:
container_name: pihole
image: pihole/pihole:latest
ports:
- "53:53/tcp"
- "53:53/udp"
- "80:80/tcp"
environment:
TZ: 'Europe/Paris'
FTLCONF_webserver_api_password: 'changez-ce-mot-de-passe'
FTLCONF_dns_listeningMode: 'ALL'
volumes:
- './etc-pihole:/etc/pihole'
restart: unless-stopped
Le point le plus important de cette configuration, absent de la plupart des tutoriels en français encore en ligne (tous antérieurs à Pi-hole v6) : si FTLCONF_webserver_api_password n’est pas définie, Pi-hole génère un mot de passe aléatoire au démarrage et l’imprime uniquement dans les logs du conteneur. Fixez toujours cette variable vous-même, avec un mot de passe robuste.
Pour désactiver complètement le mot de passe (déconseillé sauf réseau strictement isolé) : FTLCONF_webserver_api_password: ''.
L’ancienne variable WEBPASSWORD, utilisée jusqu’à la v5, n’est plus documentée en v6 : elle n’apparaît plus dans la configuration officielle actuelle, qui ne mentionne que les variables FTLCONF_*.
Étape 3 – Démarrer le conteneur
docker compose up -d
Vérifiez le démarrage et récupérez le mot de passe si vous ne l’avez pas fixé manuellement :
docker logs pihole
# En cas de mot de passe auto-généré, une ligne du type suit :
# [i] Assigning random password: VotreMotDePasseGenere
L’interface web est accessible sur http://IP-DE-LA-MACHINE/admin.
Étape 4 – Configurer le réseau pour utiliser Pi-hole
Deux approches, selon la portée souhaitée :
Sur le routeur (recommandé) — modifiez le serveur DNS distribué par DHCP dans l’interface d’administration de votre box ou routeur, en le remplaçant par l’IP de la machine hébergeant Pi-hole. Tous les appareils du réseau sont protégés automatiquement, sans configuration individuelle.
Sur un appareil isolé — modifiez uniquement les paramètres réseau de cet appareil (IPv4 > DNS manuel) si vous ne voulez pas filtrer tout le réseau.
Étape 5 – Sécuriser l’accès à l’interface web avec Nginx Proxy Manager
Par défaut, l’interface d’administration est accessible en HTTP sur l’IP et le port du conteneur, sans certificat. Si vous avez déjà un reverse proxy sur votre serveur — Nginx Proxy Manager, par exemple — c’est le moment de lui adosser un sous-domaine dédié à Pi-hole plutôt que de mémoriser une adresse IP et un port.
Nginx Proxy Manager a lui-même besoin du port 80 de l’hôte pour fonctionner (validation des certificats Let’s Encrypt comprise). Si NPM tourne sur la même machine que Pi-hole, retirez impérativement le mappage "80:80/tcp" du fichier docker-compose.yml de Pi-hole avant de démarrer NPM, sous peine du même conflit bind: address already in use rencontré à l’étape 1. Si NPM tourne sur une autre machine du réseau, vous pouvez conserver le port 80 de Pi-hole en accès direct de secours.
Si vous êtes passé en network_mode: host (voir la section plus loin sur l’affichage des IP clients), ce même conflit se pose différemment : la section ports: n’existe plus dans le fichier, mais le port 80 de l’hôte reste occupé par Pi-hole puisque le conteneur partage directement la pile réseau de la machine. Démarrer NPM sur cette même machine provoquera le même bind: address already in use, sans qu’aucun mappage ne soit visible dans le fichier Compose de Pi-hole pour l’expliquer. Dans ce cas, faites tourner NPM sur une autre machine du réseau, ou renoncez au mode host pour cette machine si vous avez besoin d’y héberger NPM également.
Dans Nginx Proxy Manager, créez un hôte proxy pointant vers pihole (ou son IP sur le réseau Docker) sur le port 80 interne du conteneur — ce port reste accessible à NPM même sans être publié sur l’hôte, tant que les deux conteneurs partagent un réseau Docker commun. Activez le certificat SSL automatique sur l’hôte proxy.
Aller plus loin : DNS récursif local avec unbound
Par défaut, Pi-hole transmet les requêtes non bloquées à un résolveur DNS tiers (Google, Cloudflare, etc.), qui voit donc l’ensemble de votre trafic de résolution. Unbound permet à votre serveur de résoudre lui-même les noms de domaine en interrogeant directement la hiérarchie DNS, sans intermédiaire.
D’après la documentation officielle, l’installation se fait sur l’hôte (pas dans le même conteneur que Pi-hole) :
# Installer unbound sur l'hôte
sudo apt install unbound
Créez /etc/unbound/unbound.conf.d/pi-hole.conf pour l’écoute sur le port 5335, en UDP et TCP, avec validation DNSSEC activée — la configuration complète est détaillée dans le guide officiel Pi-hole sur unbound.
Point d’attention propre au déploiement Docker, non traité par la documentation officielle : Pi-hole tournant dans un conteneur, il ne peut pas joindre unbound via 127.0.0.1 — cette adresse désignerait le conteneur lui-même, pas l’hôte. Il faut soit ajouter une résolution vers l’hôte dans le fichier Compose :
extra_hosts:
- "host.docker.internal:host-gateway"
puis renseigner host.docker.internal#5335 comme serveur DNS personnalisé dans Pi-hole (Settings > DNS), soit utiliser directement l’IP de l’hôte sur le réseau Docker. Cette syntaxe host-gateway est documentée par Docker lui-même, indépendamment de Pi-hole.
Condition indispensable : la configuration du guide officiel fait écouter unbound sur 127.0.0.1 uniquement. Depuis le conteneur, host.docker.internal désigne la passerelle Docker de l’hôte (172.17.0.1 par défaut), sur laquelle unbound refuserait alors toute connexion. Ajoutez à la fin de la section server: de pi-hole.conf :
# Écouter aussi sur la passerelle Docker, même absente au démarrage
interface: 172.17.0.1
ip-freebind: yes
# Autoriser les réseaux Docker (plage 172.16.0.0/12 par défaut)
access-control: 172.16.0.0/12 allow
Vérifiez l’adresse de la passerelle avec ip -4 addr show docker0, contrôlez le fichier avec sudo unbound-checkconf, puis redémarrez unbound avec sudo systemctl restart unbound.
Avant de basculer en production, testez que votre FAI ne bloque pas les requêtes vers les serveurs racine, condition nécessaire au fonctionnement d’unbound :
dig @198.41.0.4 . NS +norec +time=3
Vérifier que tout fonctionne
Une fois le DNS du réseau ou de l’appareil pointé vers Pi-hole, confirmez que les requêtes passent bien par le conteneur. Interrogez d’abord Pi-hole sur son propre nom :
# En mode bridge, la réponse est l'IP interne du conteneur (172.x) : c'est normal
dig pi.hole @IP-DE-LA-MACHINE
En mode bridge, Pi-hole répond à pi.hole avec l’adresse de l’interface sur laquelle la requête est arrivée, c’est-à-dire celle du conteneur (172.19.0.2, par exemple) : le DNS fonctionne, mais http://pi.hole/admin reste injoignable depuis les autres appareils. Pour que pi.hole renvoie l’IP de la machine, ajoutez ces deux lignes à la section environment: du fichier Compose, en remplaçant l’adresse par la vôtre, puis relancez avec docker compose up -d :
# Faire répondre pi.hole avec l'IP de la machine plutôt que celle du conteneur
FTLCONF_dns_reply_host_force4: 'true'
FTLCONF_dns_reply_host_IPv4: '192.168.1.10'
En network_mode: host, la question ne se pose pas : la requête arrive directement sur l’interface réseau de la machine.
Puis testez le blocage sur un domaine publicitaire connu :
# Un domaine bloqué doit renvoyer 0.0.0.0 ou NXDOMAIN, pas son IP réelle
dig doubleclick.net @IP-DE-LA-MACHINE
Le tableau de bord de l’interface web (http://IP-DE-LA-MACHINE/admin) affiche en temps réel le nombre de requêtes bloquées et le taux de blocage global — c’est la confirmation la plus directe que Pi-hole traite bien le trafic du réseau.
Pourquoi les statistiques affichent une seule IP pour tout le réseau
Une fois Pi-hole en service, un défaut discret apparaît souvent dans le tableau de bord : toutes les requêtes semblent provenir d’une même adresse, du type 172.17.0.1 ou 172.18.0.1, au lieu des IP réelles de vos appareils (téléphone, ordinateur, télévision connectée). Ce comportement est confirmé par la communauté sur le forum officiel Pi-hole : en mode réseau Docker par défaut (bridge), celui utilisé par le fichier docker-compose.yml de cet article, les requêtes DNS transitent par la passerelle virtuelle du réseau Docker avant d’atteindre le conteneur, qui ne voit donc que cette passerelle, jamais l’appareil d’origine.
Le blocage publicitaire fonctionne normalement dans ce mode : seule la finesse des statistiques par appareil est affectée. Deux options si vous voulez retrouver les vraies IP clients :
Rester en bridge (recommandé pour débuter) — configuration la plus simple et la plus stable, alignée sur l’exemple de la documentation officielle. À privilégier si le détail par appareil dans les statistiques n’est pas une priorité.
Passer en network_mode: host — le conteneur partage alors directement la pile réseau de l’hôte, sans passerelle Docker intermédiaire, et les IP clients redeviennent visibles.
Attention : un cas documenté sur le forum officiel (22 janvier 2026) montre que ce mode casse la résolution DNS si FTLCONF_dns_listeningMode garde sa valeur ALL prévue pour le mode bridge. La cause n’est pas un bug inhérent au mode host, mais une valeur de configuration à changer explicitement.
La correction qui a fonctionné pour l’auteur du fil : passer FTLCONF_dns_listeningMode à 'SINGLE' et fixer FTLCONF_dns_interface sur l’interface réseau réelle de l’hôte (eth0 dans le cas le plus courant ; vérifiez la vôtre avec ip route get 1.1.1.1 — l’interface après dev).
Si vous adoptez ce mode, retirez aussi la section ports: du fichier Compose : elle devient inutile, tous les ports de l’hôte sont exposés directement.
services:
pihole:
container_name: pihole
image: pihole/pihole:latest
network_mode: host
environment:
TZ: 'Europe/Paris'
FTLCONF_webserver_api_password: 'changez-ce-mot-de-passe'
FTLCONF_dns_listeningMode: 'SINGLE'
FTLCONF_dns_interface: 'eth0'
volumes:
- './etc-pihole:/etc/pihole'
restart: unless-stopped
Remplacez eth0 par le nom réel de votre interface si elle diffère (courant sur certaines distributions ou avec un VPN actif : enp3s0, ens18…). Omettre FTLCONF_dns_interface ou laisser FTLCONF_dns_listeningMode sur ALL en mode host est la cause exacte du dysfonctionnement documenté dans ce fil.
Si vous laissez malgré tout la section ports: en place, le fichier reste valide : docker compose config l’accepte sans le moindre avertissement, vérification faite avec Docker Compose v5.1.3. L’avertissement n’arrive qu’au démarrage du conteneur, où Docker écarte ces ports avec le message Published ports are discarded when using host network mode. Rien n’est cassé, mais la section ne sert plus à rien : autant la retirer pour que le fichier dise ce qu’il fait réellement.
Aucune des deux options n’est strictement supérieure : c’est un compromis entre simplicité (bridge) et précision des statistiques (host), à trancher selon votre usage.
Le mode host a un troisième avantage, distinct des statistiques : c’est aussi la condition pour activer le serveur DHCP intégré de Pi-hole. Le protocole DHCP fonctionne par diffusion (broadcast), qui ne franchit pas la frontière du réseau bridge isolé de Docker — c’est pourquoi ce guide ne configure Pi-hole que comme serveur DNS, en changeant le DNS sur le routeur plutôt qu’en activant le DHCP de Pi-hole.
En mode host, le conteneur partage directement le réseau local de l’hôte, ce qui lève cette limite : la documentation officielle Docker Pi-hole cite le passage en network_mode: host comme la méthode la plus simple pour ça. Le dépôt officiel précise qu’il faut aussi accorder au conteneur la capacité NET_ADMIN (bloc cap_add: du fichier Compose) lorsque Pi-hole sert le DHCP.
Si vous activez le DHCP de Pi-hole, désactivez d’abord celui de votre routeur pour éviter d’avoir deux serveurs DHCP actifs sur le même réseau — une source de conflits d’adresses IP.
Pi-hole vs AdGuard Home : lequel choisir ?
Les deux outils bloquent la publicité au niveau DNS pour l’ensemble du réseau ; le choix se joue sur la philosophie plus que sur l’efficacité brute.
| Critère | Pi-hole | AdGuard Home |
|---|---|---|
| DNS chiffré (DoH/DoT) | Nécessite un outil complémentaire (cloudflared, par exemple, pour le DNS-over-HTTPS) | Intégré nativement |
| Contrôle parental | Via listes de blocage manuelles | Interrupteurs intégrés par client |
| Architecture | pihole-FTL, qui intègre le moteur DNS dérivé de dnsmasq et, depuis la v6, le serveur web | Binaire Go unique |
| Écosystème | Communauté large, listes de blocage nombreuses, DHCP éprouvé | Plus récent, configuration centralisée |
Verdict par profil : si vous gérez déjà un homelab Docker et voulez du contrôle fin sur chaque brique (DNS, DHCP, interface), Pi-hole s’intègre naturellement à une stack existante — visible dans ce même conteneur via Portainer plutôt qu’en ligne de commande. Si vous cherchez une solution unique avec chiffrement DNS prêt à l’emploi sans conteneur supplémentaire, AdGuard Home demande moins de configuration initiale.
Désinstaller / revenir en arrière
# Arrêter et supprimer le conteneur (conserve le dossier etc-pihole)
docker compose down
Pensez à restaurer le serveur DNS d’origine sur votre routeur ou vos appareils avant d’arrêter le conteneur, sous peine de perte de résolution DNS sur le réseau.
Si vous aviez désactivé le stub listener de systemd-resolved à l’étape 1, rétablissez la configuration d’origine :
sudo rm /etc/systemd/resolved.conf.d/no-stub.conf
sudo mv /etc/resolv.conf.backup /etc/resolv.conf
sudo systemctl restart systemd-resolved
Avertissement. La commande suivante efface définitivement la configuration, les listes et les statistiques de Pi-hole. Les fichiers créés par le conteneur appartiennent à root, d’où
sudo.
# Suppression complète, y compris la configuration et les statistiques
sudo rm -rf ~/pihole
Erreurs courantes
Error starting userland proxy: listen tcp4 0.0.0.0:53: bind: address already in use
Le port 53 est occupé, le plus souvent par systemd-resolved. Reprenez l’étape 1.
Mot de passe de l’interface web perdu
Régénérez-en un directement dans le conteneur :
docker exec -it pihole pihole setpassword
Plus de résolution DNS sur le réseau après un arrêt du conteneur
Si le routeur pointe exclusivement vers Pi-hole, l’arrêt du conteneur coupe toute résolution DNS pour le réseau entier. N’ajoutez pas pour autant un DNS secondaire qui ne soit pas un Pi-hole : la FAQ officielle de Pi-hole rappelle qu’il doit être le seul DNS du réseau, faute de quoi les appareils interrogent aussi l’autre serveur en temps normal et une partie des requêtes échappe au filtrage. La ligne restart: unless-stopped relance déjà le conteneur après un plantage ou un redémarrage de la machine ; pour tenir une panne de la machine elle-même, faites tourner une seconde instance Pi-hole et déclarez-la comme second DNS.
Pi-hole ne bloque pas ou peu de publicités
Le cas le plus fréquent, d’après le forum communautaire officiel de Pi-hole : l’appareil testé n’utilise pas réellement Pi-hole comme serveur DNS.
Sur Android en particulier, le « DNS privé » (Private DNS, DNS-over-HTTPS) réglé sur un fournisseur explicite dans les paramètres du téléphone contourne totalement Pi-hole, quelle que soit la configuration du routeur. Le réglage « Automatique » ne pose en principe pas ce problème, mais un fournisseur explicite (Google, Cloudflare) le pose systématiquement. Désactivez le DNS privé sur l’appareil ou repassez-le en mode automatique.
Certaines publicités intégrées au flux vidéo (YouTube en tête) restent visibles quel que soit le réglage : voir la question suivante.
FAQ
C’est quoi un Pi-hole ?
Pi-hole est un bloqueur de publicité et de traqueurs qui agit au niveau du DNS : il intercepte les requêtes de vos appareils et bloque celles qui pointent vers un domaine publicitaire connu, sans installer de logiciel sur chaque appareil. Conçu à l’origine pour Raspberry Pi, il fonctionne aujourd’hui sur toute distribution Linux, y compris en conteneur Docker.
Pi-hole vs AdGuard Home, lequel choisir ?
Pi-hole convient mieux à qui gère déjà une stack Docker et veut assembler chaque brique séparément (DNS, chiffrement, DHCP). AdGuard Home convient mieux à qui cherche une solution unique avec DNS chiffré intégré sans configuration additionnelle. Voir le comparatif détaillé plus haut.
Quel est le port par défaut de Pi-hole ?
Le port 53 (TCP et UDP) pour le service DNS, et le port 80 pour l’interface web d’administration. Le port 443 (HTTPS, avec un certificat auto-signé généré par Pi-hole) n’est joignable que si vous le publiez dans le fichier Compose, comme le fait l’exemple du dépôt officiel.
Peut-on utiliser Pi-hole sur Raspberry Pi ?
Oui, c’est la plateforme d’origine de Pi-hole. L’installation en Docker Compose décrite dans cet article fonctionne à l’identique sur Raspberry Pi OS (architecture ARM prise en charge par l’image officielle).
Pi-hole bloque-t-il les publicités YouTube ?
Pas de façon fiable. Un bloqueur DNS agit sur des domaines entiers, or YouTube sert ses publicités depuis les mêmes domaines que ses vidéos. Le dépôt officiel d’AdGuard Home, autre bloqueur DNS, range d’ailleurs les publicités YouTube parmi ce qu’un filtrage DNS ne peut pas bloquer.
Peut-on utiliser le serveur DHCP intégré de Pi-hole avec cette configuration Docker Compose ?
Non sans adaptation. Le serveur DHCP de Pi-hole a besoin de diffuser des paquets broadcast sur le réseau local, ce que le mode bridge par défaut utilisé dans cet article ne permet pas nativement — c’est pourquoi ce guide configure Pi-hole uniquement comme serveur DNS, en changeant le DNS sur votre routeur plutôt qu’en activant le DHCP de Pi-hole. Pour activer le DHCP, il faut soit passer en network_mode: host (voir la section sur les IP clients plus haut), soit utiliser un réseau Docker de type macvlan, une configuration plus avancée non couverte ici.
Quelles sont les alternatives à Pi-hole ?
AdGuard Home est la plus citée, avec un DNS chiffré natif. Technitium DNS Server est une autre option, orientée serveur DNS complet plutôt que blocage publicitaire pur.
Quel est le meilleur bloqueur de pub DNS ?
Il n’y a pas de réponse universelle : Pi-hole et AdGuard Home bloquent tous deux la publicité avec une efficacité comparable au niveau DNS. Le choix dépend de vos besoins (voir le comparatif plus haut), pas d’une différence de performance brute entre les deux.
Pourquoi les statistiques Pi-hole affichent-elles une seule IP pour tous mes appareils ?
C’est un effet du mode réseau Docker « bridge » utilisé par défaut : les requêtes transitent par la passerelle du réseau Docker avant d’atteindre Pi-hole, qui ne voit donc que cette passerelle. Voir la section dédiée plus haut pour la solution en mode host.
Conclusion
Docker Compose reste la méthode la plus simple à maintenir pour Pi-hole : une mise à jour tient en une commande (docker compose pull && docker compose up -d), la configuration entière vit dans deux fichiers versionnables, et la suppression ne laisse aucune trace résiduelle sur le système hôte. Le seul piège propre à la v6 à ne jamais oublier est la variable FTLCONF_webserver_api_password : sans elle, le mot de passe est généré aléatoirement et n’existe que dans les logs du conteneur. Si votre image date d’avant le 19 septembre 2026, mettez-la à jour dès maintenant : la release 2026.09.0 (FTL v6.7.1) corrige plusieurs failles de sécurité, dont trois classées élevées.
Une fois Pi-hole en place, la suite logique est de l’exposer proprement via Nginx Proxy Manager plutôt que de mémoriser une IP et un port, puis d’envisager unbound si la dépendance à un résolveur DNS tiers vous gêne.
Comment ces commandes ont été vérifiées
| Élément | Niveau | Vérification |
|---|---|---|
Fichier docker-compose.yml du mode bridge |
Testé | docker compose config (Docker Compose v5.1.3, 20/09/2026) : fichier accepté, les trois mappages de ports (53/tcp, 53/udp, 80/tcp) et les trois variables d’environnement correctement interprétés |
Fichier docker-compose.yml du mode host |
Testé | docker compose config : fichier accepté, network_mode: host, FTLCONF_dns_listeningMode: SINGLE et FTLCONF_dns_interface: eth0 correctement interprétés |
Comportement de ports: laissé en network_mode: host |
Testé (validation) | docker compose config ne produit aucun avertissement et conserve la section. L’écartement effectif des ports au démarrage est, lui, conforme à docs.docker.com/engine/network/drivers/host/, non exécuté ici |
Syntaxe extra_hosts: "host.docker.internal:host-gateway" |
Testé (syntaxe) | Bloc greffé dans le fichier Compose et validé par docker compose config |
ip route get 1.1.1.1 pour trouver l’interface |
Testé | Exécutée : renvoie une ligne du type 1.1.1.1 via … dev eth0 src … ; l’extraction du champ après dev fonctionne |
sudo ss -tulpn | grep ':53 ' |
Testé | Écoute ouverte sur 127.0.0.53:53 : détectée, avec le nom du processus. Port libre : aucune sortie. Écoute sur le port 5353 : non détectée. Contre-épreuve : sans sudo, le nom du processus n’apparaît pas, et l’ancien filtre grep :53 signalait aussi le port 5353 (corrigé le 23/09/2026) |
Contenu écrit par le printf du fichier no-stub.conf |
Testé | Commande exécutée puis fichier relu avec od -c : contient exactement [Resolve], saut de ligne, DNSStubListener=no, saut de ligne — les \n sont bien des retours à la ligne réels |
Variables FTLCONF_webserver_api_password, FTLCONF_dns_listeningMode, TZ |
Conforme à la documentation officielle | docs.pi-hole.net/docker/configuration/, consulté le 20/09/2026 |
| Procédure de désactivation du stub listener systemd-resolved | Conforme à la documentation officielle | docs.pi-hole.net/docker/tips-and-tricks/, consulté le 20/09/2026 |
| Installation et configuration d’unbound | Conforme à la documentation officielle | docs.pi-hole.net/guides/dns/unbound/, consulté le 20/09/2026 |
Syntaxe extra_hosts: host-gateway |
Conforme à la documentation officielle Docker | docs.docker.com, référence Compose, consulté le 20/09/2026 |
docker exec pihole pihole setpassword |
Conforme à la documentation officielle | docs.pi-hole.net/main/pihole-command/, consulté le 20/09/2026 |
| Comportement du mode bridge sur les IP clients affichées | Conforme à une réponse communautaire sur le forum officiel Pi-hole (utilisateur Bucking_Horn, non membre de l’équipe) | discourse.pi-hole.net/t/no-client-ip-addresses-showing-in-pihole/39564, consulté le 20/09/2026 |
Cause et correctif du DNS cassé en network_mode: host (FTLCONF_dns_listeningMode: SINGLE + FTLCONF_dns_interface) |
Conforme à une résolution communautaire documentée sur le forum officiel Pi-hole | discourse.pi-hole.net/t/broken-dns-with-network-mode-host/84669 (22/01/2026), consulté le 20/09/2026 |
Valeurs autorisées de FTLCONF_dns_listeningMode (ALL en bridge) |
Conforme à la documentation officielle | github.com/pi-hole/docker-pi-hole README, consulté le 20/09/2026 |
| Limite du DHCP Pi-hole en mode bridge par défaut (nécessite host ou macvlan) | Conforme à la documentation officielle | docs.pi-hole.net/docker/dhcp/, consulté le 20/09/2026 |
| Contournement de Pi-hole par le DNS privé Android (DoH) | Conforme au forum officiel Pi-hole | discourse.pi-hole.net/t/doh-private-dns-on-android-phones/72751, consulté le 20/09/2026 |
Unbound joignable depuis Docker (interface: 172.17.0.1, ip-freebind, access-control) |
Testé (partiellement) | Configuration du guide officiel seule : unbound répond sur 127.0.0.1 et refuse la connexion sur 172.17.0.1. Avec l’ajout : fichier validé par unbound-checkconf, écoute effective sur 172.17.0.1. Requête réelle depuis un conteneur Pi-hole non testée (23/09/2026) |
Sauvegarde puis restauration du lien /etc/resolv.conf (cp -a, puis mv) |
Testé | Exécuté sur un lien symbolique équivalent : la copie conserve le lien d’origine, la restauration le rétablit (23/09/2026) |
| Pi-hole seul DNS du réseau, sans DNS secondaire non filtrant | Conforme à la FAQ officielle | discourse.pi-hole.net/t/how-do-i-configure-my-devices-to-use-pi-hole-as-their-dns-server/245, consulté le 23/09/2026 |
Release 2026.09.0 (FTL v6.7.1), capacité NET_ADMIN pour le DHCP |
Conforme aux sources officielles | Notes de version et README de github.com/pi-hole/docker-pi-hole, consultés le 23/09/2026 |
Réponse de pi.hole en mode bridge (IP du conteneur) et variables FTLCONF_dns_reply_host_force4 / FTLCONF_dns_reply_host_IPv4 |
Conforme à la documentation officielle ; syntaxe testée | docs.pi-hole.net/ftldns/configfile (section dns.reply.host) et deux cas résolus sur discourse.pi-hole.net (mars et juillet 2025). Fichier Compose complété validé par docker compose config (23/09/2026). Réponse réelle d’un conteneur non testée |
Ce qui n’a pas été exécuté. Les éléments marqués « conforme à la documentation officielle » (démarrage du conteneur et mot de passe aléatoire dans les logs, pihole setpassword, commandes dig de la section de vérification, blocage publicitaire effectif, statistiques et IP clients, intégration Nginx Proxy Manager) suivent la documentation officielle et les sources citées, sans avoir été exécutés sur une installation réelle pour cet article.
La commande dig @198.41.0.4 . NS +norec +time=3 n’a pas pu être validée par un test : son résultat dépend de votre fournisseur d’accès. Exécutez-la sur votre propre machine avant de passer à unbound.
Les éléments marqués « testé » l’ont été sur le code exact publié dans cet article. La validation docker compose config a par ailleurs été contrôlée sur un fichier volontairement invalide, qu’elle rejette bien : les fichiers acceptés le sont donc pour une vraie raison.
Versions : tests exécutés le 20 septembre 2026 avec Docker 29.4.3 et Docker Compose v5.1.3, sur la base de Pi-hole/FTL 6.7 (release 2026.07.2). Article mis à jour le 23 septembre 2026 pour la release 2026.09.0 (FTL v6.7.1) et pour les corrections signalées dans ce tableau.
