Pi-hole integration
Overview
Pi-hole is a popular network-wide ad blocker. Many users have asked to run it on the same device as RaspAP, so that a single Raspberry Pi provides both the access point and the ad blocking for its clients.
Until now this was difficult, because both projects need port 53. RaspAP uses dnsmasq for DHCP and DNS, and Pi-hole's FTL engine is built on dnsmasq as well. When both try to start, one of them fails with:
RaspAP can now turn off its own DNS server while it keeps serving DHCP. Pi-hole then answers DNS on port 53, and RaspAP gives AP clients the Pi-hole address as their DNS server.
Note
This page describes Pi-hole v6. Pi-hole v5 wrote its own files to /etc/dnsmasq.d, which conflict with RaspAP's configuration.
Requirements
- A working RaspAP installation with the Disable DNS server (DHCP only) option on the DHCP Server > Advanced tab.
- Pi-hole v6, installed after the steps in Configure RaspAP.
Configure RaspAP
- Go to DHCP Server and select your AP interface, for example
wlan0. - On the Advanced tab, enable Disable DNS server (DHCP only). This will automatically set the DNS Server on the Server settings tab to the IP address of the AP interface.
-
On the Server settings tab, be sure to leave DNS Server 2 empty, so that clients cannot bypass Pi-hole.
-
Choose Save settings, then Restart dnsmasq.
Important
DNS Server 1 must be the address of this device. The default configuration hands out public DNS servers such as 9.9.9.9 and 1.1.1.1. With those, clients still have working DNS, but their queries never reach Pi-hole.
The Upstream DNS servers option on the Advanced tab has no effect while the DNS server is disabled. Configure upstream servers in Pi-hole instead.
Check that dnsmasq no longer listens on port 53:
This should return nothing. The dnsmasq log at /var/log/dnsmasq.log reports DNS disabled when it starts.
Install Pi-hole
Install Pi-hole with its official installer:
Accept the defaults. You may select any interface in the installer, since Pi-hole's default listening mode answers queries from all directly connected networks, including the AP subnet.
Pi-hole's web server tries ports 80 and 443 by default. RaspAP's lighttpd already uses port 80, so move Pi-hole's web interface to another port:
The Pi-hole dashboard is then available at http://10.3.141.1:8080/admin/, and RaspAP remains at http://10.3.141.1.
Tip
Alternatively, you may move RaspAP to another port as described in this FAQ.
Verify the setup
On the RaspAP device, check that Pi-hole answers on the AP address:
Then watch the Pi-hole query log while a client connected to the AP browses the web:
Queries should appear with the client's address from the AP subnet, for example 10.3.141.205. You can also use the Query Log in the Pi-hole dashboard.
Troubleshooting
Pi-hole reports "Address in use"
If Pi-hole was started while RaspAP's dnsmasq still held port 53, Pi-hole's DNS server does not start, although its web interface runs. Restart dnsmasq first, then Pi-hole:
Clients are not shown in the query log
If only a few queries appear, the client probably sends its DNS queries elsewhere. Common causes are:
- A VPN client on the device, which uses its own DNS server.
- Encrypted DNS in the browser (DNS over HTTPS). Disable it in the browser's privacy or security settings.
- iCloud Private Relay or "Limit IP address tracking" on Apple devices.
- A DHCP lease from before the change. Reconnect the client to the AP to renew it.
On macOS, scutil --dns | grep nameserver shows the DNS servers in use. The first entry should be the AP address.
Settings that must stay at their defaults
- Pi-hole's own DHCP server must remain disabled. RaspAP provides DHCP.
- Pi-hole's
misc.etc_dnsmasq_doption must remain false (the default). If it is enabled, Pi-hole loads RaspAP's files from/etc/dnsmasq.d, including the option that disables DNS.
Limitations
- RaspAP's own ad blocking and DNS query logging use RaspAP's DNS server, so they do not work while it is disabled. Use Pi-hole's blocklists and query log instead.
- The DNS server option applies to all interfaces that RaspAP serves with DHCP. Set DNS Server 1 for each of them, for example for
uap0in AP-STA mode.
