Homelab Pi-hole DNS

Was macht Homelab Pi-hole DNS?

Pi-hole ist ein netzwerkweiter DNS-Werbeblocker, der auf einem Raspberry Pi oder einem anderen Linux-Host läuft. Jedes Gerät in deinem Netzwerk erhält automatisch Werbe- und Malware-Domainblockierung – ohne Browsererweiterung.

Wann verwenden

• Installation von Pi-hole auf einem Raspberry Pi oder Linux-Host
• Konfiguration von Pi-hole als DNS-Server für ein Heimnetzwerk
• Hinzufügen oder Verwalten von Blocklisten
• Einrichtung von DNS-over-HTTPS (DoH) als Upstream-Resolver
• Erstellen lokaler DNS-Einträge (z.B. nas.home.lan, pi.home.lan)
• Fehlerbehebung bei Geräten, die nach der Pi-hole-Installation keinen Internetzugang mehr haben
• Betrieb von Pi-hole neben oder anstelle von DHCP

Wie Pi-hole funktioniert

Normaler Ablauf (ohne Pi-hole):
  Gerät → Anfrage ads.tracker.com → ISP-DNS → echte IP → Werbung lädt

Mit Pi-hole:
  Gerät → Anfrage ads.tracker.com → Pi-hole-DNS → blockiert (gibt 0.0.0.0 zurück) → keine Werbung

Alle DNS-Anfragen gehen zuerst durch Pi-hole.
Pi-hole prüft gegen Blocklisten.
Blockierte Domains erhalten eine Null-Antwort – die Werbung/der Tracker wird nie geladen.
Erlaubte Domains werden an deinen Upstream-Resolver weitergeleitet (Cloudflare, Google usw.).

Installation

Docker (Empfohlen)

Docker ist der einfachste Weg, Pi-hole zu installieren und macht Updates und Backups unkompliziert.

# docker-compose.yml
services:
  pihole:
    image: pihole/pihole:<pinned-release-tag>
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"          # Web-Administration
    environment:
      TZ: "America/New_York"
      WEBPASSWORD: "${PIHOLE_WEBPASSWORD}"   # über .env-Datei oder Secret setzen
      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              # nur nötig, wenn Pi-hole DHCP bedient

Ersetze <pinned-release-tag> vor dem Deployment durch eine aktuelle Pi-hole-Release-Version. Vermeide latest für langlebige DNS-Infrastruktur, damit Upgrades bewusst und überprüfbar sind.

Setze PIHOLE_WEBPASSWORD in einer .env-Datei neben docker-compose.yml, chmod sie auf 600 und halte sie aus Git heraus – setze das Passwort nicht direkt in die Compose-Datei.

Web-Administration aufrufen unter: http://<pi-ip>/admin

Bare-Metal-Installation (Raspberry Pi OS / Debian / Ubuntu)

Pi-hole benötigt vor der Installation eine statische IP.

# Schritt 1: Statische IP zuweisen (bearbeite /etc/dhcpcd.conf auf Pi OS)
sudo nano /etc/dhcpcd.conf
# Füge am Ende hinzu:
interface eth0
static ip_address=192.168.3.2/24
static routers=192.168.3.1
static domain_name_servers=192.168.3.1

# Schritt 2: Installer herunterladen und vor der Ausführung prüfen.
# Bevorzuge den Paket- oder Installationspfad, der von Pi-hole für dein OS/deine Version dokumentiert wird.
curl -sSL https://install.pi-hole.net -o pi-hole-install.sh
less pi-hole-install.sh   # vor dem Fortfahren prüfen

# Schritt 3: Ausführen
bash pi-hole-install.sh

# Folge dem interaktiven Installer:
# 1. Netzwerkschnittstelle auswählen (eth0 für kabelgebunden – empfohlen)
# 2. Upstream-DNS auswählen (Cloudflare oder Standard belassen – kann später geändert werden)
# 3. Statische IP bestätigen
# 4. Web-Administrationsoberfläche installieren (empfohlen)
# 5. Das am Ende angezeigte Admin-Passwort notieren

