Homelab Pi-hole DNS

Was macht Homelab Pi-hole DNS?

Pi-hole ist ein netzwerkweiter DNS-Werbeblocker, der auf einem Raspberry Pi oder einem beliebigen Linux-Host läuft. Alle Geräte in Ihrem Netzwerk werden automatisch vor Werbe- und Malware-Domains geschützt – ohne Browsererweiterung.

Wann verwenden

• Installieren von Pi-hole auf einem Raspberry Pi oder Linux-Host
• Konfigurieren von Pi-hole als DNS-Server für ein Heimnetzwerk
• Hinzufügen oder Verwalten von Blocklisten
• Einrichten 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
• Betreiben von Pi-hole zusammen mit oder anstelle von DHCP

Wie Pi-hole funktioniert

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

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 durchlaufen zuerst Pi-hole.
Pi-hole prüft gegen Blocklisten.
Blockierte Domains erhalten eine Null-Antwort – der Werbe-/Tracker-Server wird nie geladen.
Erlaubte Domains werden an Ihren 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-Admin
    environment:
      TZ: "Europe/Berlin"
      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 erforderlich, wenn Pi-hole DHCP bereitstellt

Ersetzen Sie <pinned-release-tag> durch ein aktuelles Pi-hole-Release-Tag vor dem Bereitstellen. Vermeiden Sie latest für langlebige DNS-Infrastruktur, damit Upgrades bewusst und überprüfbar sind.

Setzen Sie PIHOLE_WEBPASSWORD in einer .env-Datei neben docker-compose.yml, setzen Sie deren Berechtigungen auf 600 und halten Sie sie aus Git heraus – geben Sie das Passwort nicht direkt in die Compose-Datei.

Web-Admin 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 vergeben (/etc/dhcpcd.conf auf Pi OS bearbeiten)
sudo nano /etc/dhcpcd.conf
# Am Ende hinzufügen:
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: Installationsskript herunterladen und prüfen, bevor Sie es ausführen.
# Bevorzugen Sie den Paket- oder Installationspfad, der von Pi-hole für Ihr OS/Ihre Version dokumentiert ist.
curl -sSL https://install.pi-hole.net -o pi-hole-install.sh
less pi-hole-install.sh   # vor der Ausführung prüfen

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

# Dem interaktiven Installer folgen:
# 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-Admin-Oberfläche installieren (empfohlen)
# 5. Das angezeigte Admin-Passwort notieren

Netzwerk auf Pi-hole ausrichten

# Methode 1: DNS in den Router-DHCP-Einstellungen ändern (empfohlen)
  Router-Admin-UI → DHCP-Einstellungen → DNS-Server
  Primärer DNS: 192.168.3.2  (Pi-hole-IP)
  Sekundärer DNS: für striktes Blockieren leer lassen oder eine zweite Pi-hole-Instanz verwenden.
                 Ein öffentlicher Fallback wie 1.1.1.1 verbessert die Verfügbarkeit während des
                 Rollouts, kann aber das Blockieren umgehen, da Clients ihn abfragen könnten.

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

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

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

Blocklisten-Verwaltung

# Pi-hole-Admin → Adlists → Neue Adlist 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 dem 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-Admin → Whitelist → Domain hinzufügen
  Beispiel: api.my-legitimate-service.com

# In Echtzeit prüfen, was blockiert wird:
  Dashboard → Abfragelog  (Live-DNS-Abfragestream mit Block/Allow-Status)

DNS-over-HTTPS-Upstream

DNS-over-HTTPS verschlüsselt Ihre DNS-Anfragen, sodass Ihr ISP nicht sehen kann, welche Seiten Sie auflösen.

# Cloudflared (Cloudflares DoH-Proxy) installieren.
# Bevorzugen Sie Cloudflares Paket-Repository für automatische, signierte Paketüberprüfung.
# Wenn Sie ein Binärpaket direkt herunterladen, fixieren Sie eine Release-Version und prüfen Sie die Prüfsumme.
CLOUDFLARED_VERSION="<pinned-version>"
curl -LO "https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/cloudflared-linux-arm64"
# Überprüfen Sie die Prüfsumme/Signatur aus Cloudflares Release-Notizen, bevor Sie installieren.
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

# Pi-hole nun auf den lokalen DoH-Proxy ausrichten:
# Pi-hole-Admin → Einstellungen → DNS → Benutzerdefinierter Upstream-DNS
# Auf: 127.0.0.1#5053 setzen
# Alle anderen Upstream-Resolver deaktivieren

Lokale DNS-Einträge

Machen Sie Ihre Dienste per Name 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 Verwendung ist .home.arpa (RFC 8375) – verwenden Sie dieses, um dem Standard zu folgen. Vermeiden Sie .local für Pi-hole-DNS-Einträge, da es mit mDNS/Bonjour kollidiert.

# Pi-hole-Admin → 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 Ihrem Netzwerk:
  ping nas.home.lan        → 192.168.30.10
  http://grafana.home.lan  → Ihr Grafana-Dashboard

# Für Subdomains einen CNAME hinzufügen:
  Pi-hole-Admin → 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 auf die Whitelist setzen

# 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

# Abfragelogs für ein bestimmtes Gerät prüfen
pihole -t                      # Live-Mitverfolgung aller Abfragen
# Oder im Web-Admin nach Client filtern (Abfragelog)

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

Anti-Patterns

# SCHLECHT: Auf eine einzige Pi-hole-Instanz ohne Wiederherstellungspfad angewiesen sein
# Wenn Pi-hole abstürzt oder der Pi stromlos wird, kann DNS ausfallen
# GUT: Für den Rollback während der Einrichtung einen dokumentierten Router-Fallback bereithalten
# BESSER: Zwei Pi-hole-Instanzen für Redundanz betreiben; öffentliches Fallback-DNS für striktes Blockieren 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 vorher das Router-DHCP zu deaktivieren
# Zwei DHCP-Server im selben Netzwerk vergeben widersprüchliche IPs
# GUT: Router-DHCP deaktivieren, dann Pi-hole-DHCP aktivieren

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

Best Practices

• Dem Pi eine statische IP oder DHCP-Reservierung geben, bevor Pi-hole installiert wird
• Pi-hole als primären DNS verwenden; für Redundanz eine zweite Pi-hole-Instanz hinzufügen, anstatt einen öffentlichen Resolver, wenn striktes Blockieren erforderlich ist
• DoH (DNS-over-HTTPS) mit cloudflared für verschlüsselte Upstream-Abfragen aktivieren
• home.lan als lokale Domain festlegen und DNS-Einträge für alle Dienste erstellen
• Das Abfragelog gelegentlich prüfen – blockierte Abfragen zeigen, was Ihre Geräte tun

Verwandte Skills

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