Met Pi-hole blokkeren we advertentie-, tracking- en andere ongewenste domeinen centraal binnen het lokale netwerk. In plaats van op ieder apparaat afzonderlijk een browserextensie te installeren, laten we DNS-verzoeken controleren door Pi-hole.
Deze handleiding beschrijft de installatie op Ubuntu Server met Docker Compose, de configuratie van DNS en DHCP en de controles achteraf. De installatie is uitsluitend bedoeld voor intern gebruik: we configureren geen externe toegang.
1. Benodigdheden en voorbeeldconfiguratie
- Een ondersteunde versie van Ubuntu Server, bij voorkeur LTS.
- SSH-toegang met een account dat sudo kan uitvoeren.
- Een vast LAN-adres of DHCP-reservering voor Ubuntu Server.
- Internettoegang voor het downloaden van pakketten en Docker-images.
- Toegang tot de DHCP-instellingen van de router, firewall of DHCP-server.
| Onderdeel | Instelling |
| Besturingssysteem | Ubuntu Server |
| Containerplatform | Docker Engine met Compose-plugin |
| Applicatie | Pi-hole v6 |
| Voorbeeld-LAN-adres | 192.0.2.10 |
| DNS | TCP/UDP 53 |
| Webinterface | TCP 8080 |
| Tijdzone | Europe/Amsterdam |
Let op: 192.0.2.10 is een gereserveerd documentatieadres. Vervang dit overal door het daadwerkelijke vaste LAN-adres van je Ubuntu-server. Er worden geen IP-adressen uit een bestaande infrastructuur gebruikt.
2. Ubuntu Server voorbereiden
Werk de pakketlijst en geïnstalleerde pakketten bij:
sudo apt update
sudo apt upgrade -y
Herstart de server wanneer een kernelupdate of een andere wijziging dit vereist:
sudo reboot
Controleer na het opnieuw verbinden het netwerkadres:
ip -br addr
De server moet een vast bereikbaar LAN-adres hebben. Een wijzigend IP-adres zou ertoe leiden dat clients hun ingestelde DNS-server niet meer kunnen bereiken.
3. Docker Engine en Docker Compose installeren
Installeer de benodigde pakketten en voeg de officiële Docker-repository toe:
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo “${UBUNTU_CODENAME:-$VERSION_CODENAME}”)
Components: stable
Architectures: $(dpkg –print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
Installeer vervolgens Docker Engine en de Compose-plugin:
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Controleer de installatie:
sudo docker –version
sudo docker compose version
sudo systemctl status docker
sudo docker run –rm hello-world
Wanneer de testcontainer zonder foutmelding wordt uitgevoerd, is Docker klaar voor gebruik.
4. Beschikbaarheid van DNS-poort 53 controleren
Pi-hole gebruikt poort 53 TCP en UDP. Controleer of er al een proces op deze poort luistert:
sudo ss -lntup | grep ‘:53 ‘
Ubuntu kan systemd-resolved gebruiken op 127.0.0.53:53. Dit hoeft geen conflict op te leveren als de Pi-hole-container uitsluitend aan het afzonderlijke LAN-adres van de server wordt gekoppeld.
Controleer eventuele bezetting van het LAN-adres op poort 53 voordat je Pi-hole start. Schakel systemd-resolved niet zomaar uit: daarmee kan de DNS-resolutie van Ubuntu zelf worden verstoord.
5. Pi-hole configureren met Docker Compose
Maak een aparte werkdirectory aan:
sudo mkdir -p /opt/pihole
cd /opt/pihole
Maak het Compose-bestand:
sudo nano compose.yaml
Voeg de volgende configuratie toe:
services:
pihole:
container_name: pihole
image: pihole/pihole:latest
ports:
– “${PIHOLE_HOST_IP}:53:53/tcp”
– “${PIHOLE_HOST_IP}:53:53/udp”
– “${PIHOLE_HOST_IP}:8080:80/tcp”
environment:
TZ: “Europe/Amsterdam”
FTLCONF_webserver_api_password: “${PIHOLE_PASSWORD}”
FTLCONF_dns_listeningMode: “ALL”
volumes:
– “./etc-pihole:/etc/pihole”
restart: unless-stopped
De variabele PIHOLE_HOST_IP zorgt ervoor dat de gepubliceerde poorten aan het LAN-adres worden gekoppeld. De map etc-pihole bewaart de configuratie buiten de container. Bij het standaard Docker bridge-netwerk gebruikt Pi-hole de luistermodus ALL; beperk daarom de bereikbaarheid tot vertrouwde interne netwerken.
Maak het bestand met omgevingsvariabelen:
sudo nano /opt/pihole/.env
PIHOLE_HOST_IP=192.0.2.10
PIHOLE_PASSWORD=VervangDitDoorEenSterkWachtwoord
Vervang het documentatieadres en het voorbeeldwachtwoord door de juiste waarden. Beperk de leesrechten op het bestand:
sudo chmod 600 /opt/pihole/.env
Controleer de syntaxis van Docker Compose en start de container:
cd /opt/pihole
sudo docker compose config –quiet
sudo docker compose up -d
Controleer vervolgens de containerstatus en de logs:
sudo docker compose ps
sudo docker compose logs –tail=100 pihole
De container moet actief blijven en mag geen terugkerende fouten laten zien. Let bij een fout over poort 53 vooral op een andere DNS-service die al aan het LAN-adres is gekoppeld.
6. Webinterface openen en upstream DNS instellen
Open vanaf een apparaat binnen het LAN de Pi-hole-webinterface:
http://<LAN-IP-VAN-DE-SERVER>:8080/admin/
Log in met het wachtwoord uit het .env-bestand. De webinterface geeft inzicht in DNS-aanvragen, geblokkeerde verzoeken, clients en domeinen.
Configureer vervolgens via de DNS-instellingen één of meerdere upstream DNS-servers. Dat kan een publieke resolver zijn, zoals Cloudflare of Quad9, of een eigen interne resolver. Pi-hole controleert aanvragen eerst tegen de ingestelde blokkeringen en stuurt toegestane aanvragen door naar de upstream resolver.
Let op: de webinterface gebruikt in dit voorbeeld HTTP. Maak poort 8080 alleen bereikbaar voor vertrouwde beheerclients binnen het LAN.
7. Blocklists en uitzonderingen beheren
Pi-hole gebruikt blocklists om ongewenste domeinen te blokkeren. Begin met de standaardlijsten. Extra blocklists zijn niet automatisch beter: te agressieve filtering kan legitieme websites of applicaties verstoren.
Na het aanpassen van lijsten kun je Gravity opnieuw opbouwen:
sudo docker exec pihole pihole -g
Controleer bij problemen met een website de Query Log en voeg alleen waar nodig een domein toe aan de allowlist. Een specifiek ongewenst domein kan juist in de denylist worden geplaatst.
8. Pi-hole via DHCP aanbieden aan interne clients
Om netwerkbreed DNS-filtering te gebruiken, moet de DHCP-server het interne IP-adres van Pi-hole als DNS-server uitdelen. Pas hiervoor de DNS-instelling aan op de router, firewall of bestaande DHCP-server.
Vernieuw op een Windows-client de DHCP-lease en controleer de DNS-server:
ipconfig /renew
ipconfig /all
Controleer of het LAN-adres van Pi-hole als DNS-server wordt weergegeven. Configureer niet zomaar een publieke DNS-server als tweede DNS-server: clients kunnen deze rechtstreeks gebruiken, waardoor Pi-hole wordt omzeild.
Controleer ook de DNS-instellingen via IPv6. Apparaten kunnen anders alsnog DNS-resolvers buiten Pi-hole gebruiken. Applicaties die eigen versleutelde DNS gebruiken, zoals DNS-over-HTTPS, kunnen de standaard systeem-DNS eveneens omzeilen.
9. Firewall en bereikbaarheid beperken tot het LAN
| Poort | Protocol | Gebruik |
| 53 | TCP | DNS |
| 53 | UDP | DNS |
| 8080 | TCP | Pi-hole webinterface |
Sta DNS-verkeer alleen toe vanuit interne netwerksegmenten die Pi-hole moeten gebruiken. Beperk de webinterface bij voorkeur tot een beheernetwerk. Er is geen portforwarding of publieke toegang nodig.
Aandachtspunt: Docker publiceert poorten via eigen netwerk- en firewallregels. Standaard UFW-regels zijn daarom niet altijd voldoende om toegang tot gepubliceerde containerpoorten te beperken. Controleer de effectieve toegang op de host én via de netwerkfirewall, of pas waar nodig een geschikte DOCKER-USER-filtering toe.
10. Pi-hole bijwerken en back-ups maken
Werk een Docker-installatie bij door een nieuwe image op te halen en de container opnieuw aan te maken. Gebruik hiervoor niet het reguliere pihole -up-commando binnen de container.
cd /opt/pihole
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs –tail=100 pihole
De configuratie staat persistent in /opt/pihole/etc-pihole. Maak hiervan vóór grotere updates een back-up, samen met compose.yaml en het vertrouwelijke .env-bestand. Je kunt ook de Teleporter-functie van Pi-hole gebruiken om configuratiegegevens te exporteren.
Lees vóór grotere upgrades de release notes. Houd rekening met een korte DNS-onderbreking tijdens het opnieuw aanmaken van de container.
11. DNS-resolutie en filtering controleren
Controleer eerst op de Ubuntu-server of Pi-hole draait:
cd /opt/pihole
sudo docker compose ps
Test daarna op een Windows-client DNS-resolutie rechtstreeks via Pi-hole. Vervang het voorbeeldadres door het eigen LAN-adres:
nslookup google.nl 192.0.2.10
Controleer vervolgens of de client Pi-hole ook standaard gebruikt:
ipconfig /all
nslookup google.nl
Open in Pi-hole de Query Log en controleer of de DNS-aanvragen van de client zichtbaar worden. Voeg desgewenst tijdelijk een onschuldig testdomein toe aan de denylist, controleer of het wordt geblokkeerd en verwijder de testblokkering na afloop.
Een succesvolle DNS-respons alleen bewijst nog niet dat filtering actief is. Controleer daarom zowel de standaard ingestelde DNS-server als de daadwerkelijke blokkering.
12. Checklist voor de installatie
- Ubuntu Server bijgewerkt en vast LAN-adres bevestigd.
- Docker Engine en Docker Compose geïnstalleerd.
- Poort 53 gecontroleerd op conflicten.
- compose.yaml en .env aangemaakt.
- Pi-hole-container gestart en logs gecontroleerd.
- Webinterface intern bereikbaar en beheerderswachtwoord ingesteld.
- Upstream DNS en blocklists gecontroleerd.
- DHCP deelt Pi-hole als DNS-server uit.
- DNS via IPv4 en IPv6 gecontroleerd.
- Toegang tot DNS en webinterface beperkt tot vertrouwde netwerken.
- DNS-resolutie en blokkering vanaf een client getest.
- Back-up van configuratie en herstelprocedure geregeld.
Officiële documentatie