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
@Hans
"devices that are set as DNS resolver on the box" means any IP that belongs to the local network.
Regarding setup 2, is there any feature on Gold enabled that may change the upstream DNS server, e.g., family protect or DNS over HTTPs? If there is, Gold will send DNS request to other DNS servers, not 172.0.0.2.
I followed the instructions exactly on my FWG box. However, I don't see any queries from devices on the network. I tested disabling the DNS Booster on 1 of the laptop device. I then started seeing the queries from that device. By disabling the DNS Booster on the device, looks like we lose the Family Protect, Ad Block, Safe Search, DNS over HTTPS, right?
@Binh Tom yes, that's been my experience, and what @Firewalla has said.
Thanks Hans. I like your request to combine the pi-hole into FWG so that we don't lose other features due to disabling the DNS Booster.
Agreed with Hans, I'd like to use pi-hole as the last leg in the chain while keeping the firewalla features. Right now I have most of the features turned off to get pi-hole to work. I can't live without pi-hole now because the internet is an ad machine.
By the way, thanks for the support. I love the active threads and dev work from the firewalla team!!
Have any of you wonderful chaps tried installing DNS over HTTPS on the Pi-hole using
https://docs.pi-hole.net/guides/dns-over-https/
Anyone who installs Pi-hole onto their Firewalla has to turn off the built in service. Just wondering if this would conflict with anything already installed.
Thanks
@Andy brown I haven't tried this yet, but just for simplicity of management I have opted not to use pi-hole with FWG until we figure out if there's a way to layer it with DNS Booster functionality (and the associated protection associated with the booster) with pi-hole. I really think this means we need functionality in FWG to explicitly and manually define the upstream DNS server that is used.
@Firewalla @Support can you comment here? Haven't heard from you all in a while on this topic. Thank you! The new early access release is very good!
I slightly modified the script to run cloudflared docker along with pihole. Also switched off the DoH on the app. (DNSbooster still ON).
The chain goes like this
device => FWG => DNSbooster or Pihole(depends on cached or not) => DoH Upstream
on my try outs.. 18+ block and safesearch worked as intended in this setup.
Need to evaluate in the long run. Also need to check if the cloudflared will get autostarted.
Script is as follows (5054 is the cloudflared port)
```
I am trying to install using this document. I get this error. Any idea?
ERROR: for pihole Cannot start service pihole: OCI runtime create failed: container_linux.go:346: starting container process caused "process_linux.go:449: container init caused \"rootfs_linux.go:58: mounting \\\"/home/pi/.firewalla/run/docker/pi-hole/etc/localtime\\\" to rootfs \\\"/var/lib/docker/overlay2/a47de3d7fa1caf8265cb36a6d8f019ae9664499a1cf323d8f51381936ffc62af/merged\\\" at \\\"/var/lib/docker/overlay2/a47de3d7fa1caf8265cb36a6d8f019ae9664499a1cf323d8f51381936ffc62af/merged/usr/share/zoneinfo/UCT\\\" caused \\\"not a directory\\\"\"": unknown: Are you trying to mount a directory onto a file (or vice-versa)? Check if the specified host path exists and is the expected type
ERROR: Encountered errors while bringing up the project.
If anyone is interested in an ansible implementations of this post, more coming soon.
https://github.com/hhcalder92/ansible-firewalla-role/
@hector, super! We love ansible
Sundar, I got that same error. The problem for me was the last line here:
I am having odd results. I've followed the directions and I end up with my clients having their DNS queries resolved, but nothing gets logged (or blocked) by pi-hole.
Here is dig output from one of my clients
$ dig @172.16.0.2 a-ads.com
; <<>> DiG 9.9.5-9+deb8u19-Raspbian <<>> @172.16.0.2 a-ads.com
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 38369
;; flags: qr rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 1
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 512
;; QUESTION SECTION:
;a-ads.com. IN A
;; ANSWER SECTION:
a-ads.com. 300 IN A 104.26.14.247
a-ads.com. 300 IN A 172.67.69.167
a-ads.com. 300 IN A 104.26.15.247
;; Query time: 24 msec
;; SERVER: 172.16.0.2#53(172.16.0.2)
;; WHEN: Wed Sep 30 13:04:46 EDT 2020
;; MSG SIZE rcvd: 86
And here is the dig output from the firewalla box itself
(Firewalla) $ dig @172.16.0.2 a-ads.com
; <<>> DiG 9.11.3-1ubuntu1.11-Ubuntu <<>> @172.16.0.2 a-ads.com
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 40266
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0
;; QUESTION SECTION:
;a-ads.com. IN A
;; ANSWER SECTION:
a-ads.com. 2 IN A 0.0.0.0
;; Query time: 1 msec
;; SERVER: 172.16.0.2#53(172.16.0.2)
;; WHEN: Wed Sep 30 13:04:32 EDT 2020
;; MSG SIZE rcvd: 43
The pi-hole UI reflects these results too, sort of. The query from the FWG box shows as "172.16.0.1" and there is no record at all from the client machine.
The really odd thing is that I followed these instructions for 1.970 (back when the ip address was 172.0.0.2 and there were not the post_main.d instructions) and everything worked then. I saw all of my clients activity in pi-hole and things were being blocked (I even had to whitelist somethings for my kid's school.)
Anyone have any ideas?
@Nathan Jones
Just to level set: Do you have Family Protect, DNS booster, Ad block, and/or DNS over HTTPS turned on in firewalla?
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!
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
Please sign in to leave a comment.