diff --git a/.gitignore b/.gitignore index 2b48bf7..a024362 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ node_modules/ vendor/bundle/ .bundle/ .npm-cache/ +etc-pihole/ diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..ff7d7cc --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1 @@ +MD013: false diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..f60f1a8 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,16 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +## [2026-09-05] + +### Changed + +- Updated repository to reflect Pi-hole Core v6.1.4, FTL v6.7, Web v6.6, and Docker 2026.07.x. +- Rewrote README for better scannability and inclusion of Docker quickstart. +- Migrated legacy Docker configurations to use modern `FTLCONF_*` environment variables. + +### Added + +- `docker-compose.yml` and `.env` template in root. +- `MIGRATION.md`, `CONTRIBUTING.md`, and `CHANGELOG.md`. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 516209c..3cec7d5 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -7,6 +7,7 @@ We as contributors and maintainers pledge to make participation in our project a ## 🚫 Unacceptable Behavior Examples include: + - Use of sexualized language or imagery - Trolling, insulting or derogatory comments - Public or private harassment diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6bc104c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,13 @@ +# Contributing + +Thank you for your interest in contributing to the Pi-hole v6 Troubleshooting Hub! + +## How to Contribute + +1. Fork this repository. +2. Create a feature branch (`git checkout -b feature/your-feature`). +3. Commit your changes (`git commit -m 'Add some feature'`). +4. Push to the branch (`git push origin feature/your-feature`). +5. Open a Pull Request. + +Please ensure your changes align with the official Pi-hole documentation and do not introduce unverified workarounds. diff --git a/LICENSE b/LICENSE index db0cd85..c936fa2 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2025 TimInTech +Copyright (c) 2026 TimInTech Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..4df9773 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,13 @@ +# Migrating to Pi-hole v6 + +Pi-hole v6 introduces significant changes, notably the removal of `lighttpd` in favor of a built-in web server, and a shift to TOML-based configuration (`pihole.toml`). + +## Docker Migration + +If you are upgrading an existing Docker deployment: + +1. **Environment Variables:** `WEBPASSWORD` and other legacy vars are deprecated. Use `FTLCONF_*` prefixes. + - Example: `WEBPASSWORD=secret` becomes `FTLCONF_webserver_api_password=secret`. +2. **Volumes:** `/etc/dnsmasq.d` is no longer strictly required for standard configs, as Pi-hole FTL handles everything internally. + +See the root `docker-compose.yml` for a modern working example. diff --git a/README.de.md b/README.de.md index ce3cd3b..aff20db 100644 --- a/README.de.md +++ b/README.de.md @@ -1,221 +1,80 @@ -# 🛠️ Pi-hole Resolver v6 — Ultimativer Troubleshooting-Hub (Aktualisiert) +# 🛠️ Pi-hole Resolver v6 — Ultimativer Troubleshooting-Hub -Umfassender Pi-hole v6.x Setup-, Fix- und FAQ-Leitfaden (Debian Bookworm/Trixie/Raspberry Pi OS) +## Umfassender Pi-hole v6.x Setup-, Fix- und FAQ-Leitfaden (Linux/Docker) [![Build](https://img.shields.io/github/actions/workflow/status/TimInTech/pi-hole-resolver-v6/ci-sanity.yml?branch=main)](https://github.com/TimInTech/pi-hole-resolver-v6/actions) [![License](https://img.shields.io/github/license/TimInTech/pi-hole-resolver-v6)](LICENSE) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-Spenden-ffdd00?logo=buymeacoffee&logoColor=000&labelColor=fff)](https://buymeacoffee.com/timintech) -![Technik](https://skillicons.dev/icons?i=bash,linux,debian,rpi) - **Sprachen:** 🇩🇪 Deutsch (diese Datei) • 🇬🇧 [English](README.md) --- ## 🧠 Über dieses Projekt -> Stack: Pi-hole Core 6.1.4 / FTL 6.1 / Web 6.2 (eingebauter Webserver, kein lighttpd). Getestet auf Raspberry Pi 3/4 (64-bit) mit Debian Bookworm/Trixie bzw. Raspberry Pi OS. - -Dieses Repository ist ein **zentraler Hub** zur Lösung häufiger Pi-hole v6.x-Probleme. Es baut auf dem ursprünglichen [Pi-hole v6.0 Guide](https://github.com/TimInTech/Pi-hole-v6.0---Comprehensive-Guide) auf und adressiert wiederkehrende Themen aus r/pihole und dem offiziellen Discourse: - -- **Aktualisiert für v6.1.4+** (neueste Core-Release: 14. Juli 2025; FTL v6.1: 30. März 2025; Web v6.2: 30. Mai 2025): Beinhaltet Fixes für den eingebauten Webserver, FTL-Datenbankmigrationen sowie Bugfixes rund um DNS-Auflösung und UI-Stabilität. -- **Reddit-Sticky-FAQs**: Häufigste Fragen integriert, um Doppelposts zu vermeiden. -- **Spezifische 2025-Fixes**: DNS-Ausfälle nach Upgrade, 403 Forbidden im Admin-UI, fehlende pihole.toml, Docker-Migration, Unbound-Konflikte. -- **Verifizierte Links**: Externe Links geprüft (Umbrella KB aktualisiert; keine 404s). -- **Neue Skripte**: Ausführbare Helfer für DB-Reparatur, GUI-Optimierung, Backups und v6-Upgrades. -- **Companion-Repos**: - - Automatisiertes Full-Stack-Setup (Pi-hole + Unbound + NetAlertX): [Pi-hole-Unbound-PiAlert-Setup](https://github.com/TimInTech/Pi-hole-Unbound-PiAlert-Setup) – One-Click-Install mit DNSSEC und Monitoring. - - Wartung: [pihole-maintenance-pro](https://github.com/TimInTech/pihole-maintenance-pro) – Automatische Updates, Backups und Health Checks (v5.3.2, 10. Okt. 2025). +> **Aktueller Stack:** Pi-hole Core v6.1.4 / FTL v6.7 / Web v6.6 / Docker 2026.07.x. -Bitte zuerst r/pihole durchsuchen—viele Antworten verweisen hierher oder auf das [Pi-hole Discourse](https://discourse.pi-hole.net) (offizieller Support). +Dieses Repository ist ein zentraler Hub zur Lösung häufiger Pi-hole v6.x-Probleme. Es beinhaltet: -**Repo-Struktur** (Neu & erweitert): - -- `README.md` / `README.de.md`: Dieser Leitfaden. -- `scripts/`: Automatisierte Fixer (z. B. `fix-ftl-db.sh`, `optimize-gui.sh`, `v6-upgrade-check.sh`). -- `docs/`: Hintergrundwissen (z. B. IPv6-Umgehung, DoH/DoT-Blocks, Docker-Migrationen). -- `lists/`: Kuratierte Blocklisten 2025 (inkl. aktualisierte Firebog-Integrationen). -- `LICENSE`: MIT. -- `.github/workflows/`: CI-Sanity-Checks. +- **Aktualisiert für 2026:** Volle Unterstützung für FTL v6.7, Web v6.6 und Docker 2026.07.x. +- **Docker-Fokus:** Ausführlicher Leitfaden zu den neuen `FTLCONF_*` Umgebungsvariablen. +- **Neue Skripte:** Helfer für DB-Reparatur, GUI-Optimierung, Backups und v6-Upgrades. +- **Companion-Repos:** + - [Pi-hole-Unbound-PiAlert-Setup](https://github.com/TimInTech/Pi-hole-Unbound-PiAlert-Setup) + - [pihole-maintenance-pro](https://github.com/TimInTech/pihole-maintenance-pro) --- ## ⚙️ Schnellstart -> Bevorzugst du Automatisierung? Nutze `Pi-hole-Unbound-PiAlert-Setup` für die Ein-Klick-Installation. Für laufende Updates/Backups siehe `pihole-maintenance-pro`. +### 🖥️ Bare-Metal (Linux) -### 🔧 Pi-hole v6.x installieren +Pi-hole direkt auf einem Linux-Host installieren (Debian/Ubuntu/Raspberry Pi OS): ```bash curl -sSL https://install.pi-hole.net | bash ``` -**Nach der Installation (v6.1+ spezifisch):** - -- Admin-UI: `http:///admin/` (eingebauter Webserver; kein lighttpd nötig; prüfe Port 80/8080 bei 403-Fehlern). -- Passwort ändern: `sudo pihole -a -p`. -- Test: `dig pi.hole @`. -- **Neu: v6 DB-Migration & toml prüfen**: - -```bash -sudo pihole -r # Reparatur, falls FTL fehlschlägt oder pihole.toml fehlt -sudo systemctl status pihole-FTL # Sicherstellen, dass CPU/DNS ok sind -``` +**Prüfung nach der Installation:** -**Tipp für Unbound**: Für Unbound-Integration nach der Basisinstallation [Pi-hole-Unbound-PiAlert-Setup](https://github.com/TimInTech/Pi-hole-Unbound-PiAlert-Setup) verwenden. +- Admin-UI: `http:///admin/` (Pi-hole v6 nutzt einen eingebauten Webserver; kein lighttpd nötig). +- Passwort ändern: `sudo pihole -a -p` +- Status-Check: `sudo systemctl status pihole-FTL` -### 🌌 Update & Wartung (für v6.1 optimiert) +### 🐳 Docker Compose -```bash -sudo apt update && sudo apt upgrade -y -sudo pihole -up # Handhabt v6.1+ Upgrades; auf DNS-Ausfälle achten -sudo pihole -g -sudo pihole restartdns -``` +Für ein modernes Docker-Deployment nutze unsere `docker-compose.yml`, die auf `FTLCONF_*` Variablen setzt. -**v6-Tipp**: Vor Updates Auto-Backups aktivieren, um DB/toml-Korruption zu vermeiden: +1. Repo klonen oder `docker-compose.yml` und `.env` kopieren. +2. `.env` anpassen (Passwort und Zeitzone). +3. Container starten: ```bash -sudo mkdir -p /var/backups/pihole -sudo tee -a /etc/pihole/pihole-FTL.conf >/dev/null <<'EOF' -BACKUP_DIR=/var/backups/pihole -EOF -sudo systemctl restart pihole-FTL +docker compose up -d ``` -**Automatisierte Option**: [pihole-maintenance-pro](https://github.com/TimInTech/pihole-maintenance-pro) für cron-basierte Läufe integrieren. +> **Hinweis:** In Pi-hole v6 ist `WEBPASSWORD` veraltet; stattdessen wird `FTLCONF_webserver_api_password` genutzt. Ein vollständiges Beispiel findest du in der Root-`docker-compose.yml`. --- -## 🔌 Häufige Fehler & Lösungen (Ausgabe 2025) +## 🔌 Häufige Fehler & Lösungen (Ausgabe 2026) | Problem | Ursache (v6.1+ spezifisch) | Lösung | |---------|-----------------------------|--------| -| **Listen laden nicht** | Upstream-DNS-Ausfall oder IPv6-Fehlkonfig | `sudo pihole -g`; `/etc/resolv.conf` prüfen; IPv6 testen: `ping6 google.com`. | -| **Nur Router als Client sichtbar** | Router leitet sämtlichen DNS weiter | Pi-hole DHCP aktivieren; Router „DNS-Rebinding“ deaktivieren. Skript: `scripts/enable-dhcp.sh`. | -| **YouTube-Werbung nicht blockbar** | Ads von Videodomains | Per DNS nicht zuverlässig möglich; uBlock Origin verwenden. | -| **Seiten laden nicht (Overblocking)** | Z. B. neue CDNs | Im Query Log whitelisten; 2025-Whitelist aus `lists/` nutzen. | -| **Port 53 Konflikt** | systemd-resolved oder Unbound | `sudo systemctl disable --now systemd-resolved`. | -| **FTL-DB korrupt nach Update** | v6.1 Migrationsfehler | DB umbenennen: `sudo mv /etc/pihole/pihole-FTL.db /etc/pihole/pihole-FTL.db.bak`; `sudo pihole restartdns`. Skript: `scripts/fix-ftl-db.sh`. | -| **Langsame GUI / hohe CPU (30–70%)** | Eingebauter Server überlastet (Pi Zero/3) | `MAXDBDAYS=14` in `pihole-FTL.conf`; Blocklisten reduzieren. Skript: `scripts/optimize-gui.sh`. | -| **Mehrfach täglich Freezes** | Memory-Leak in FTL v6.0.x | Neuinstallation + Restore: `sudo pihole uninstall; curl install; Teleporter restore`. | -| **Verbindungs-/UDP-/NTP-Fehler** | v6 Sync-Probleme | `timedatectl set-ntp true`; Upstream-DNS prüfen (z. B. 1.1.1.1). | -| **Kein Internet nach v6-Upgrade** | DHCP/DNS-Schleife | Pi-hole-IP als einzigen DNS im Router setzen; `sudo pihole flush`. | -| **Web-UI (403 Forbidden)** | v6.1 eingebauter Webserver: Rechte/Port | `http://:8080/admin/` probieren; `sudo pihole -r`; `/etc/pihole/pihole.toml` prüfen. Skript: `scripts/fix-ui-403.sh`. | -| **DNS Server Failure** | Unbound/Upstream-Konflikte nach v6.1 | Upstream in UI prüfen; `dig @127.0.0.1 -p 5335 example.com`. Siehe [Pi-hole-Unbound-PiAlert-Setup](https://github.com/TimInTech/Pi-hole-Unbound-PiAlert-Setup). | -| **pihole.toml fehlt nach Upgrade** | v6.1 Konfig-Migration fehlgeschlagen | `sudo pihole -r --reconfigure`; aus Backup wiederherstellen. | -| **Docker v5→v6 Migration** | Env-Variablen (WEBPASSWORD) oder dnsmasq-Änderungen | Compose aktualisieren: `-e WEBPASSWORD`; Volumes neu abbilden; DHCP-Statics prüfen. Siehe `docs/docker-v6.md`. | - -**Debug ausführen**: `pihole -d` (Token teilen im Discourse). - -Hinweis zu Rechten: Viele Pi-hole CLI-Befehle benötigen Root-Rechte. Beispiel: `sudo pihole -t` für Live-Log. - ---- +| **Listen laden nicht** | Upstream-DNS-Ausfall / IPv6 | `sudo pihole -g`; `/etc/resolv.conf` prüfen. | +| **FTL-DB korrupt** | v6 Migrationsfehler | DB umbenennen: `sudo mv /etc/pihole/pihole-FTL.db /etc/pihole/pihole-FTL.db.bak`; `sudo pihole restartdns`. | +| **Web-UI (403)** | v6.1 Webserver Rechte | `http://:8080/admin/` probieren; `sudo pihole -r`; `/etc/pihole/pihole.toml` prüfen. | +| **Docker-Variablen ignoriert**| Veraltete Variablen | Auf `FTLCONF_*` Format wechseln (z. B. `FTLCONF_webserver_api_password`). | -## 🔍 Verifizierte FAQ (aus r/pihole Sticky & Discourse, nach Views sortiert) - -| Frage | Kurzantwort | Quelle | -|-------|-------------|--------| -| Wie blocke ich YouTube-Werbung? | Mit Pi-hole nicht zuverlässig (Browser-Erweiterungen nutzen). | [Discourse #253](https://discourse.pi-hole.net/t/how-do-i-block-ads-on-youtube/253) | -| Ungewöhnliche DNS-Anfragen (z. B. „z9d8ejfsdsdf9“)? | Chrome-Prefetch; harmlos. | [Umbrella KB (2025)](https://support.umbrella.com/hc/en-us/articles/115005876643-Unusual-DNS-queries-showing-in-reports) | -| Warum laden Inhalte nicht? | Domain im Query Log identifizieren. | [Discourse #1522](https://discourse.pi-hole.net/t/how-do-i-determine-what-domain-an-ad-is-coming-from/1522) | -| Wie nutze ich Pi-hole auf Geräten/Router? | DNS am Gerät/Router setzen oder Pi-hole DHCP nutzen. | [Discourse #245](https://discourse.pi-hole.net/t/how-do-i-configure-my-devices-to-use-pi-hole-as-their-dns-server/245) | -| Router blockiert DNS-Änderungen? | Pi-hole DHCP nutzen; Rebind-Schutz deaktivieren. | [#3026](https://discourse.pi-hole.net/t/how-do-i-use-pi-holes-built-in-dhcp-server-and-why-would-i-want-to/3026), [#3142](https://discourse.pi-hole.net/t/why-wont-pi-hole-work-with-dns-rebind-protection-enabled/3142) | -| Alle DNS-Anfragen vom Router? | Pi-hole DHCP aktivieren für per-Client-Sicht. | [#3653](https://discourse.pi-hole.net/t/why-do-i-only-see-my-routers-ip-address-instead-of-individual-devices-in-the-top-clients-section-and-query-log/3653) | -| Zweiter DNS empfohlen? | Nein – nur Pi-hole, um Umgehungen zu verhindern. | [#3376](https://discourse.pi-hole.net/t/why-should-pi-hole-be-my-only-dns-server/3376), [#1536](https://discourse.pi-hole.net/t/primary-vs-secondary-dns/1536) | -| Geräte vom Blocken ausnehmen? | Gruppenverwaltung nutzen (v6 verbessert). | [#3372](https://discourse.pi-hole.net/t/how-can-i-use-pi-hole-for-all-my-devices-except-one-or-more/3372) | -| Andere Software mit Pi-hole betreiben? | Ja, aber Ressourcen im Blick behalten. | [#8684](https://discourse.pi-hole.net/t/can-i-run-other-software-along-side-pi-hole/8684) | -| Blocklisten hinzufügen? | GUI: Gruppenverwaltung → Adlists (2025: Firebog nutzen). | [#259](https://discourse.pi-hole.net/t/how-do-i-add-additional-block-lists-to-pi-hole/259); siehe `lists/2025-firebog.txt` | -| Standard-Adlists wiederherstellen? | `sudo pihole -g --reset`; oder manuell via Gravity. | [#32323](https://discourse.pi-hole.net/t/restoring-default-pi-hole-adlists/32323) | -| Remote-Zugriff (Port 53 öffnen)? | Nein – VPN nutzen (Tailscale/WireGuard). | [#13705](https://discourse.pi-hole.net/t/accessing-pi-hole-outside-of-my-lan/13705) | -| **Neu: DoH/DoT-Umgehung in v6?** | Geräte nutzen verschlüsseltes DNS. | Domains wie `dns.google` blocken; Port 853 via iptables/nftables sperren. Siehe `docs/ipv6-doh.md`. | -| **Neu: Hoher Speicherverbrauch in v6?** | Große FTL-DB. | `MAXDBDAYS=30` setzen; `sudo pihole vacuum`. | -| **Neu: DNS-Fehler nach v6.1-Upgrade?** | Upstream/Unbound-Fehlkonfig. | Upstream neu setzen; mit `dig` testen. Siehe [Pi-hole-Unbound-PiAlert-Setup](https://github.com/TimInTech/Pi-hole-Unbound-PiAlert-Setup). | -| **Neu: Admin-Panel Login/Update-Probleme?** | v6.1 Berechtigungen oder NGINX-Konflikte. | `pihole -r`; eigenes NGINX deaktivieren. | - -Vollständige Sticky-Liste: Siehe [r/pihole Wiki](https://www.reddit.com/r/pihole/wiki/index). +**Mehr Hilfe?** `pihole -d` ausführen für ein Debug-Token. --- -## 📊 Diagnose-Befehle (v6.1 erweitert) - -```bash -# Gravity-Refresh -sudo pihole -g - -# Live-Log -sudo pihole -t - -# Domain abfragen -sudo pihole -q example.com - -# Neustart (v6: leichterer Reload) -sudo pihole restartdns - -# v6 DB/toml prüfen/reparieren -sudo sqlite3 /etc/pihole/pihole-FTL.db "PRAGMA integrity_check;" -sudo ls -la /etc/pihole/pihole.toml # Existenz prüfen - -# Cache leeren -sudo pihole flush - -# Upstream (Unbound) testen -dig @127.0.0.1 -p 5335 example.com -``` - -Hinweis (Docker): In Containern läuft Pi-hole standardmäßig als root; dort Befehle ohne sudo ausführen. Vom Host aus per `docker exec -it pihole -g` u. a. Befehle ausführen. - -**Skript-Nutzung**: +## 📚 Dokumentation & Beitrag -- `./scripts/fix-high-cpu.sh`: Optimierungen für Pi 3/Zero. -- `./scripts/backup-restore.sh`: Teleporter + manuell. -- `./scripts/v6-upgrade-check.sh`: Scans für häufige Post-Upgrade-Probleme. +- [CHANGELOG.md](CHANGELOG.md) - Versionshistorie. +- [MIGRATION.md](MIGRATION.md) - Migrationsleitfaden von v5 auf v6. +- [CONTRIBUTING.md](CONTRIBUTING.md) - Wie man hier mitwirken kann. -**Wartungstipp**: Per [pihole-maintenance-pro](https://github.com/TimInTech/pihole-maintenance-pro) automatisierte Health-Checks durchführen. - ---- - -## 🔐 Sicherheit & Wartung (v6.1 Best Practices) - -- **Kein WAN-Expose**: Für Remote-Zugriff VPN nutzen. -- **Auto-Updates**: `unattended-upgrades` + cron für `sudo pihole -up`. -- **Backups**: Täglich via Teleporter; Offsite speichern. `--backup`-Flags in Skripten nutzen. -- **Neu in v6.1**: Audit-Log aktivieren: `AUDITLOG=true` in `pihole-FTL.conf`; pihole.toml-Rechte prüfen. -- **Blocklisten 2025**: Mit Defaults starten + `lists/home-2025.txt` (vermeidet Overblocking). -- **Full Stack**: Für Unbound + Monitoring: [Pi-hole-Unbound-PiAlert-Setup](https://github.com/TimInTech/Pi-hole-Unbound-PiAlert-Setup) – inkl. API für Stats und DNSSEC. - -**Cron-Beispiel (wöchentlich)**: - -```bash -0 4 * * 0 /usr/local/bin/pihole_maintenance_pro.sh >> /var/log/pihole_maint.log 2>&1 -``` - ---- - -## 🛡️ Support & Beitrag - -Vor Posts in r/pihole oder Discourse: Erst hier suchen! Bei Problemen `pihole -d` ausführen und den Token teilen. - -Unterstütze das Projekt: [☕ Buy me a coffee](https://buymeacoffee.com/timintech) (valider Account; hilft bei laufenden Updates). - -**Fork/Contribute**: PRs für neue Fixes willkommen (z. B. v6.2 Previews oder Docker-Themen). - ---- - -**Maintainer:** TimInTech -**Zuletzt aktualisiert:** 2025-10-12 -**Version:** v6.1.1 (Hub) +**Maintainer:** TimInTech **Lizenz:** [MIT](LICENSE) - ---- - -## 📚 Weitere Dokumente (neu in diesem Repo) - -- **IPv6-Umgehungen/DoH**: `docs/ipv6-doh.md` – Fixes für Android/iOS DoH. -- **Pi Zero W Leitfaden**: `docs/pi-zero-v6.md` – Leichtgewicht-Setup für schwache Hardware. -- **Docker v6 Migration**: `docs/docker-v6.md` – Env-Variablen, Volumes und statisches DHCP. -- **Router-DNS-Einrichtung**: `docs/router-dns.md` – FRITZ!Box, UniFi, Asus, OpenWrt Anleitungen & Links. -- **Unbound-Integration**: Verweise auf [Pi-hole-Unbound-PiAlert-Setup](https://github.com/TimInTech/Pi-hole-Unbound-PiAlert-Setup) für API/Monitoring. -- **Changelog-Sync**: Spiegel der [Pi-hole Releases](https://github.com/pi-hole/pi-hole/releases). - -Falls du Fehler entdeckst oder Erweiterungen wünschst, öffne gern ein Issue! diff --git a/README.md b/README.md index 8ab8ccf..140e052 100644 --- a/README.md +++ b/README.md @@ -1,223 +1,80 @@ -# 🛠️ Pi-hole Resolver v6 — Ultimate Troubleshooting Hub (Updated) +# 🛠️ Pi-hole Resolver v6 — Ultimate Troubleshooting Hub -**Comprehensive Pi-hole v6.x Setup, Fixes & FAQ Guide (Debian Bookworm/Trixie/Raspberry Pi OS)** +## Comprehensive Pi-hole v6.x Setup, Fixes & FAQ Guide (Linux/Docker) [![Build](https://img.shields.io/github/actions/workflow/status/TimInTech/pi-hole-resolver-v6/ci-sanity.yml?branch=main)](https://github.com/TimInTech/pi-hole-resolver-v6/actions) [![License](https://img.shields.io/github/license/TimInTech/pi-hole-resolver-v6)](LICENSE) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-Donate-ffdd00?logo=buymeacoffee&logoColor=000&labelColor=fff)](https://buymeacoffee.com/timintech) -![Tech](https://skillicons.dev/icons?i=bash,linux,debian,rpi) - **Languages:** 🇬🇧 English (this file) • 🇩🇪 [Deutsch](README.de.md) --- ## 🧠 About -> Stack: Pi-hole Core 6.1.4 / FTL 6.1 / Web 6.2 (built-in web server; no lighttpd). Tested on Raspberry Pi 3/4 (64-bit) for Debian Bookworm/Trixie and Raspberry Pi OS. - -This repository is a **completely new, centralized hub** for resolving common Pi-hole v6.x issues, built from the ground up to address repetitive problems seen in r/pihole and official Discourse threads. It expands on the original [Pi-hole v6.0 Guide](https://github.com/TimInTech/Pi-hole-v6.0---Comprehensive-Guide) by incorporating: - -- **Updated for v6.1.4+** (latest core release: July 14, 2025; FTL v6.1: March 30, 2025; Web v6.2: May 30, 2025): Includes built-in web server fixes, FTL database migrations, and post-v6.1 bugfixes for DNS resolution and UI stability. -- **Reddit Sticky FAQs**: Integrated top-voted questions from r/pihole to prevent reposts. -- **2025-Specific Fixes**: DNS failures post-upgrade, 403 Forbidden on admin UI, missing pihole.toml, Docker migration issues, and Unbound conflicts. -- **Verified Links**: All external links checked (Umbrella KB updated; no 404s). -- **New Scripts**: Ready-to-run fixes for DB corruption, GUI slowdowns, backups, and v6 upgrades. -- **Companion Repos**: - - For automated full-stack setup (Pi-hole + Unbound + NetAlertX): [Pi-hole-Unbound-PiAlert-Setup](https://github.com/TimInTech/Pi-hole-Unbound-PiAlert-Setup) – One-click install with DNSSEC and monitoring. - - For maintenance: [pihole-maintenance-pro](https://github.com/TimInTech/pihole-maintenance-pro) – Automated updates, backups, and health checks (v5.3.2, Oct 10, 2025). +> **Current Stack:** Pi-hole Core v6.1.4 / FTL v6.7 / Web v6.6 / Docker 2026.07.x. -Search r/pihole first for duplicates—many answers link back here or to [Pi-hole Discourse](https://discourse.pi-hole.net) (official support). +This repository is a centralized hub for resolving common Pi-hole v6.x issues, built to address repetitive problems seen in the community. It includes: -**Repo Structure** (New & Expanded): - -- `README.md` / `README.de.md`: This guide. -- `scripts/`: Automated fixers (e.g., `fix-ftl-db.sh`, `optimize-gui.sh`, `v6-upgrade-check.sh`). -- `docs/`: Deep dives (e.g., IPv6 bypass, DoH/DoT blocks, Docker migrations). -- `lists/`: Curated 2025 blocklists (e.g., updated Firebog integrations). -- `LICENSE`: MIT. -- `.github/workflows/`: CI for sanity checks. +- **Up-to-date for 2026:** Full support for FTL v6.7, Web v6.6, and Docker 2026.07.x migrations. +- **Docker First:** Extensive guide on `FTLCONF_*` environment variables. +- **New Scripts:** Ready-to-run fixes for DB corruption, GUI slowdowns, backups, and v6 upgrades. +- **Companion Repos:** + - [Pi-hole-Unbound-PiAlert-Setup](https://github.com/TimInTech/Pi-hole-Unbound-PiAlert-Setup) + - [pihole-maintenance-pro](https://github.com/TimInTech/pihole-maintenance-pro) --- ## ⚙️ Quick Start -> Prefer automation? Use `Pi-hole-Unbound-PiAlert-Setup` for a one-click install. For ongoing updates/backups, see `pihole-maintenance-pro`. +### 🖥️ Bare-Metal (Linux) -### 🔧 Install Pi-hole v6.x +Install Pi-hole directly on your Linux host (Debian/Ubuntu/Raspberry Pi OS): ```bash curl -sSL https://install.pi-hole.net | bash ``` -**Post-Install (v6.1+ Specific)**: +**Post-Install Check:** -- Access Admin UI: `http:///admin/` (built-in server; no lighttpd needed; check port 80/8080 if 403 error). -- Change password: `sudo pihole -a -p`. -- Verify: `dig pi.hole @`. -- **New: Check for v6 DB migration & toml issues**: +- Access Admin UI: `http:///admin/` (Pi-hole v6 uses a built-in web server; no lighttpd needed). +- Change password: `sudo pihole -a -p` +- Status check: `sudo systemctl status pihole-FTL` - ```bash - sudo pihole -r # Repair if FTL fails or no pihole.toml - sudo systemctl status pihole-FTL # Ensure no high CPU or DNS failure - ``` +### 🐳 Docker Compose -**Companion Setup Tip**: For Unbound integration, use [Pi-hole-Unbound-PiAlert-Setup](https://github.com/TimInTech/Pi-hole-Unbound-PiAlert-Setup) after basic install. +For a modern Docker deployment, use our updated `docker-compose.yml` that leverages `FTLCONF_*` variables. -### 🌌 Update & Maintenance (v6.1 Optimized) +1. Clone the repo or copy `docker-compose.yml` and `.env`. +2. Edit `.env` to set your secure password and timezone. +3. Start the container: ```bash -sudo apt update && sudo apt upgrade -y -sudo pihole -up # Auto-handles v6.1+ upgrades; watch for DNS failures -sudo pihole -g -sudo pihole restartdns +docker compose up -d ``` -**v6 Tip**: Enable auto-backups before updates to avoid DB/toml corruption: - -```bash -sudo mkdir -p /var/backups/pihole -sudo tee -a /etc/pihole/pihole-FTL.conf >/dev/null <<'EOF' -BACKUP_DIR=/var/backups/pihole -EOF -sudo systemctl restart pihole-FTL -``` - -**Automated Option**: Integrate [pihole-maintenance-pro](https://github.com/TimInTech/pihole-maintenance-pro) for cron-based runs. +> **Note:** Pi-hole v6 deprecates `WEBPASSWORD` in favor of `FTLCONF_webserver_api_password`. Check out the root `docker-compose.yml` for the complete example. --- -## 🔌 Common Errors & Fixes (2025 Edition) +## 🔌 Common Errors & Fixes (2026 Edition) | Problem | Cause (v6.1+ Specific) | Fix | |---------|-------------------------|-----| -| **Lists not downloading** | Upstream DNS outage or IPv6 misconfig | Run `sudo pihole -g`; check `/etc/resolv.conf`; test IPv6: `ping6 google.com`. | -| **Only router as client** | Router forwards all DNS | Enable Pi-hole DHCP; disable router DNS rebinding. Script: `scripts/enable-dhcp.sh`. | -| **YouTube ads not blocked** | Ads from video domains | Not feasible via DNS; use uBlock Origin. | -| **Blocked sites fail to load** | Overblocking (e.g., new CDNs) | Query Log whitelist; add 2025 whitelists from `lists/`. | -| **Port 53 conflict** | systemd-resolved or unbound | `sudo systemctl disable --now systemd-resolved`. | -| **FTL DB corruption post-update** | v6.1 migration bug | Rename DB: `sudo mv /etc/pihole/pihole-FTL.db /etc/pihole/pihole-FTL.db.bak`; `sudo pihole restartdns`. Script: `scripts/fix-ftl-db.sh`. | -| **Slow GUI / High CPU (30-70%)** | Built-in server overload on Pi Zero/3 | Limit DB: `MAXDBDAYS=14` in `pihole-FTL.conf`; reduce blocklists. Script: `scripts/optimize-gui.sh`. | -| **Freezes multiple times/day** | Memory leak in FTL v6.0.x | Reinstall + restore config: `sudo pihole uninstall; curl install; Teleporter restore`. | -| **Connection/UDP/NTP errors** | v6 sync issues | `timedatectl set-ntp true`; check upstream DNS (e.g., 1.1.1.1). | -| **No internet after v6 upgrade** | DHCP/DNS loop | Set Pi-hole IP as sole DNS in router; `sudo pihole flush`. | -| **Web UI inaccessible (403 Forbidden)** | v6.1 built-in server perms or port issues | Try `http://:8080/admin/`; `sudo pihole -r`; check `/etc/pihole/pihole.toml`. Script: `scripts/fix-ui-403.sh`. | -| **DNS Server Failure** | Unbound/upstream conflicts post-v6.1 | Verify upstream in UI; `dig @127.0.0.1 -p 5335 example.com` if using Unbound. See [Pi-hole-Unbound-PiAlert-Setup](https://github.com/TimInTech/Pi-hole-Unbound-PiAlert-Setup). | -| **Missing pihole.toml after upgrade** | v6.1 config migration fail | `pihole -r --reconfigure`; restore from backup. | -| **Docker v5 to v6 migration issues** | Env vars like WEBPASSWORD or dnsmasq changes | Update compose: Use `-e WEBPASSWORD`; remap volumes; test DHCP statics in new conf. See `docs/docker-v6.md`. | - -**Run Debug**: `pihole -d` for token; share on Discourse. - -Note on permissions: Most Pi-hole CLI commands require root privileges. Example: `sudo pihole -t` for live tail. - ---- - -## 🔍 Verified FAQ (From r/pihole Sticky + Discourse, Sorted by Views) - -| Question | Short Answer | Source | -|----------|--------------|--------| -| How to block YouTube ads? | Not possible with Pi-hole (use browser extensions). | [Discourse #253](https://discourse.pi-hole.net/t/how-do-i-block-ads-on-youtube/253) | -| Unusual DNS queries (e.g., gibberish like "z9d8ejfsdsdf9")? | Chrome prefetching; harmless. | [Umbrella KB (Updated 2025)](https://support.umbrella.com/hc/en-us/articles/115005876643-Unusual-DNS-queries-showing-in-reports) | -| Why ads/content not loading? | Identify domain via Query Log. | [Discourse #1522](https://discourse.pi-hole.net/t/how-do-i-determine-what-domain-an-ad-is-coming-from/1522) | -| How to configure devices for Pi-hole? | Set DNS on devices/router or use Pi-hole DHCP. | [Discourse #245](https://discourse.pi-hole.net/t/how-do-i-configure-my-devices-to-use-pi-hole-as-their-dns-server/245) | -| Router blocks DNS changes? | Use Pi-hole DHCP; disable rebind protection. | [Discourse #3026](https://discourse.pi-hole.net/t/how-do-i-use-pi-holes-built-in-dhcp-server-and-why-would-i-want-to/3026), [#3142](https://discourse.pi-hole.net/t/why-wont-pi-hole-work-with-dns-rebind-protection-enabled/3142) | -| All DNS from router? | Enable Pi-hole DHCP for per-client visibility. | [Discourse #3653](https://discourse.pi-hole.net/t/why-do-i-only-see-my-routers-ip-address-instead-of-individual-devices-in-the-top-clients-section-and-query-log/3653) | -| Secondary DNS recommended? | No—use Pi-hole only to avoid bypasses. | [Discourse #3376](https://discourse.pi-hole.net/t/why-should-pi-hole-be-my-only-dns-server/3376), [#1536](https://discourse.pi-hole.net/t/primary-vs-secondary-dns/1536) | -| Exclude clients from blocking? | Use Group Management (v6 enhanced). | [Discourse #3372](https://discourse.pi-hole.net/t/how-can-i-use-pi-hole-for-all-my-devices-except-one-or-more/3372) | -| Run other software with Pi-hole? | Yes, but monitor resources (e.g., no heavy VMs on Pi Zero). | [Discourse #8684](https://discourse.pi-hole.net/t/can-i-run-other-software-along-side-pi-hole/8684) | -| Add blocklists? | GUI: Group Management → Adlists (2025: Use Firebog for curated). | [Discourse #259](https://discourse.pi-hole.net/t/how-do-i-add-additional-block-lists-to-pi-hole/259); See `lists/2025-firebog.txt` | -| Restore default adlists? | `sudo pihole -g --reset`; or manual via gravity. | [Discourse #32323](https://discourse.pi-hole.net/t/restoring-default-pi-hole-adlists/32323) | -| Remote access (open Port 53?)? | No—use VPN (Tailscale/WireGuard). | [Discourse #13705](https://discourse.pi-hole.net/t/accessing-pi-hole-outside-of-my-lan/13705) | -| **New: DoH/DoT bypass in v6?** | Devices use encrypted DNS. | Block domains like `dns.google`; redirect Port 853 via iptables. See `docs/ipv6-doh.md`. | -| **New: High memory on v6?** | Large FTL DB. | Set `MAXDBDAYS=30`; prune: `sudo pihole vacuum`. | -| **New: DNS failure after v6.1 upgrade?** | Upstream/Unbound misconfig. | Reconfigure upstream; test with `dig`. Use [Pi-hole-Unbound-PiAlert-Setup](https://github.com/TimInTech/Pi-hole-Unbound-PiAlert-Setup) for robust Unbound. | -| **New: Admin panel login/update issues?** | v6.1 perms or NGINX conflicts. | `pihole -r`; disable custom NGINX. | - -**Full Sticky List**: See [r/pihole Wiki](https://www.reddit.com/r/pihole/wiki/index) for more. - ---- - -## 📊 Troubleshooting Commands (v6.1 Enhanced) - -```bash -# Gravity refresh -sudo pihole -g - -# Live log -sudo pihole -t - -# Query domain -sudo pihole -q example.com - -# Restart (v6: Use restartdns for lighter reload) -sudo pihole restartdns - -# v6 DB/toml check/fix -sudo sqlite3 /etc/pihole/pihole-FTL.db "PRAGMA integrity_check;" -sudo ls -la /etc/pihole/pihole.toml # Verify existence - -# Flush cache -sudo pihole flush - -# Test upstream (Unbound) -dig @127.0.0.1 -p 5335 example.com -``` - -Docker hint: Inside containers Pi-hole runs as root, so run commands without sudo. From the host you can exec into the container, e.g. `docker exec -it pihole -g`. - -**Scripts Usage**: - -- `./scripts/fix-high-cpu.sh`: Optimizes for Pi 3/Zero. -- `./scripts/backup-restore.sh`: Teleporter + manual. -- `./scripts/v6-upgrade-check.sh`: Scans for common post-upgrade issues. - -**Maintenance Tip**: Run via [pihole-maintenance-pro](https://github.com/TimInTech/pihole-maintenance-pro) for automated health checks. - ---- - -## 🔐 Security & Maintenance (v6.1 Best Practices) - -- **Never expose WAN**: Use VPN for remote. -- **Auto-Updates**: `unattended-upgrades` + cron for `sudo pihole -up`. -- **Backups**: Daily via Teleporter; store offsite. Use `--backup` flag in maintenance scripts. -- **v6.1 New**: Enable audit logging: `AUDITLOG=true` in `pihole-FTL.conf`; verify pihole.toml perms. -- **Blocklists 2025**: Start with defaults + `lists/home-2025.txt` (avoids overblocking). -- **Full Stack**: For Unbound + monitoring, deploy [Pi-hole-Unbound-PiAlert-Setup](https://github.com/TimInTech/Pi-hole-Unbound-PiAlert-Setup) – Includes API for stats and DNSSEC. - -**Cron Example (Weekly Maintenance)**: - -```bash -0 4 * * 0 /usr/local/bin/pihole_maintenance_pro.sh >> /var/log/pihole_maint.log 2>&1 -``` +| **Lists not downloading** | Upstream DNS outage or IPv6 misconfig | Run `sudo pihole -g`; check `/etc/resolv.conf`. | +| **FTL DB corruption** | v6 migration bug | Rename DB: `sudo mv /etc/pihole/pihole-FTL.db /etc/pihole/pihole-FTL.db.bak`; `sudo pihole restartdns`. | +| **Web UI inaccessible (403)** | v6.1 built-in server perms | Try `http://:8080/admin/`; `sudo pihole -r`; check `/etc/pihole/pihole.toml`. | +| **Docker variables ignored** | Deprecated variables used | Switch to `FTLCONF_*` format (e.g. `FTLCONF_webserver_api_password`). | -(From [pihole-maintenance-pro](https://github.com/TimInTech/pihole-maintenance-pro).) +**Need more help?** Run `pihole -d` for a debug token. --- -## 🛡️ Support & Contribution - -Before posting on r/pihole or Discourse: Search here first! If stuck, run `pihole -d` and share the token. +## 📚 Documentation & Contribution -Support this hub: [☕ Buy me a coffee](https://buymeacoffee.com/timintech) (Valid profile; supports ongoing updates.) - -**Fork/Contribute**: PRs for new fixes welcome (e.g., v6.2 previews or Docker issues). - ---- +- [CHANGELOG.md](CHANGELOG.md) - Version history and updates. +- [MIGRATION.md](MIGRATION.md) - Guide for migrating from v5 to v6. +- [CONTRIBUTING.md](CONTRIBUTING.md) - How to contribute to this repo. -**Maintainer:** TimInTech -**Last Updated:** 2025-10-12 -**Version:** v6.1.1 (Hub) +**Maintainer:** TimInTech **License:** [MIT](LICENSE) - ---- - -## 📚 Additional Docs (New in This Repo) - -- **IPv6 Bypass**: `docs/ipv6-doh.md` – Fixes for Android/iOS DoH. -- **Pi Zero W Guide**: `docs/pi-zero-v6.md` – Lightweight config for slow hardware. -- **Docker v6 Migration**: `docs/docker-v6.md` – Env vars, volumes, and static DHCP. -- **Router DNS Setup**: `docs/router-dns.md` – FRITZ!Box, UniFi, Asus, OpenWrt Anleitungen & Links. -- **Unbound Integration**: Links to [Pi-hole-Unbound-PiAlert-Setup](https://github.com/TimInTech/Pi-hole-Unbound-PiAlert-Setup) for API/device monitoring. -- **Changelog Sync**: Mirrors [Pi-hole Releases](https://github.com/pi-hole/pi-hole/releases). - -For German version: See `README.de.md` (translated FAQs + commands). If you spot issues or need expansions, open an issue! diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..069f9d1 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,17 @@ +services: + pihole: + container_name: pihole + image: pihole/pihole:2026.07.0 + ports: + - "53:53/tcp" + - "53:53/udp" + - "80:80/tcp" + environment: + - TZ=${TZ:-Europe/Berlin} + - FTLCONF_webserver_api_password=${PIHOLE_PASSWORD} + - FTLCONF_dns_upstreams=1.1.1.1;1.0.0.1 + volumes: + - './etc-pihole:/etc/pihole' + cap_add: + - NET_ADMIN + restart: unless-stopped diff --git a/docs/docker-v6.md b/docs/docker-v6.md index 223ebfe..f11ce5b 100644 --- a/docs/docker-v6.md +++ b/docs/docker-v6.md @@ -43,20 +43,25 @@ Hinweise: ## Migration v5 -> v6 Schritt für Schritt -1) Backup anlegen (Teleporter oder Volume-Sicherung): - - Web-UI: Settings → Teleporter (recommended) - - Oder Volumes `/etc/pihole` und `/etc/dnsmasq.d` sichern. -2) Container stoppen und entfernen: `docker compose down` -3) Compose-Datei auf v6 aktualisieren (siehe Beispiele): - - `image: pihole/pihole:latest` - - `WEBPASSWORD` setzen - - Ports/Volumes prüfen -4) Container neu starten: `docker compose up -d` -5) Prüfen: - - `docker logs pihole -f` für Fehler - - Admin UI: `http:///admin/` (oder `:8080`) - - `dig @ pi.hole` -6) Optional: Unbound-Container hinzufügen und in Pi-hole als Upstream `127.0.0.1#5335` konfigurieren. +1. Backup anlegen (Teleporter oder Volume-Sicherung): + - Web-UI: Settings → Teleporter (recommended) + - Oder Volumes `/etc/pihole` und `/etc/dnsmasq.d` sichern. + +2. Container stoppen und entfernen: `docker compose down` + +3. Compose-Datei auf v6 aktualisieren (siehe Beispiele): + - `image: pihole/pihole:latest` + - `WEBPASSWORD` setzen + - Ports/Volumes prüfen + +4. Container neu starten: `docker compose up -d` + +5. Prüfen: + - `docker logs pihole -f` für Fehler + - Admin UI: `http:///admin/` (oder `:8080`) + - `dig @ pi.hole` + +6. Optional: Unbound-Container hinzufügen und in Pi-hole als Upstream `127.0.0.1#5335` konfigurieren. ## Nützliche Tipps