Pi‑hole Cloudflared DNS-over-HTTPS Guide

Table of Contents

1 What Is Pi‑hole + Cloudflared and Why Should You Care?

Pi‑hole Cloudflared merges two open‑source tools: Pi‑hole, which blocks ads and trackers network‑wide, and Cloudflared, which sends every DNS query through Cloudflare’s encrypted DNS‑over‑HTTPS endpoint. Together they keep your browsing private, tamper‑proof and clutter‑free on every device.

Key benefits of combining the two:

Privacy – ISPs and public Wi‑Fi can’t snoop on your DNS look‑ups.
Security – Encrypted DNS thwarts spoofing, malware domains and censorship.
Performance – Fewer ads mean faster page loads and less mobile data.

2 Prerequisites

Debian‑based server (Raspberry Pi, Proxmox LXC, Ubuntu VM)
Static LAN IP or DHCP reservation
curl, git, and sudo installed

3 Install Pi‑hole

curl -sSL https://install.pi-hole.net | bash

Choose your network interface, set the web password with pihole -a -p, and take note of the admin URL shown at the end of the installer.

4 Install Cloudflared (DoH Proxy)

sudo mkdir -p /opt/cloudflared
sudo wget -O /opt/cloudflared/cloudflared \
https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64
sudo chmod +x /opt/cloudflared/cloudflared
sudo useradd -r -M -s /usr/sbin/nologin cloudflared

Create /etc/default/cloudflared:

CLOUDFLARED_OPTS="proxy-dns \
--port 5053 \
--upstream https://1.1.1.1/dns-query \
--upstream https://1.0.0.1/dns-query"

Add systemd unit:

sudo tee /etc/systemd/system/cloudflared.service <<'EOF'
[Unit]
Description=cloudflared DNS over HTTPS proxy
After=network-online.target

[Service]
User=cloudflared
ExecStart=/opt/cloudflared/cloudflared $CLOUDFLARED_OPTS
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable --now cloudflared

5 Point Pi‑hole to Cloudflared

Open Settings → DNS and set Custom 1 to 127.0.0.1#5053. Disable all other resolvers, click Save, then flush with pihole restartdns.

6 Verify the Setup

dig example.com @127.0.0.1 -p 5053 +short

You should receive the IPv4/IPv6 answer instantly. In the Pi‑hole Query Log the Status column will show DOH while /var/log/syslog contains cloudflared lines confirming the upstream HTTPS call. If the query hangs, confirm port 5053 is not already in use and that the systemd service is running without errors (systemctl status cloudflared).

7 Hardening & Maintenance

Automatic updates

sudo pihole -up sudo /opt/cloudflared/cloudflared update

Add these commands to /etc/cron.weekly/ to stay patched.

Set Pi‑hole FTLDNS privacy level = “Maximum” to hide client IPs in logs.
Import community blocklists and add custom regex filters to silence telemetry domains.
Periodically prune stale gravity items with pihole -g.

8 Using Pi‑hole Remotely

Create a WireGuard tunnel back home so laptops and phones benefit from the resolver even on 5G or hotel Wi‑Fi. Inside the WireGuard configuration set DNS = 10.6.0.1 (Pi‑hole’s VPN IP). Consider enabling AllowedIPs = 0.0.0.0/0, ::/0 to force all traffic—including DNS—through the tunnel for full privacy.

8.1 Split‑tunnel Option

If you only want DNS and not full Internet routing, keep AllowedIPs limited to 10.6.0.0/24 and fd00:6::/64 so only resolver traffic traverses the tunnel.

9 Backup & Restore

sudo tar -czf pihole-backup_$(date +%F).tgz /etc/pihole /etc/dnsmasq.d

Upload the archive with Restic & Rclone to S3, B2 or OneDrive. To restore, untar the backup, run pihole -r → Reconfigure, and restart DNS.

10 Troubleshooting & FAQs

Pi‑hole admin page won’t load – Ensure port 80/443 isn’t occupied by another service like Nginx.
Cloudflared service fails – Check for architecture mismatch; on ARM devices download the -arm64 binary.
Some sites break – Temporarily disable a blocklist in Group Management → Adlists and reload gravity.

11 Recap

Deploying Pi‑hole Cloudflared gives you ad‑free, encrypted DNS for every LAN device in under 30 minutes. Combine it with WireGuard and automated backups for a bullet‑proof homelab foundation.

Pi‑hole Cloudflared DNS‑over‑HTTPS Guide