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:
- This is a tech doc only for advanced users.
- 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 ip -4 rule add from all iif br-$(sudo docker network inspect pi-hole_default |jq -r '.[0].Id[0:12]') lookup lan_routable priority 5003
sudo docker-compose up --detachIf 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 MASQUERADEIf 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-holeAnd you are ready to go.
BONUS: Use DoH on Pi-hole
Only available for Gold and Gold Pro
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/24Restart 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_netfilterafter 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
118 comments
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?
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)
It's actually fairly simple, and this guide here descibes it pretty well:
https://docs.docker.com/config/containers/container-networking/
as does this one:
https://runnable.com/docker/binding-docker-ports
You can also use the "ports: HOST:CONTAINER" tags in the YAML config file to specify which ports you want exposed for a given container (since I think those other references talk more to exposing ports in an already running container).
The routing to/from the network itself would be configured in the Firewalla Gold app by creating your network segments and then rules to pass (or block) traffic between them.
I've tried everything but I can't even ping the ip I selected for the pi-hole, I believe the docker has another ip and I don't know how to change it ... my network uses the 192.168.25.0/24 range
if someone can help me, I will be more thanked!
I follow exactly all steps, in the end the ip 172.16.0.2 ping normal, but when i try enter in pi-hole web site interface it show: the page canot be found. Some tip?
------------------------------------------------------------------------------------
-----------------------------------------------------------------------------
My Network is:
Firewalla Gold eth0: My modem (bridged) connection (stactic ip).
Firewalla gold eth1 (br1): Vlan in 192.168.25.9 ip (all my devices is in this network)
Firewalla eth2 (br1): My Server with stactic network ip (192.168.25.222)
Firewalla eth3 (br0): This port i need change the vlan because i link it in my wireless router wan port and it have a 192.168.25.0/24 in 4 lan ports and wi-fi ips too so WAN port need another range ip (192.168.24.9 in firewalla port)
I try change the docker ip but its back to 172.17.0.1 when i restart the Firewalla Gold.
I need fix it to run 2 (very light) dockers: 1 pi-hole and 1 TeamSpeak Server.
I will be very grateful if anyone can help me, i tried to install the pi-hol keeping the default ipof the tutorial and it also didn´t work. ping the ip (172.16.0.2) but does not enter the page through the browser.
Here is the picture of my Firewalla Gold config:
Thanks for the tip, this is really great info. I would like to keep pi-hole on the firewalla, so I changed the database retention to 90 days. And I'll keep an eye on disk usage. My FTL db was already at 508MB, it's been running a little under 90 days.
Add "MAXDBDAYS=90" in /data/pi-hole/etc-pihole/pihole-FTL.conf and restart the container.
The FTL db lives in the above directory so you can have a look there if you want to see how much storage it's consuming.
Totally agree with @Joel, if you do plan to use a lot of storage, please leave the service off Firewalla. (or you can get a USB storage and use that instead) We get too many of these cases in our support, and it is wasting us a lot of time (which we can use for other things) supporting and debug disk full errors.
Wow. Mine is about 729 MB. So do I trim this thing down?
I updated pihole-FTL.conf to:
DBINTERVAL=60
MAXDBDAYS=30
It will only write to the DB every 60 minutes in order to save the SD card.
On Blue+ I'm deploying via portainer now, and have this YAML set up in Stacks. Working quite well and much easier to manage than going to SSH every 5 seconds.
---BEGIN YAML 4 PORTAINER STACK---
version: '2'
# 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:latest
environment:
- TZ=Los_Angeles/America
- DNS1=192.168.86.1
- DNS2=no
# set a secure password here or the default will be firewalla
- WEBPASSWORD=yopasswordherebruddah
# 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
network_mode: host
dns:
- 127.0.0.1
- 192.168.86.1
ports:
- "53:53"
- "443:443"
- "80:80"
@Firewalla,
I highly recommend you to add a note of this advice at the top of this article :)
Anyway, I want to thank you for your efforts to develop such a great device, Firewalla Gold!
I've had the network go down a couple of times now with no explanation, and the only solution is to reboot the Firewalla Gold and have all the devices in the network reacquire IP addresses. Further reflection (and reading this thread) tells me that it's likely the pi-hole container that's blowing up the Firewalla storage, and rebooting clears out that history.
To me, this means it's really not viable for my network. Is there any way the OP can update the original post (OP?) to account for a change to the pihole-FTL.conf to cap the storage?
Either that, or maybe the better solution is to run pi-hole on a RPi on a new subnet (discussed here: https://help.firewalla.com/hc/en-us/articles/360062551673-How-to-run-external-pi-hole-on-the-Firewalla-Gold , but there are different issues there), which could maybe use a tutorial?
Honestly, I'd poke around on it myself, but the amount of time the network would be down while I messed things up and corrected isn't feasible with 2 people WFH and 2 kids SFH here. Smarter people than me probably know how to set this up without having to experiment much.
Thoughts?
It appears to me that there is some kind of exploit in cloudflared container. I have my setup regularly breached and the logs are pointing to a large amount of activity in dockerd.
@Ma At
Not sure what you mean. Can you explain what you mean that your “set-up [is] regularly breached?” What “exploit” do you think you are seeing?
What “Cloudflared container”? Are you using Cloudflare DNS over HTTPS in your Pi-Hole docker?
Can you share the logs?
Is there a way to set maxdbdays and dbinterval with this approach?
In a 'non-docker' setup, this would be set in pihole-ftl.conf...
Thanks in advance!
The pihole-FTL.conf is located
/.firewalla/run/docker/pi-hole/etc-pihole
Thanks Andy!
I was looking and I don't have that directory, in .... /pi-hole/ I only have docker-compose.yaml and etc-dnsmasq.d, which has 01-pihole.conf and 06-rfc6761.conf...
No etc-pihole to be seen...
should be in yaml file:
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'
Found it!
It was indeed in the yaml file, and based on that I found that the conf file is in /data/pi-hole/etc-pihole.
Cheers!
Btw, anyone tried this docker image that includes pihole and unbound yet?
https://github.com/chriscrowe/docker-pihole-unbound/tree/master/one-container
I'm considering giving it a go...
https://help.firewalla.com/hc/en-us/community/posts/1500001172701-Pihole-and-Unbound
Have a look at this before you try.
Firewalla are looking into it, but I failed to get it work
In terms of updating, am I doing anything wrong by reapplying the above procedure (I have the yaml file pointing to :latest) and then running
afterwards to remove old docker images?
Please sign in to leave a comment.