Netzwerk auf Pi-hole ausrichten

# Methode 1: DNS in den Router-DHCP-Einstellungen ändern (empfohlen)
  Router-Admin-Oberfläche → DHCP-Einstellungen → DNS-Server
  Primär-DNS: 192.168.3.2  (Pi-hole-IP)
  Sekundär-DNS: für strikte Blockierung leer lassen, oder einen zweiten Pi-hole verwenden.
                 Ein öffentlicher Fallback wie 1.1.1.1 verbessert die Verfügbarkeit während
                 der Einführung, kann jedoch die Blockierung umgehen, da Clients ihn abfragen können.

  Alle Geräte erhalten Pi-hole automatisch als DNS bei der nächsten DHCP-Verlängerung.
  Erzwungene Verlängerung: WLAN neu verbinden oder unter Linux 'sudo dhclient -r && sudo dhclient' ausführen

# Methode 2: Gerätespezifisches DNS (nützlich zum Testen vor der netzwerkweiten Einführung)
  Windows: Systemsteuerung → Netzwerkadapter → IPv4-Eigenschaften → DNS manuell setzen
  macOS: Systemeinstellungen → Netzwerk → Details → DNS → manuell setzen
  Linux: /etc/resolv.conf oder NetworkManager

# Methode 3: Pi-hole als DHCP-Server (ersetzt Router-DHCP)
  Pi-hole-Administration → Einstellungen → DHCP → Aktivieren
  Deaktiviere zuerst das DHCP auf deinem Router – zwei DHCP-Server im selben Netzwerk verursachen Konflikte
  Vorteil: Hostnamen-Auflösung funktioniert automatisch (Geräte registrieren ihre Namen)

Blocklisten-Verwaltung

# Pi-hole-Administration → Adlisten → Neue Adliste hinzufügen

# Empfohlene Blocklisten:
  https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
  # Standard – 200k+ Domains

  https://blocklistproject.github.io/Lists/malware.txt
  # Malware-Domains

  https://blocklistproject.github.io/Lists/tracking.txt
  # Tracking/Telemetrie

# Nach Hinzufügen einer Liste:
  Tools → Gravity aktualisieren  (lädt alle Blocklisten herunter und kompiliert sie)

# Wenn eine Seite blockiert wird, die nicht blockiert werden sollte (falsch positiv):
  Pi-hole-Administration → Whitelist → Domain hinzufügen
  Beispiel: api.my-legitimate-service.com

# Prüfen, was in Echtzeit blockiert wird:
  Dashboard → Abfrageprotokoll  (Live-DNS-Abfragestream mit Block/Erlauben-Status)

DNS-over-HTTPS Upstream

DNS-over-HTTPS verschlüsselt deine DNS-Abfragen, sodass dein ISP nicht sehen kann, welche Seiten du auflöst.

# Cloudflared installieren (Cloudflares DoH-Proxy).
# Bevorzuge Cloudflares Paket-Repository für automatische signierte Paketüberprüfung.
# Wenn du ein Binary direkt herunterlädst, pinne eine Release-Version und überprüfe seinen Prüfsumme.
CLOUDFLARED_VERSION="<pinned-version>"
curl -LO "https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/cloudflared-linux-arm64"
# Überprüfe die Prüfsumme/Signatur aus Cloudflares Release-Notizen, bevor du installierst.
sudo mv cloudflared-linux-arm64 /usr/local/bin/cloudflared
sudo chmod +x /usr/local/bin/cloudflared

# Cloudflared-Konfiguration erstellen
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

# Systemd-Dienst erstellen
sudo cloudflared service install
sudo systemctl start cloudflared
sudo systemctl enable cloudflared

# Jetzt Pi-hole auf den lokalen DoH-Proxy ausrichten:
# Pi-hole-Administration → Einstellungen → DNS → Benutzerdefinierter Upstream-DNS
# Setze auf: 127.0.0.1#5053
# Deaktiviere alle anderen Upstream-Resolver

