How to Use Pi-hole with DoH and Cloudflared (Zero Trust)


I was setting up Pi-hole on a new LXC container on Proxmox and wanted to use DNS over HTTPS (DoH) for DNS traffic, so I referred to the the official guide from Pi-hole that previously worked for me. When I tried to install the cloudflared package using the –legacy flag per the instructions from the Pi-hole website cloudflared service install --legacy, I received the error "Incorrect Usage: flag provided but not defined: -legacy"

root@localsharespace:~ $ sudo cloudflared service install --legacy
Incorrect Usage: flag provided but not defined: -legacy

   cloudflared service install - Install cloudflared as a system service

   cloudflared service install [command options] [arguments...]

   --help, -h  show help (default: false)

This guide will show you how to install cloudflared without the –legacy flag by using the Cloudflare Zero Trust dashboard for tunnels.


You will need an account with Cloudflare. A free account is sufficient.

You will also need to have a website domain in order to setup the Cloudflare Zero Trust tunnel. If you don’t have a domain, you can purchase one for cheap through the Cloudflare Registrar.

Make sure you have done the following:

Create Cloudflare Zero Trust Access Tunnel

There are two ways to create a Cloudflare Tunnel:

  • Remotely using the Zero Trust dashboard, or
  • Locally using the CLI on your server

In this guide, we will create the tunnel using the Zero Trust dashboard:

Log in to the Zero Trust dashboard and go to Access > Tunnels.

Select Create a tunnel.

Enter a name for your tunnel (for example, Pi-hole Cloudflared).

Select Save.

Install cloudflared on your server by using the code provided in the Zero Trust dashboard. Choose the environment that matches your operating system, then copy the commands provided in the box and paste it into a terminal window on your system.

Run the commands that you pasted.

After the command has finished running, select Next.

Note: We will be using cloudflared’s DNS proxy for DoH with Pi-hole. You can use cloudflared’s DNS proxy without having to configure anything in the tabs for Public Hostname or Private Network.

Your tunnel should appear Active on the Zero Trust dashboard.

Also, confirm that the cloudflared daemon is installed on your system by using the following command:

cloudflared --version
cloudflared version 2022.9.0 (built 2022-09-07-0832 UTC)

Start Cloudflared DNS Proxy

Use the below command to start cloudflared’s DNS proxy with a specific port. For this configuration, we will be using port 5553 for the cloudflared DNS proxy:

cloudflared proxy-dns --port 5553

Note: If a port is not specified, the DNS proxy will listen on the default port 53, which is a privileged port and will not work because Pi-hole is already listening on port 53.

After you run above the command, it should return the following output:

INFO[2022-09-19T10:38:57Z] Adding DNS upstream - url:
INFO[2022-09-19T10:38:57Z] Adding DNS upstream - url:
INFO[2022-09-19T10:38:57Z] Starting metrics server on
INFO[2022-09-19T10:38:57Z] Starting DNS over HTTPS proxy server on: dns://localhost:5553

Confirm that cloudflared is running using dig or other DNS client:

dig +short @ -p5553 AAAA

Run Cloudflared as a Service

To automatically start cloudflared on bootup, run cloudflared as a service.

First, setup the service file:

sudo tee /etc/systemd/system/cloudflared-proxy-dns.service >/dev/null <<EOF
Description=DNS over HTTPS (DoH) proxy client

ExecStart=/usr/local/bin/cloudflared proxy-dns --port 5553 --upstream --upstream


Note: You can change the upstream servers to be any of the following:

IPv4 DoH

  • Cloudflare – Unfiltered Fast DNS
  • Cloudflare – Malware Blocking
  • Quad9 – Malware Blocking, DNSSEC Validation
  • Quad9 – Secured w/ECS: Malware blocking, DNSSEC Validation, ECS enabled
  • AdGuard – Default With Ad-block

IPv6 DoH

  • Cloudflare – Unfiltered Fast DNS
    • https://[2606:4700:4700::1111]/dns-query
    • https://[2606:4700:4700::1001]/dns-query
  • Cloudflare – Malware Blocking
    • https://[2606:4700:4700::1112]/dns-query
    • https://[2606:4700:4700::1002]/dns-query
  • Quad9 – Malware Blocking, DNSSEC Validation
    • https://[2620:fe::fe]/dns-query
    • https://[2620:fe::9]/dns-query
  • Quad9 – Secured w/ECS: Malware blocking, DNSSEC Validation, ECS enabled
    • https://[2620:fe::11]/dns-query
    • https://[2620:fe::fe:11]/dns-query
  • AdGuard – Default With Ad-block
    • https://[2a10:50c0::ad1:ff]/dns-query
    • https://[2a10:50c0::ad2:ff]/dns-query

Use the following command if you need to edit the service file and make any changes to your configuration:

sudo nano /etc/systemd/system/cloudflared-proxy-dns.service

After you’re satisfied with your settings, run the following command to enable the service:

sudo systemctl enable --now cloudflared-proxy-dns

If you make any changes to your service file, you can restart cloudflared with the following commands:

systemctl daemon-reload
systemctl restart cloudflared-proxy-dns

Configure Pi-hole

We will now configure Pi-hole to use the cloudflared DNS proxy service:

Log into your Pi-hole admin page.

Select Settings on the left hand navigation menu.

Select the DNS tab at the top of the page.

Under the section for custom Upstream DNS Servers, use for Custom 1 (IPv4) and check the box to enable it. Make sure you don’t have any other Upstream DNS Servers enabled.

Click Save at the bottom of the page.

Your configuration is now done and you should be able to use DoH for all your DNS queries.

Test DNS over HTTPS (DoH)

You can test your system and configuration at the following websites:

Note: Cloudflare’s nameservers support DoT, but DoT will not work using only cloudflared with Pi-hole. If you also want DoT, you can use Stubby with the following upstream servers:

  • tls://
  • tls://

See also DNS Privacy Project for more information.


Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.