homelab-pihole-dns

Homelab Pi-hole DNS

Pi-hole est un bloqueur de publicités DNS à l'échelle du réseau qui fonctionne sur un Raspberry Pi ou tout hôte Linux. Tous les appareils de votre réseau bénéficient automatiquement du blocage des domaines publicitaires et malveillants — sans besoin d'extension de navigateur.

Quand l'utiliser

• Installer Pi-hole sur un Raspberry Pi ou un hôte Linux
• Configurer Pi-hole comme serveur DNS pour un réseau domestique
• Ajouter ou gérer des listes de blocage
• Mettre en place des résolveurs DNS-over-HTTPS (DoH) en amont
• Créer des enregistrements DNS locaux (ex. nas.home.lan, pi.home.lan)
• Résoudre les problèmes d'appareils qui perdent l'accès à Internet après l'installation de Pi-hole
• Exécuter Pi-hole en complément ou à la place du DHCP

Comment fonctionne Pi-hole

Flux normal (sans Pi-hole) :
  Appareil → requête ads.tracker.com → DNS FAI → vraie IP → publicités chargées

Avec Pi-hole :
  Appareil → requête ads.tracker.com → DNS Pi-hole → bloqué (retourne 0.0.0.0) → pas de publicité

Toutes les requêtes DNS passent d'abord par Pi-hole.
Pi-hole vérifie les listes de blocage.
Les domaines bloqués reçoivent une réponse nulle — la publicité/pisteur ne se charge jamais.
Les domaines autorisés sont transmis à votre résolveur amont (Cloudflare, Google, etc.).

Installation

Docker (Recommandé)

Docker est le moyen le plus simple d'installer Pi-hole et facilite les mises à jour et les sauvegardes.

# docker-compose.yml
services:
  pihole:
    image: pihole/pihole:<pinned-release-tag>
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"          # Administration web
    environment:
      TZ: "America/New_York"
      WEBPASSWORD: "${PIHOLE_WEBPASSWORD}"   # défini via fichier .env ou secret
      PIHOLE_DNS_: "1.1.1.1;1.0.0.1"
      DNSMASQ_LISTENING: "all"
    volumes:
      - "./etc-pihole:/etc/pihole"
      - "./etc-dnsmasq.d:/etc/dnsmasq.d"
    restart: unless-stopped
    cap_add:
      - NET_ADMIN              # nécessaire uniquement si Pi-hole sert le DHCP

Remplacez <pinned-release-tag> par une version actuelle de Pi-hole avant le déploiement. Évitez latest pour une infrastructure DNS durable afin que les mises à niveau soient délibérées et révisables.

Définissez PIHOLE_WEBPASSWORD dans un fichier .env à côté de docker-compose.yml, définissez ses permissions à 600, et gardez-le hors de git — ne mettez pas le mot de passe directement dans le fichier compose.

Accédez à l'administration web à : http://<ip-du-pi>/admin

Installation sur système nu (Raspberry Pi OS / Debian / Ubuntu)

Pi-hole nécessite une IP statique avant l'installation.

# Étape 1 : Attribuer une IP statique (éditer /etc/dhcpcd.conf sur Pi OS)
sudo nano /etc/dhcpcd.conf
# Ajoutez à la fin :
interface eth0
static ip_address=192.168.3.2/24
static routers=192.168.3.1
static domain_name_servers=192.168.3.1

# Étape 2 : Téléchargez et inspectez le programme d'installation avant de l'exécuter.
# Préférez le paquet ou le chemin d'installation documenté par Pi-hole pour votre OS/version.
curl -sSL https://install.pi-hole.net -o pi-hole-install.sh
less pi-hole-install.sh   # examinez avant de continuer

# Étape 3 : Exécutez
bash pi-hole-install.sh

# Suivez l'installateur interactif :
# 1. Sélectionnez l'interface réseau (eth0 pour filaire — recommandé)
# 2. Sélectionnez le DNS amont (Cloudflare ou laissez par défaut — modifiable plus tard)
# 3. Confirmez l'IP statique
# 4. Installez l'interface d'administration web (recommandé)
# 5. Notez le mot de passe administrateur affiché à la fin

