Wer Pi-hole Whitelist-Einträge hinzufügen möchte, ohne jedes Mal den Admin zu bemühen, steht vor einem typischen Problem im Familiennetzwerk: Blockiert Pi-hole eine harmlose Domain, kann nur die Person mit Admin-Zugang zur Weboberfläche sie freigeben. In diesem Guide zeigen wir dir, wie du mit dem quelloffenen Projekt „Pihole Simple Whitelist“ eine schlanke Weboberfläche einrichtest, über die auch Mitbewohner und Familienmitglieder eine Domain selbst freischalten können – ganz ohne Zugriff auf das eigentliche Pi-hole-Adminpanel.
Pi-hole ist ein netzwerkweiter Werbeblocker, der als DNS-Sinkhole arbeitet und Werbung sowie Tracker für alle Geräte im Netzwerk blockiert. Läuft der Blocker auf einem Raspberry Pi oder einem anderen Linux-Server, filtert er den DNS-Verkehr zentral. Wie du Pi-hole von Grund auf aufsetzt, erklären wir im Guide Pi-hole installieren: DNS-Werbeblocker einrichten.
Das Problem: False-Positives im Haushalt
Mit den offiziellen Blocklisten treten nur selten Fehlblockaden (False-Positives) auf. Sobald du aber zusätzliche, aggressivere Blocklisten einbindest, kann es schnell passieren, dass einzelne Webseiten nicht mehr richtig laden oder komplett unerreichbar sind. Als Pi-hole-Admin ist die Domain zwar in wenigen Sekunden auf die Whitelist gesetzt – alle anderen im Haushalt müssen jedoch warten, bis du dich darum kümmerst. Genau hier setzt eine simple Self-Service-Lösung an.
Die Lösung: Pi-hole Simple Whitelist
Pihole Simple Whitelist ist ein kleines Open-Source-Projekt von zigzag1001 auf GitHub. Es stellt eine minimalistische Weboberfläche bereit, über die jede Person im Netzwerk eine Domain auf die Whitelist setzen kann, ohne Zugang zum Pi-hole-Adminbereich zu benötigen. Zusätzlich lässt sich das Blocking optional für einige Minuten pausieren.
Pi-hole Simple Whitelist installieren
Die Installation erfolgt direkt auf dem Server, auf dem Pi-hole läuft. Öffne dazu eine SSH-Verbindung oder ein Terminal und folge den Schritten. Zuerst wechselst du in eine Root-Shell:
sudo suWechsle anschließend in das Webverzeichnis deines Servers:
cd /var/www/html/Lege einen Ordner für die Whitelist-Anwendung an und wechsle hinein:
mkdir whitelist
cd whitelistLade nun die drei benötigten Dateien des Projekts direkt aus dem GitHub-Repository herunter:
curl -O https://raw.githubusercontent.com/zigzag1001/pihole-Simple-Whitelist/main/whitelist-add.php \
-O https://raw.githubusercontent.com/zigzag1001/pihole-Simple-Whitelist/main/style.css \
-O https://raw.githubusercontent.com/zigzag1001/pihole-Simple-Whitelist/main/index.htmlPasswort-Hash ermitteln
Damit das optionale Pausieren des Blockings funktioniert, benötigt das Skript den Hash deines Pi-hole-Webinterface-Passworts. Diesen liest du so aus:
cat /etc/pihole/setupVars.conf | grep WEBPASSWORDÖffne danach die Datei whitelist-add.php im Editor und trage den ermittelten Hash bei der Variable $auth ein (im Original in Zeile 16):
nano whitelist-add.phpSpeichern mit STRG + O, schließen mit STRG + X. Danach erreichst du die Oberfläche im Browser unter http://pi.hole/whitelist/ – und jeder im Netzwerk kann Domains selbst freigeben.
So funktioniert das Whitelist-Skript
Das Herzstück ist die Datei whitelist-add.php. Sie nimmt POST-Anfragen der Weboberfläche entgegen und ruft im Hintergrund die Pi-hole-Kommandozeile auf. Je nach Aktion listet sie bereits freigegebene Domains, pausiert das Blocking oder setzt eine neue Domain auf die Whitelist. Vor dem Whitelisting prüft ein regulärer Ausdruck, ob die Eingabe überhaupt wie eine gültige Domain aussieht:
<?php
if ($_SERVER['REQUEST_METHOD'] == 'POST') {
if (isset($_POST['action']) && $_POST['action'] === 'list') {
// List whitelisted domains
$command = "sudo pihole -w -l | awk '{print $1, $2}'";
$output = [];
exec("$command 2>&1", $output);
echo "<pre>" . implode("\n", $output) . "</pre>";
} elseif (isset($_POST['action']) && $_POST['action'] === 'disable') {
// https://www.crosstalksolutions.com/the-worlds-greatest-pi-hole-and-unbound-tutorial-2023/
$XMin = 5; // Minutes to disable blocking
$XSec = $XMin * 60;
$auth = "YOUR_PASSWORD_HASH"; // `cat /etc/pihole/setupVars.conf | grep WEBPASSWORD`
$command = "curl -s \"http://localhost/admin/api.php?disable={$XSec}&auth={$auth}\"";
$output = [];
$returnVar = 0;
exec("$command 2>&1", $output, $returnVar);
if ($returnVar === 0) {
echo "Disabled blocking for $XMin minutes. ". implode(' ', $output);
$t=time();
$d=date("M-d H:i e",$t);
error_log("Disabled by {$_SERVER['REMOTE_ADDR']} - {$d}\n", 3, "/var/log/pihole_disabled.log");
} else {
echo "Failed. Blocking not disabled. Output: " . implode(' ', $output);
}
} else {
// Whitelist a domain
$t=time();
$d=date("M-d H:i e",$t);
$domain = escapeshellarg($_POST['domain']);
$regex_domain = "/[a-zA-Z0-9-]+(\.[a-zA-Z0-9-]+)*\.[a-zA-Z]{2,6}/";
$is_match = preg_match($regex_domain, $domain);
if ($is_match == 1) {
$command = "sudo pihole -w $domain --comment \"{$_SERVER['REMOTE_ADDR']} - {$d}\"";
$output = [];
$returnVar = 0;
exec("$command 2>&1", $output, $returnVar);
if ($returnVar === 0) {
echo "Domain $domain has been successfully whitelisted.";
} else {
echo "Failed to whitelist domain $domain. Output: " . implode(' ', $output);
}
} else {
echo "Domain input is wrong.";
}
}
}
?>Sicherheitshinweise: Whitelist ohne Admin-Zugang absichern
Weil das Skript Systembefehle mit erhöhten Rechten ausführt, solltest du es ausschließlich im lokalen Netzwerk erreichbar machen – niemals offen im Internet. Beachte dabei:
- Der hinterlegte Passwort-Hash liegt im Klartext in der PHP-Datei. Schütze das Verzeichnis mit passenden Dateirechten.
- Gib die Oberfläche nur im Heimnetz frei und veröffentliche sie nicht über eine Portweiterleitung. Für sicheren Fernzugriff eignet sich stattdessen ein VPN wie in unserem Guide zu Tailscale für Fernzugriff ohne Portfreigabe.
- Die Domain-Prüfung per Regex ist grundlegend. In einer vertrauenswürdigen Familienumgebung ist das ausreichend, in größeren Netzen solltest du zusätzliche Zugriffsbeschränkungen setzen.
Fazit
Mit Pihole Simple Whitelist gibst du allen im Haushalt die Möglichkeit, fälschlich blockierte Domains selbst freizuschalten – ohne den Umweg über den Admin und ohne Zugriff auf das eigentliche Pi-hole-Panel. Die Einrichtung dauert nur wenige Minuten, senkt spürbar den Support-Aufwand und macht aggressive Blocklisten im Familienalltag deutlich praxistauglicher. Wichtig bleibt: Betreibe die Oberfläche nur im lokalen Netzwerk und sichere den Zugriff sinnvoll ab.
Häufige Fragen (FAQ)
Kann man in Pi-hole Whitelist-Einträge wirklich ohne Admin-Zugang hinzufügen?
Ja. Mit dem Projekt Pihole Simple Whitelist richtest du eine eigene Weboberfläche unter http://pi.hole/whitelist/ ein. Über diese kann jede Person im Netzwerk eine Domain freigeben, ohne sich am Pi-hole-Adminbereich anmelden zu müssen.
Ist das für ein normales Heimnetzwerk sicher?
In einem vertrauenswürdigen Heimnetz ja, solange die Oberfläche nicht ins Internet veröffentlicht wird. Da das Skript Befehle mit erhöhten Rechten ausführt, sollte es niemals per Portweiterleitung öffentlich erreichbar sein. Für Fernzugriff nutzt du besser ein VPN.
Wozu wird der Passwort-Hash benötigt?
Der Hash des Webinterface-Passworts wird nur für die optionale Funktion gebraucht, das Blocking für einige Minuten zu pausieren. Zum reinen Whitelisten von Domains ist er nicht zwingend erforderlich. Du liest ihn mit cat /etc/pihole/setupVars.conf | grep WEBPASSWORD aus.
Auf welchem System läuft die Whitelist-Oberfläche?
Die Dateien werden direkt auf dem Server abgelegt, auf dem Pi-hole läuft – typischerweise unter /var/www/html/whitelist. Voraussetzung ist ein funktionierender Webserver mit PHP-Unterstützung.
Was passiert bei einer ungültigen Domain-Eingabe?
Das Skript prüft die Eingabe mit einem regulären Ausdruck. Sieht die Eingabe nicht wie eine gültige Domain aus, wird sie abgelehnt und die Meldung „Domain input is wrong“ ausgegeben, statt einen Befehl auszuführen.