Pi-hole est un resolveur DNS filtrant qui bloque la publicite, les traqueurs et de nombreux domaines malveillants pour tous les appareils du reseau, sans rien installer sur les clients. Le filtrage se faisant au niveau DNS, il protege aussi bien le PC que le smartphone, la TV connectee ou les objets domotiques.
La version Pi-hole v6 (2025) a tout modernise : le serveur web et l’API REST sont desormais integres au binaire pihole-FTL (fini lighttpd et PHP), la configuration est centralisee dans un unique fichier TOML, la CLI a ete clarifiee (pihole allow / pihole deny) et l’interface a ete entierement repensee. Dans cet article, on deploie Pi-hole sur Debian, sans Docker, entierement en ligne de commande, puis on le configure, on le tune et on optimise les listes de blocage.
1. Le principe : un « trou noir » DNS
Quand un appareil veut joindre ads.exemple.com, il demande d’abord l’adresse IP a son serveur DNS. Si ce serveur est Pi-hole et que le domaine figure dans une liste de blocage, Pi-hole repond « adresse inexistante » : la connexion publicitaire n’a jamais lieu. C’est le principe du DNS sinkhole.
Les nouveautes marquantes de la v6 :
- Serveur web + API REST embarques dans
pihole-FTL(empreinte reduite, interface plus rapide). - Configuration unifiee dans
/etc/pihole/pihole.toml(richement commente). - Listes d’autorisation abonnees (« Antigravity ») : des listes qui autorisent des domaines, en complement des listes de blocage.
- Interface Basic / Expert et HTTPS natif (certificats auto-generes ou fournis).
2. Prerequis
- Une Debian 12 ou 13 a jour, dediee a Pi-hole (machine physique, VM ou LXC).
- Une adresse IP fixe : c’est indispensable, puisque tous les clients pointeront vers cette IP pour leur DNS.
Exemple d’IP statique via /etc/network/interfaces (ici la machine sera en 192.168.1.2, passerelle 192.168.1.1) :
auto eth0
iface eth0 inet static
address 192.168.1.2/24
gateway 192.168.1.1
dns-nameservers 1.1.1.1
On met ensuite le systeme a jour et on installe curl :
sudo apt update && sudo apt full-upgrade -y sudo apt install -y curl
3. Installation en ligne de commande
Pi-hole fournit un installeur officiel. La methode la plus directe :
curl -sSL https://install.pi-hole.net | bash
Si vous preferez inspecter le script avant de l’executer (bonne pratique) :
wget -O install-pihole.sh https://install.pi-hole.net less install-pihole.sh sudo bash install-pihole.sh
L’assistant en mode texte vous fait choisir : l’interface reseau, le resolveur amont (Cloudflare, Quad9, Google…), une premiere liste de blocage (StevenBlack par defaut), l’activation de l’interface web et de l’API, et le niveau de journalisation. A la fin, l’installeur affiche l’URL d’administration et un mot de passe genere aleatoirement.
On (re)definit un mot de passe a soi et on verifie l’etat du service :
# Definir le mot de passe de l'interface web/API pihole setpassword # Etat et versions pihole status pihole version
4. Premier acces a l’interface web
L’interface est servie directement par pihole-FTL sur le port 80 :
# Tableau de bord http://192.168.1.2/admin
Si le port 80 etait deja pris, Pi-hole bascule automatiquement sur le 8080 (http://192.168.1.2:8080/admin). On se connecte avec le mot de passe defini plus haut. Le tableau de bord donne en un coup d’oeil le nombre de requetes, le pourcentage bloque, le top des domaines et des clients.
Vue d’ensemble du tableau de bord Pi-hole v6 (illustration).
La v6 propose un mode Basic (l’essentiel) et un mode Expert (tous les reglages), via le selecteur en haut a droite des Settings.
5. Configuration en ligne de commande
La configuration peut se faire de cinq facons : en editant le fichier TOML, via la CLI pihole-FTL --config, via l’API, via l’interface web (qui utilise l’API), ou via des variables d’environnement (surtout utiles en conteneur). Quelques reglages frequents en une ligne :
# Activer la validation DNSSEC pihole-FTL --config dns.dnssec true # Repondre aux requetes venant de TOUS les sous-reseaux (VLAN, VPN...) pihole-FTL --config dns.listeningMode ALL # Appliquer pihole restartdns
Le mode d’ecoute ALL est indispensable si Pi-hole doit repondre a des clients situes sur un autre sous-reseau (VLAN, clients d’un VPN, etc.) : par defaut il n’ecoute que son reseau local directement attache.
L’ensemble des reglages vit dans /etc/pihole/pihole.toml. Voici un extrait typique (resolveurs amont, DNSSEC, cache, et conditional forwarding pour resoudre les noms d’hotes locaux de la box) :
[dns]
upstreams = ["9.9.9.9", "149.112.112.112"] # Quad9
dnssec = true
listeningMode = "ALL"
# Resolution des noms locaux via la box (reseau, IP de la box, domaine local)
revServers = ["true,192.168.1.0/24,192.168.1.1,lan"]
[dns.cache]
size = 10000
[webserver]
port = "80o,443os" # 80 HTTP + 443 HTTPS (o = ouvert/redirige)
[database]
maxDBdays = 30 # retention de l'historique des requetes (jours)
Apres une edition manuelle du fichier, on recharge la configuration :
sudo systemctl restart pihole-FTL
6. Pointer vos clients vers Pi-hole
Pour que tout le reseau en profite, le plus simple est de declarer l’IP de Pi-hole comme serveur DNS distribue par le DHCP de votre box/routeur (champ « DNS primaire » = 192.168.1.2). Evitez de laisser en plus le DNS de la box : sinon les clients pourraient le contourner.
Alternative : laisser Pi-hole jouer le role de serveur DHCP (on desactive alors celui de la box). C’est l’option la plus fiable pour que chaque client soit bien identifie nommement dans les statistiques. Cela s’active dans Settings, DHCP ou dans la section [dhcp] du TOML.
On verifie depuis un poste client que Pi-hole repond bien et bloque :
# Doit renvoyer une reponse depuis 192.168.1.2 nslookup pi-hole.net 192.168.1.2 # Un domaine publicitaire connu doit etre bloque (reponse 0.0.0.0 ou NXDOMAIN) nslookup doubleclick.net 192.168.1.2
7. Optimiser les listes de blocage
Les listes (adlists) sont compilees par gravity dans une base unique. Pi-hole part avec la liste StevenBlack. Plutot que d’empiler des dizaines de listes (doublons, faux positifs, RAM consommee), mieux vaut quelques listes curatees et maintenues. Bons choix complementaires : OISD et HaGeZi.
Ajout depuis l’interface : Lists, Add a new adlist, on colle l’URL puis on lance Update Gravity (Tools).
Gestion des adlists abonnees dans l’interface (illustration).
En ligne de commande, on insere les listes dans la base gravity.db via le SQLite embarque, puis on recompile gravity :
pihole-FTL sqlite3 /etc/pihole/gravity.db "INSERT OR IGNORE INTO adlist (address, comment) VALUES ('https://big.oisd.nl', 'OISD Big');"
pihole-FTL sqlite3 /etc/pihole/gravity.db "INSERT OR IGNORE INTO adlist (address, comment) VALUES ('https://raw.githubusercontent.com/hagezi/dns-blocklists/main/hosts/pro.txt', 'HaGeZi Pro');"
# Telecharger et compiler les listes
pihole -g
Pour gerer les faux positifs, on autorise des domaines (allowlist) ou on bloque finement par expression reguliere :
# Autoriser un domaine injustement bloque pihole allow discovery.meethue.com # Bloquer tout un domaine et ses sous-domaines (wildcard/regex) pihole deny --regex "(\.|^)tracker-exemple\.com$" # Verifier dans quelles listes se trouve un domaine pihole query doubleclick.net
Enfin, la v6 permet de creer des groupes (Groups) et d’y rattacher des clients (Clients) pour appliquer des listes differentes selon les appareils : par exemple un groupe « enfants » avec une liste de controle parental, sans l’imposer au reste du foyer.
8. Tuning et performances
Quelques reglages utiles, a poser dans le TOML (section indiquee) :
[dns]
# Limitation anti-abus : par defaut 1000 requetes / 60 s par client.
# Un client tres actif (ou un autre resolveur derriere) peut etre bride :
# augmentez, ou mettez count = 0 pour desactiver.
[dns.rateLimit]
count = 1000
interval = 60
[dns.cache]
size = 10000 # taille du cache DNS (entrees)
[database]
maxDBdays = 30 # moins de retention = base plus legere
Cote vie privee/journalisation, le niveau de log des requetes est ajustable (de « tout journaliser » a l’anonymisation). On peut aussi vider les logs a la demande :
# Statistiques temps reel et flux en direct pihole -c pihole -t # Purger le journal des requetes pihole flush
9. Bonus : resolution recursive avec unbound
Pour ne plus dependre d’un resolveur tiers (Google, Cloudflare…) et gagner en confidentialite, on peut faire de Pi-hole un resolveur recursif grace a unbound tournant en local :
sudo apt install -y unbound # unbound ecoute en local sur le port 5335 (voir la doc Pi-hole pour le fichier de conf) sudo systemctl enable --now unbound
Il suffit ensuite de definir 127.0.0.1#5335 comme unique resolveur amont de Pi-hole :
pihole-FTL --config dns.upstreams '["127.0.0.1#5335"]' pihole restartdns
10. Maintenance, sauvegarde et mise a jour
Pi-hole installe une tache cron qui met a jour gravity automatiquement chaque semaine. Pour le reste :
# Mettre a jour Pi-hole (core, web, FTL) pihole -up # Sauvegarde complete de la configuration (Teleporter) -> archive .zip pihole-FTL --teleporter
L’archive Teleporter se restaure depuis Settings, Teleporter dans l’interface : pratique pour migrer ou repartir d’un etat propre.
11. Points de vigilance
- IP fixe obligatoire : si l’IP de Pi-hole change, tout le reseau perd la resolution DNS.
- Point unique de defaillance : un seul Pi-hole = plus de DNS s’il tombe. Prevoyez un second resolveur (2e Pi-hole, ou DNS secondaire fiable) cote DHCP.
- Ne pas exposer le port 53 sur Internet : avec
listeningMode = ALL, le DNS repond largement ; gardez-le derriere votre pare-feu (resolveur ouvert = abus/amplification). - Un seul DNS sur les clients : ne laissez pas le DNS de la box en secondaire, sinon le filtrage est contourne.
- Listes : la qualite avant la quantite : trop de listes = faux positifs et maintenance penible.
- Rate limiting : si un client legitime est bride (1000 req/60 s par defaut), ajustez la section
[dns.rateLimit].
12. Recapitulatif des commandes
# Installation curl -sSL https://install.pi-hole.net | bash pihole setpassword # Configuration pihole-FTL --config dns.dnssec true pihole-FTL --config dns.listeningMode ALL pihole restartdns # Listes pihole -g # recompiler gravity pihole allow exemple.com # autoriser pihole deny pub.exemple.com # bloquer pihole query doubleclick.net # ou est bloque ce domaine ? # Exploitation pihole status pihole -t # flux des requetes en direct pihole disable 10m # desactiver 10 min pihole -up # mise a jour pihole-FTL --teleporter # sauvegarde
Conclusion
En une poignee de commandes, Pi-hole transforme une petite Debian en filtre DNS pour tout le reseau, sans Docker ni dependance lourde. La v6 simplifie nettement l’exploitation : configuration centralisee dans un seul fichier TOML, CLI lisible, interface moderne et API REST. Avec quelques listes bien choisies, un peu de tuning (cache, retention, rate limit) et, en bonus, unbound pour la resolution recursive, vous obtenez une solution sobre, rapide et entierement maitrisee — ideale a scripter via Ansible pour un deploiement reproductible.