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:
  • Firewalla Gold and Gold Plus
  • Firewalla Gold SE
  • Firewalla Gold Pro
  • Firewalla Purple and Purple SE
  • Firewalla Orange
• 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

1. a network as your docker network, we use 172.16.0.0/24 in this tutorial
2. a static IP for your pi-hole instance, we use 172.16.0.2 in this tutorial
3. 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 --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

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/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/