Pointer votre réseau vers Pi-hole

# Méthode 1 : Modifier le DNS dans les paramètres DHCP de votre routeur (recommandé)
  Interface admin du routeur → Paramètres DHCP → Serveur DNS
  DNS primaire : 192.168.3.2  (IP de Pi-hole)
  DNS secondaire : laissez vide pour un blocage strict, ou utilisez un second Pi-hole.
                 Un basculement public comme 1.1.1.1 améliore la disponibilité pendant
                 le déploiement mais peut contourner le blocage car les clients peuvent l'interroger.

  Tous les appareils reçoivent Pi-hole comme DNS automatiquement lors du prochain renouvellement DHCP.
  Renouvellement forcé : reconnectez le Wi-Fi ou exécutez 'sudo dhclient -r && sudo dhclient' sur Linux

# Méthode 2 : DNS par appareil (utile pour les tests avant déploiement sur tout le réseau)
  Windows : Panneau de configuration → Carte réseau → Propriétés IPv4 → définir DNS manuellement
  macOS : Réglages système → Réseau → Détails → DNS → définir manuellement
  Linux : /etc/resolv.conf ou NetworkManager

# Méthode 3 : Pi-hole comme serveur DHCP (remplace le DHCP du routeur)
  Admin Pi-hole → Paramètres → DHCP → Activer
  Désactivez le DHCP sur votre routeur d'abord — deux serveurs DHCP sur le même réseau provoquent des conflits
  Avantage : la résolution de nom d'hôte fonctionne automatiquement (les appareils enregistrent leurs noms)

Gestion des listes de blocage

# Admin Pi-hole → Adlists → Ajouter une nouvelle adlist

# Listes de blocage recommandées :
  https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
  # par défaut — 200k+ domaines

  https://blocklistproject.github.io/Lists/malware.txt
  # domaines malveillants

  https://blocklistproject.github.io/Lists/tracking.txt
  # pistage/télémétrie

# Après avoir ajouté une liste :
  Outils → Mettre à jour Gravity  (télécharge et compile toutes les listes de blocage)

# Si un site est bloqué alors qu'il ne devrait pas l'être (faux positif) :
  Admin Pi-hole → Liste blanche → Ajouter un domaine
  Exemple : api.my-legitimate-service.com

# Vérifiez ce qui est bloqué en temps réel :
  Tableau de bord → Journal des requêtes  (flux en direct des requêtes DNS avec statut bloqué/autorisé)

DNS-over-HTTPS Amont

Le DNS-over-HTTPS chiffre vos requêtes DNS afin que votre FAI ne puisse pas voir quels sites vous résolvez.

# Installez cloudflared (proxy DoH de Cloudflare).
# Préférez le dépôt de paquets de Cloudflare pour une vérification automatique des paquets signés.
# Si vous téléchargez un binaire directement, épinglez une version et vérifiez son checksum.
CLOUDFLARED_VERSION="<pinned-version>"
curl -LO "https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/cloudflared-linux-arm64"
# Vérifiez le checksum/signature à partir des notes de version de Cloudflare avant d'installer.
sudo mv cloudflared-linux-arm64 /usr/local/bin/cloudflared
sudo chmod +x /usr/local/bin/cloudflared

# Créez la configuration cloudflared
sudo mkdir -p /etc/cloudflared
sudo tee /etc/cloudflared/config.yml << EOF
proxy-dns: true
proxy-dns-port: 5053
proxy-dns-upstream:
  - https://1.1.1.1/dns-query
  - https://1.0.0.1/dns-query
EOF

# Créez le service systemd
sudo cloudflared service install
sudo systemctl start cloudflared
sudo systemctl enable cloudflared

# Maintenant, pointez Pi-hole vers le proxy DoH local :
# Admin Pi-hole → Paramètres → DNS → DNS amont personnalisé
# Définissez sur : 127.0.0.1#5053
# Décochez tous les autres résolveurs amont

