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
/home/pi/.firewalla/run/docker/pi-hole/docker-compose.yaml
version: "3"
# More info at https://github.com/pi-hole/docker-pi-hole/ and https://docs.pi-hole.net/
services:
pihole:
container_name: pihole
image: pihole/pihole:v5.1.2
environment:
# set a secure password here or the default will be firewalla
WEBPASSWORD: 'firewalla'
# 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
cap_add:
- NET_ADMIN
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
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 '.[0].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 '.[0].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
/home/pi/.firewalla/config/post_main.d/start_pi_hole.sh
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://1.1.1.1/dns-query,https://1.0.0.1/dns-query,https://9.9.9.9/dns-query,https://149.112.112.9/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
Notes:
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.
Known Issue
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.
References
https://github.com/pi-hole/docker-pi-hole/
https://docs.docker.com/compose/
https://mroach.com/2020/08/pi-hole-and-cloudflared-with-docker/
Comments
106 comments
Warning...absolutely clueless when it comes to docker networking...
For the docker network, can I use my existing scheme?
For example, I use 192.168.250.0/24 for addressing.
Ideally, I'd like to set the pi-hole instance to 192.168.250.2.
Thank you in advance for entertaining a rookie question. :-)
bks
@Hans, sorry, I meant to include that.... I am not using Family Protect, Ad block or DNS over HTTPS on FWG. I tried disabling DNS booster for this client and I got the same results with or without DNS booster enabled. This particular client is hard wired to a switch connected directly to the FWG. I also tried clearing the cache of the DNS Booster using the app. No change.
In case anyone else gets here through my troubles, I ended up opening a ticket with support. Apparently there was a bug in the iOS Firewalla App that setup the DNS incorrectly on the FWG. v1.40 (46) is supposed to fix it. Support was able to remote in and tweak something to make it work for me in the meantime.
The instructions worked perfectly for me once I straightened out a few errors I made. I have all of the FWG features on and running, but I don't care if I can't see device level stats on the pi-hole. I just wanted the additional ad/malware/tracker blocking.
This is was also my first docker experience so even a n00b like me can figure this out.
Ok, I'm confused! :)
Pi-Hole setup and working perfectly, configured for Cleanbrowsing DNS servers.
1) If I turn on "Conditional Forwarding" in Settings > DNS, so I can see hostnames from the Firewalla, then the DNS query figures stop incrementing, but it shows hostnames. If I turn it off, I lose hostnames but the stats increment!
2) I downloaded the Pi-Hole Remote App as above, and when using it, clicking on Statistics, it is telling me to check API and Privacy. API QR scanned, and Privacy setting set to everything.
Might be whiskey .. but feeling a little confused!
@Firewalla
I made a small change and used the latest image for the docker pull.
From:
To:
Bringing the pihole into my gold seems to have increased my internet performance and now I can turn on all of the firewalla features. Although per device statistics is a nice to have, turning off DNS booster doesn't work for me because it's an all or nothing and all new devices get it turned on. Perhaps this will be fixed in the future but not a big deal.
The firewalla gold is incredible and it has also dramatically simplified my home segmentation strategy.
10/10
I saw there is new Pihole version. How can I update the existing Pihole docker in FWG?
I see there’s a note regarding the DNS Booster and how it will interact with the pi-hole. How does the DoH functionality of the Gold interact with the setup?
Binh Ton, you can do this to update/upgrade:
Before changing it you may want to backup your config of whitelists/blacklists/adlists/etc by logging into the admin page and going to settings then teleporter to download the config to your local machine. That way you can restore it all easily after the upgrade by loading it back from the same spot in the interface though honestly that should not be necessary as the config information is being stored in the persistent volumes created in this guide (with a few minor exceptions).
Remove the existing Docker container for pihole by getting the imageID from "sudo docker ps -a" if you are running multiple docker images and you want to keep the other containers and then remove that container with "sudo docker rmi -f <imageID>" ("sudo docker rm -f pihole" should also work) otherwise just stop all of your containers with "sudo docker stop" and then "sudo docker prune -a -f" will remove them all as well as the networks attached to the containers.
Then change your pihole yaml config to read image: pihole/pihole:latest (or just image: pihole:pihole:v5.2.1 which is the explicit new version I believe) instead of the existing line that says image: pihole/pihole:v5.1.2
After that you can restart the docker container and network you had used like:
You don't need to do the sudo systemctl start docker at the beginning unless you did a sudo systemctl stop docker for some reason, though you won't get an error if you try to start it while it is already running.
Note that using the pihole/pihole:latest instruction will result in Docker always pulling the latest pihole image when you restart your FWG, which will leave you with a bunch of unused containers and may create issues for you later. I suspect that's why this guide is written to use a specific pihole version, insuring you always can/do delete the old containers before updating. Do not try and update the pihole image inside the existing container (using "sudo docker exec...").
Hope that helps.
Oh, you can if you want when cleaning house between upgrades safely delete anything other than the docker-config.yaml file in your pi-hole directory ( /home/pi/.firewalla/run/docker/pi-hole/ if you used the instructions above) and let it recreate itself after the container restarts. I'm not sure there is a reason to do it unless possibly a new version would require some mandatory changes to the etc-dnsmasq.d directory/files and I doubt that is terribly likely, but it'll get recreated when you start the new container anyway...
@Brian Shimkus
While you can change the network driver from the config file to specify "host" instead of "bridge" and create your container in the existing network space, it does not get assigned an ip address and would use the localhost address for everything. Also, I THINK that Firewalla has already pre-assigned the Docker network to be 172.17.0.0/24 so my guess is you'd end up with an address in that space unless you also go ahead and reassign the entire docker network to use the host driver. Anyway, this seems overly complicated and I am not sure what you're really going to get out of it in the end. It's potentially helpful if you're running something in a container that requires a whole lot of port forwarding, as that eliminates the need to specify the ports.
@Mauricio Guerrero: Should not interfere with anything if you enable it and should still work as intended.
This is fantastic. Thanks to all that contributed to this!
I have the DoH configuration running. One thing I noted was that I had to turn off the "DNS over HTTPS" function in the FWG to get a consistent "Yes" hit from http://1.1.1.1/help
Before I turned that off, I would randomly get Yes or No.
Any guidance on installing on a Blue Plus?
Here's the environment:
Following the Gold guide for pi-hole my docker-compose.yaml file is identical except my network is as such:
In STEP 2 of the guide is where I hit the roadblock:
Error: argument "lan_routable" is wrong: "table" value is invalid
Any advice on how to proceed?
@Brian Newbold:
Happy to try and help but shouldn't the install for the Blue Plus be the same as for the Blue and NOT the same as the Gold? The Blue install is super easy:
https://help.firewalla.com/hc/en-us/articles/360034635473-Tutorial-Running-Pi-Hole-on-Firewalla-Blue-in-5-mins
If that's not the problem, post back 8)
Blue plus supports docker and makes things nice and convenient... I suppose i'm on the >-5-mins route now :-)
Ahh, I didn't realize that. Do you know what the default docker network is on the Blue plus? I am wondering if you just need to change the network driver from bridge to host (then you can get rid of the ip route add commands entirely) or if instead you need to change the ip route command to something like ip route add <network> via <docker network> dev eth0 (or something similar).
You set the pihole address to 192.168.86.19 on a /24 subnet but then tried to set your route to a network at 192.168.0.0/24 so that wouldn't work anyway (unless you just pasted it wrong). What is the network of your home LAN?
I'll caveat this all with the fact I have never used a Blue or Blue plus though 8)
Update:
Added entries on rt_tables let me run ip route add command.
/etc/iproute2/rt_tables
Added:
202 lan_routable
201 wan_routable
Still no pihole, and unhealthy docker container.
Got things fired up but still a bit untested
Following this guide: https://homenetworkguy.com/how-to/install-pihole-on-raspberry-pi-with-docker-and-portainer/
However, I used Larry's advice on HOST networking.
And, I used the latest 5.2.1 image. (note, not using pihole:latest due to advice of available storage where additional future pulls would leave old images as clutter)
Blending everything together, I found this to be an efficient process:
Update image version to 5.2.1 or as desired
Comment out the network info, ipv4_address to the bottom of the page.
This creates the container according to firewalla spec above
Nice! I like that portainer has the ability to autoremove the container (I have never used it). Your point on using the latest release bothers me as well on the Gold. I should probably modify the autostart script to delete all existing docker containers and let it pull the latest image again though. I don't know why I didn't think about that before your comment!
Or maybe just try portainer... lol
In the meantime I need to get back to making AdguardHome work on the Gold. And still do my xmas shopping...
Is there any way to build this into the the FWG. I'm not a complete novice but I'm very intimidated to try this on my own, now that I have my network and FWG all setup and working perfectly.
The OP script doesn't appear to work for me.
After entering:
I get the following error:
Now it seems to me (and I admit, Docker is relatively new to me) that the YAML file at no point specifies a pi-hole_default network, in fact the script only uses the word "pihole", never "pi-hole", so I'm not sure how a pi-hole_default network would have been created.
Is there something I'm missing here? I can see that this tutorial has been up for a while and people are obviously having success... what am I missing?
@Rob Dennison:
The network is defined between the services tage specifying "pi_hole" and the network tag specifying "default".
As to your issue, I have a question: any chance you didn't delete the ~ or # that appears by default in some editors when you create a new file? It just sounds to me like the issue is that the network line (at least) somehow got commented out in your .yaml file. Reopen it in nano or vi or whatever you use and check.
Thanks for responding @Larry Lindenbaum, but I cannot see "pi_hole" in the YAML file at the top of this page, just "pihole".
The only underscores in the YAML file are in "container_name", and "ipv4_address".
In answering your second question, no there aren't any rogue tildes or hashes... screencap here:
Not asking for a review of my code... just a quick look at the OP's YAML file to see if I've got this right or wrong.
Thanks again!
Doh! You are correct -- I name the directory the same as my services container, it takes it from the directory it finds the yaml in (here created as pi-hole)
Your Gold is running the 1.971 software? I think before the 1.971 you needed to use a different network, 172.0.0.0/24 not 172.16.0.0/24
Also just double checking there were no errors on the docker-compose pull or up commands?
Yes - running 1.971 software. There were no errors on docker-compose pull or up commands:
But wait - as I'm going back through the commands, I see that I put the YAML file in the docker folder, not docker/pi-hole, which is very likely my problem. Let me try this again...
That'll do it!
After moving the YAML file into docker/pi-hole, the "up" won't work because "pool overlaps with other one on this address space"
I removed the old route ("sudo ip route del 172.16.0.0/24"), so the only route left that's close is 172.17.0.0/16. There is also a default route through my WAN IP, but I don't think I should touch that ;)
The rest are VPN, upstream DNS and LAN.
shows no containers (running or not), but
shows the following networks
That docker_default looks suspect because I learned earlier in this thread that the network created is based on the folder the YAML file is in, so this could have been created when I UPed the container from run/docker. The network name "docker_default" is scary, but when I inspect it:
This looks like the culprit. Before I go all "sudo docker network rm eb90dc2fedb3" on this, is there something I'm missing?
I don't want to irreparably break things here so I have to reflash the Gold and rebuild the network config, rules, groups, etc.
Nope - DNS now broken... I think maybe I shouldn't have deleted that route ><
The beautiful thing about the Firewalla is that rebooting it will restore things to a good state and you can run the docker-compose commands again 8)
Though honestly removing that route and then finishing the setup should have worked though you might have needed to do a "sudo docker system prune -a -f" in case you had an untagged image that was still using the network (or trying to). That command should also remove all stopped networks anyway, so that's probably a better option than deleting the network directly.
How do we port forward (and firewall restrict to a certain external network range) to the docker container?
(want to make containerized Pihole DNS on FWG available externally to a specific network)
Please sign in to leave a comment.