Before everything, please note:
- Pi-Hole has dropped support for Ubuntu 18.04. If your Firewalla is using Ubuntu 18.04, follow our guide to reflash your box. Gold New Image & Purple New Image
- This is a tech doc only for Pros.
- This is for Firewalla in Router mode.
- Incorrect settings of port forwarding will result in ports being opened on your WAN interface
- Pi-hole won't work with the following features of Firewalla on the same device. Firewalla's features always have a higher priority. These features are: Family Protect, Adblock, and DNS over HTTPS.
- You should not enable conditional forwarding in most cases or it might create a DNS loop.
1. Create Configuration Files
You have to choose
- a network as your docker network, we use 172.16.0.0/24 in this tutorial
- a static IP for your pi-hole instance, we use 172.16.0.2 in this tutorial
- a password for your pi-hole management console, we use firewalla in this tutorial
Use the values above unless you know exactly what you are doing and have a reason to change them.
Create the following folder/files
# More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/
# set a secure password here or the default will be firewalla
# Volumes store your data between container upgrades
# static IP address for pi-hole
# your chosen docker network here
- subnet: 172.16.0.0/24
2. Start and Test Pi-hole
run the following commands to install and start pi-hole
cd /home/pi/.firewalla/run/docker/pi-hole sudo systemctl start docker sudo docker-compose pull sudo docker-compose up --no-start sudo ip route add 172.16.0.0/24 dev br-$(sudo docker network inspect pi-hole_default |jq -r '..Id[0:12]') table lan_routable sudo ip route add 172.16.0.0/24 dev br-$(sudo docker network inspect pi-hole_default |jq -r '..Id[0:12]') table wan_routable sudo docker-compose up --detach
If you are using Gold SE, run one more command to add SNAT for the docker network.
sudo iptables -t nat -A POSTROUTING -s 172.16.1.0/16 -o eth0 -j MASQUERADE
If everything is good, pi-hole will be booted and you can now access its management portal by visiting http://172.16.0.2 in your browser.
If you use docker_compose.yaml above, your docker web password is "firewalla"
3. Set Pi-hole as DNS for your network.
Now proceed to the network settings on Firewalla App, assign 172.16.0.2 as the primary DNS server for the networks that you want to enable Pi-Hole.
- Tap on Network Button
- Tap on the Top right edit button
- Tap on the LAN segment you want to change DNS to pi-hole
- Scroll down and change the primary DNS to 172.16.0.2
- Save and you should be able to see DNS requests coming up in the management console.
4. Persisting The Configuration
You must be on firewalla 1.971 or later for this
create folder /home/pi/.firewalla/config/post_main.d and the following file
sudo systemctl start docker sudo ipset create -! docker_lan_routable_net_set hash:net sudo ipset add -! docker_lan_routable_net_set 172.16.0.0/24 sudo ipset create -! docker_wan_routable_net_set hash:net sudo ipset add -! docker_wan_routable_net_set 172.16.0.0/24 sudo systemctl start docker-compose@pi-hole
And you are ready to go.
BONUS: Use DoH on Pi-hole
Change your docker-compose file as following
version: "3" # More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/ services: cloudflared: container_name: cloudflared # Restart on crashes and on reboots restart: unless-stopped image: cloudflare/cloudflared:2020.12.0 command: proxy-dns environment: - "TUNNEL_DNS_UPSTREAM=https://184.108.40.206/dns-query,https://220.127.116.11/dns-query,https://18.104.22.168/dns-query,https://22.214.171.124/dns-query" # Listen on an unprivileged port - "TUNNEL_DNS_PORT=5053" # Listen on all interfaces - "TUNNEL_DNS_ADDRESS=0.0.0.0" # Attach cloudflared only to the private network networks: default: ipv4_address: 172.16.0.3 pihole: container_name: pihole image: pihole/pihole:v5.1.2 environment: # set a secure password here or the default will be firewalla WEBPASSWORD: 'firewalla' DNS1: '172.16.0.3#5053' DNS2: 'no' # Volumes store your data between container upgrades volumes: - '/data/pi-hole/etc-pihole/:/etc/pihole/' - './etc-dnsmasq.d/:/etc/dnsmasq.d/' - '/etc/localtime:/etc/localtime:ro' restart: unless-stopped networks: default: # static IP address for pi-hole ipv4_address: 172.16.0.2 networks: default: driver: bridge ipam: config: # your chosen docker network here - subnet: 172.16.0.0/24
Restart your docker service and it's done
sudo systemctl restart docker-compose@pi-hole
1. If the DNS Booster is enabled. The DNS requests from clients will be first redirected to the local DNS cache on Firewalla, which further uses pi-hole in docker as the upstream DNS server. So you will see all DNS requests from Firewalla's IP of docker network, which is 172.16.0.1. We strongly recommend keeping DNS Booster enabled.
2. In case docker service doesn't start, please follow this guide to reset your docker service. https://help.firewalla.com/hc/en-us/articles/360060535553
3. For those who have a local search domain, you might also want to check: Difference between Search Domain and Local Domain
All product names, logos, and brands are the property of their respective owners. All company, product, and service names used in this website are for identification purposes only. The use of these names, logos, and brands does not imply endorsement.
Note: This was fixed in our 1.976 release so this step is no longer necessary.
On ubuntu 22.04 and later, when docker starts up, it may load a kernel module
br_netfilter which conflicts with ubuntu 22.04 if you are using Smart Queue. Dockers managed by Firewalla will automatically handle this, but if you create docker instance, you may need to run:
sudo rmmod br_netfilter
after starting docker service or the firewalla routing function may break.