Enregistrements DNS locaux

Rendez vos services accessibles par nom (ex. nas.home.lan, grafana.home.lan).

Remarque sur le nom de domaine : .home.lan est largement utilisé dans les homelabs et fonctionne en pratique. Le suffixe réservé par l'IETF pour un usage local est .home.arpa (RFC 8375) — utilisez-le pour suivre la norme. Évitez .local pour les enregistrements DNS de Pi-hole car il entre en conflit avec mDNS/Bonjour.

# Admin Pi-hole → DNS local → Enregistrements DNS

  Domaine              IP
  nas.home.lan        192.168.30.10
  pi.home.lan         192.168.30.2
  grafana.home.lan    192.168.30.3
  proxmox.home.lan    192.168.30.4

# Depuis n'importe quel appareil de votre réseau :
  ping nas.home.lan        → 192.168.30.10
  http://grafana.home.lan  → votre tableau de bord Grafana

# Pour les sous-domaines, ajoutez un CNAME :
  Admin Pi-hole → DNS local → Enregistrements CNAME
  Domaine : portainer.home.lan → Cible : pi.home.lan

Résolution des problèmes

# Pi-hole bloque quelque chose qu'il ne devrait pas
pihole -q example.com          # Vérifiez si le domaine est bloqué et par quelle liste
pihole -w example.com          # Mettez en liste blanche immédiatement

# Le DNS ne résout pas du tout
pihole status                  # Vérifiez si pihole-FTL fonctionne
dig @192.168.3.2 google.com   # Testez le DNS directement contre Pi-hole

# Redémarrez le DNS de Pi-hole
pihole restartdns

# Consultez les journaux de requêtes pour un appareil spécifique
pihole -t                      # Suivi en direct de toutes les requêtes
# Ou filtrez par client dans le journal des requêtes de l'administration web

# Mise à jour de gravity Pi-hole (rafraîchir les listes de blocage)
pihole -g

Anti-patrons

# MAUVAIS : Dépendre d'un seul Pi-hole sans voie de récupération
# Si Pi-hole plante ou que le Pi perd de l'alimentation, le DNS peut cesser de fonctionner
# BON : Garder un basculement routeur documenté pour un retour en arrière lors de la configuration
# MEILLEUR : Exécuter deux instances de Pi-hole pour la redondance ; éviter le DNS public de secours pour un blocage strict

# MAUVAIS : Installer Pi-hole sans IP statique
# Si le Pi obtient une nouvelle IP DHCP, tous les appareils perdent le DNS
# BON : Définir l'IP statique d'abord, puis installer Pi-hole

# MAUVAIS : Activer le DHCP de Pi-hole sans désactiver d'abord le DHCP du routeur
# Deux serveurs DHCP sur le même réseau distribuent des IP conflictuelles
# BON : Désactiver le DHCP du routeur, puis activer le DHCP de Pi-hole

# MAUVAIS : Ne jamais mettre à jour gravity (listes de blocage)
# De nouveaux domaines publicitaires et malveillants s'accumulent — les listes obsolètes les manquent
# BON : Planifier une mise à jour hebdomadaire de gravity : pihole -g (ou activer dans Paramètres → API)

Bonnes pratiques

• Donnez au Pi une IP statique ou une réservation DHCP avant d'installer Pi-hole
• Utilisez Pi-hole comme DNS principal ; pour la redondance, ajoutez un second Pi-hole plutôt qu'un résolveur public si vous avez besoin d'un blocage strict
• Activez DoH (DNS-over-HTTPS) avec cloudflared pour des requêtes amont chiffrées
• Définissez home.lan comme votre domaine local et créez des enregistrements DNS pour tous vos services
• Consultez le journal des requêtes occasionnellement — les requêtes bloquées vous montrent ce que font les appareils

Compétences associées

• homelab-network-setup
• homelab-vlan-segmentation
• homelab-wireguard-vpn