Lokale DNS-Einträge

Mache deine Dienste über Namen erreichbar (z.B. nas.home.lan, grafana.home.lan).

Hinweis zum Domainnamen: .home.lan wird in Homelabs häufig verwendet und funktioniert in der Praxis. Das von der IETF reservierte Suffix für lokale Nutzung ist .home.arpa (RFC 8375) – verwende dies, um dem Standard zu folgen. Vermeide .local für Pi-hole-DNS-Einträge, da es mit mDNS/Bonjour kollidiert.

# Pi-hole-Administration → Lokales DNS → DNS-Einträge

  Domain              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

# Von jedem Gerät in deinem Netzwerk:
  ping nas.home.lan        → 192.168.30.10
  http://grafana.home.lan  → dein Grafana-Dashboard

# Für Subdomains einen CNAME hinzufügen:
  Pi-hole-Administration → Lokales DNS → CNAME-Einträge
  Domain: portainer.home.lan → Ziel: pi.home.lan

Fehlerbehebung

# Pi-hole blockiert etwas, das es nicht sollte
pihole -q example.com          # Prüfen, ob die Domain blockiert ist und von welcher Liste
pihole -w example.com          # Sofort whitelisten

# DNS löst überhaupt nicht auf
pihole status                  # Prüfen, ob pihole-FTL läuft
dig @192.168.3.2 google.com   # DNS direkt gegen Pi-hole testen

# Pi-hole-DNS neu starten
pihole restartdns

# Abfrageprotokolle für ein bestimmtes Gerät prüfen
pihole -t                      # Live-Ansicht aller Abfragen
# Oder nach Client im Web-Admin-Abfrageprotokoll filtern

# Pi-hole-Gravity aktualisieren (Blocklisten auffrischen)
pihole -g

Anti-Patterns

# SCHLECHT: Von einem einzelnen Pi-hole ohne Wiederherstellungspfad abhängig sein
# Wenn Pi-hole abstürzt oder der Pi die Stromversorgung verliert, kann DNS ausfallen
# GUT: Während der Einrichtung einen dokumentierten Router-Fallback für Rollback bereithalten
# BESSER: Zwei Pi-hole-Instanzen für Redundanz betreiben; öffentlichen Fallback-DNS für strikte Blockierung vermeiden

# SCHLECHT: Pi-hole ohne statische IP installieren
# Wenn der Pi eine neue DHCP-IP erhält, verlieren alle Geräte DNS
# GUT: Zuerst statische IP setzen, dann Pi-hole installieren

# SCHLECHT: Pi-hole-DHCP aktivieren, ohne zuerst das Router-DHCP zu deaktivieren
# Zwei DHCP-Server im selben Netzwerk verteilen widersprüchliche IPs
# GUT: Router-DHCP deaktivieren, dann Pi-hole-DHCP aktivieren

# SCHLECHT: Gravity (Blocklisten) nie aktualisieren
# Neue Werbe- und Malware-Domains sammeln sich an – veraltete Listen verpassen sie
# GUT: Wöchentliches Gravity-Update planen: pihole -g (oder in Einstellungen → API aktivieren)

Best Practices

• Gib dem Pi vor der Pi-hole-Installation eine statische IP oder DHCP-Reservierung
• Verwende Pi-hole als primären DNS; für Redundanz einen zweiten Pi-hole hinzufügen, anstatt einen öffentlichen Resolver, wenn du strikte Blockierung benötigst
• Aktiviere DoH (DNS-over-HTTPS) mit cloudflared für verschlüsselte Upstream-Abfragen
• Setze home.lan als deine lokale Domain und erstelle DNS-Einträge für alle deine Dienste
• Überprüfe gelegentlich das Abfrageprotokoll – blockierte Abfragen zeigen dir, was die Geräte tun

Verwandte Fähigkeiten

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