Raspberry Pi DNS-Over-HTTPS (DoH) for Pi-Hole

In this tutorial, we will be showing you how to set up DNS over HTTPS (DoH) for Pi-Hole on your Raspberry Pi.

Raspberry Pi DNS-Over-HTTPS for Pi-Hole

DNS over HTTPS (DoH) is an attempt to improve the security and privacy of your DNS requests by utilizing the HTTPS protocol.

By default, a DNS request sent by Pi-Hole, or your Raspberry Pi is sent over plain text. Unfortunately, this means anyone can intercept this request and use it to track you or even manipulate the data sending you to the wrong website.

Setting up DNS over HTTPS (DoH) for Pi-Hole will make these requests secure between your Raspberry Pi and the upstream DNS provider.

There is still one potential issue with this. Your DNS provider can still monitor your requests, so ensure you use a trustworthy DNS provider. If you want an alternative, you can set up Unbound on your Raspberry Pi for Pi-Hole, but this method has its potential drawbacks and doesn’t solve your ISP being able to snoop on the DNS request.

To get DNS-over-HTTPS working with Pi-Hole, we will utilize the Cloudflared daemon on our Raspberry Pi.

Please note before proceeding, you should set up Pi-Hole on your Raspberry Pi.


Below is the list of equipment we used when setting up DNS-Over-HTTPS for our Raspberry Pi Pi-Hole setup.



This tutorial was last tested on a Raspberry Pi 400 running the latest version of Raspberry Pi OS Bullseye.

Preparing your Raspberry Pi for DNS-Over-HTTPS

To set up DNS-Over-HTTPS for Pi-Hole on our Raspberry Pi, we will need to use the Cloudflared daemon. Cloudflared is the same tool we use to set up a Cloudflare Tunnel on the Raspberry Pi.

Cloudflared allows your Raspberry Pi to make DNS-over-HTTPS requests. The DNS request is made to Cloudflared, which securely proxies that request to your provider.

Over the following steps, we will show you how to install Cloudflared on your Raspberry Pi and prepare it to accept DNS-Over-HTTPS requests from Pi-Hole.

Please note that despite being developed by Cloudflare, you can use Cloudflared to connect to DNS-Over-HTTPS providers such as Google.

Installing Required Software

1. Our first step is to ensure we are running up-to-date software.

Use the command below to update the package list and upgrade any out-of-date packages.

sudo apt update
sudo apt upgrade

2. Next, we must install the “curl” and “lsb-release” packages to our device using the command below.

These packages make it easier to download and install Cloudflared.

sudo apt install curl lsb-release

Adding the Cloudflare Package Repository

3. Our next step is to add the official Cloudflare package repository. This will ensure you can easily update the cloudflared daemon.

Before we can add the repository itself, we must download the GPG key. This key helps ensure the packages you are installing are valid.

curl -L https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-archive-keyring.gpg >/dev/null

4. Now that we have saved the GPG key, we can add the Cloudflared repository using the following command in the terminal.

echo "deb [signed-by=/usr/share/keyrings/cloudflare-archive-keyring.gpg] https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main" | sudo tee  /etc/apt/sources.list.d/cloudflared.list

5. As we made changes to the available repositories, we must update the package list again.

To update this list, use the command below.

sudo apt update

Installing Cloudflared and Creating a User

6. All we need to do now to install Cloudflared to your Raspberry Pi is to run the following command.

sudo apt install cloudflared

7. For us to use Cloudflared to proxy DNS-Over-HTTPS requests from Pi-Hole on our Raspberry Pi we will need to create a user for the daemon to run under.

Use the following command to create a user called “cloudflared“.

  • -s“: We use the “-s” option to set the user’s shell to something that can’t be utilized.
  • -r“: This option is used to tell the system to create this user as a system user.
  • -M“: Finally, we also tell the useradd command that it shouldn’t generate a home directory for this user.
sudo useradd -s /usr/sbin/nologin -r -M cloudflared

Configure Cloudflared to Proxy DNS-Over-HTTPS Requests on the Raspberry Pi

8. To set up DNS-Over-HTTPS for Pi-Hole on your Raspberry Pi, we must create a service that will run Cloudflared. This service will pass options to Cloudflared so that it will operate as a DoH proxy.

Begin writing this service file by using the command below within the terminal.

sudo nano /etc/systemd/system/cloudflared.service

9. Within this file, type the following lines to set up the service.

Description=cloudflared DNS over HTTPS proxy
After=syslog.target network-online.target

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


10. The one line you will find interesting is the one shown below. Here is where we specify the call to the Cloudflared daemon.

  • We pass in the “proxy-dns” option to tell the daemon to operate as a proxy for DNS-Over-HTTPS (DOH) on our Raspberry Pi for Pi-Hole.
  • Next, we use the “--port” option to tell Cloudflared to operate its DoH proxy on port 5053.
  • Finally, we use the “--upstream” option to specify where to connect for DNS requests. You can have multiple upstream sources.

    In the example below, we use Cloudflare’s DNS-Over-HTTPS servers, so we use “” and ““. You can change these values to the ones provided by your DNS provider.
ExecStart=/usr/local/bin/cloudflared proxy-dns --port 5053 --upstream --upstream

11. Once you have finished typing these lines into the file, save and quit by pressing CTRL + X, followed by Y, then the ENTER key.

Starting the DNS-Over-HTTPS Cloudflared Service

12. With the service created, our next step is to enable the service by using the following command.

Enabling the service allows it to automatically start when your Raspberry Pi powers on.

sudo systemctl enable cloudflared

13. Our next step is to start the Cloudflared service by running the command below within the terminal.

sudo systemctl start cloudflared

Testing that DNS-Over HTTPS (DoH) is working on your Raspberry Pi

14. Before we go and configure Pi-Hole on your Raspberry Pi to use DNS-Over-HTTPS, let us make a request to our new proxy.

dig @ -p 5053 pimylifeup.com

15. If everything works correctly, you should see a response like the one below.

This result shows that our Raspberry Pi could successfully make a secure DNS request using our Cloudflared proxy.

; <<>> DiG 9.16.37-Debian <<>> @ -p 5053 pimylifeup.com
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 31334
;; flags: qr rd ra ad; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 1

; EDNS: version: 0, flags:; udp: 4096
; COOKIE: f28fd7303cd4a1ed (echoed)
;pimylifeup.com.                        IN      A

pimylifeup.com.         300     IN      A
pimylifeup.com.         300     IN      A
pimylifeup.com.         300     IN      A

;; Query time: 191 msec
;; WHEN: Mon Jun 05 05:12:41 BST 2023
;; MSG SIZE  rcvd: 145

Configuring Pi-Hole to use DNS-Over-HTTPS (DoH)

16. Now that we have set up a DNS-Over-HTTPS (DoH) proxy on the Raspberry Pi, we will want to point Pi-Hole to the proxy.

With the Pi-Hole web interface open in your web browser, navigate to the settings page. You can find this by clickingSettings” in the sidebar.

Open settings from within the Pi-Hole interface

17. With the settings page open, change to the DNS settings by clickingDNS” within the top navigation bar.

This is where you will be able to change Pi-Hole to use DNS-Over-HTTPS.

Change to the DNS settings page

18. We are finally in the right spot to change Pi-Hole to use our Raspberry Pi’s DoH proxy.

Start by ensuring that all of the upstream DNS servers are unticked on the left-hand side (1.).

Next, we need to enable a custom DNS server by ticking a checkbox and then typing in “” (2.).

Finally, once you have made these changes to Pi-Hole’s configuration, scroll down and click the “Save” button or press the ENTER key.

Enable DNS-Over-HTTPS from your Raspberry Pi Pi-Hole

19. If your settings have been saved, you will see a message similar to the one below.

Your Raspberry Pi’s Pi-Hole server now uses DNS-Over-HTTPS (DoH) to make DNS requests. This improves your privacy and security while browsing the internet.

DNS-Over-HTTPS settings saved


You should hopefully have Pi-Hole configured to use DNS-Over-HTTPS on your Raspberry Pi at this stage.

DNS-Over-HTTPS or DoH is a way of helping improve the privacy of your DNS requests. It does this by using the HTTPS protocol to hide the DNS lookup from prying eyes such as your ISP. It also significantly reduces the chance of someone intercepting and modifying the request.

Please comment below if you have issues getting DNS-Over-HTTPS to work with Pi-Hole.

If you found this tutorial helpful, be sure to check out our many other Raspberry Pi projects.


  1. Avatar for Maarten
    Maarten on

    If you live in the EU it is best to use dns0.eu (GDPR save or AVG for the Dutch)
    DNS53 (IPv4)

  2. Avatar for Peter Gräbner
    Peter Gräbner on

    Thanks for the tutorial, worked fine on PI5

  3. Avatar for Thomas
    Thomas on

    Awesome tutorial. Works like a charme. Thank you very much for your work.

  4. Avatar for alan
    alan on

    Another great tutorial, thanks emmett.
    Is it possible to use this cloudflared with quad 9, instead of cloudflare DNS servers?

    I also wanted to ask would you consider making a tutorial for Firefly 3 for the RPI, i cant find a decent tutorial online that is as easy as your tutorials 🙂

    Love your site BTW

    1. Avatar for Emmet
      Emmet on

      Hi Alan,

      Of course! To use Quad9 instead of Cloduflare’s DNS server you will want to change this line within the service file.

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

      Instead of this line pointing to the Cloudflare DNS-Over-HTTPS upstream you will instead want to point it to Quad9’s which would mean the line should look something like we have shown below.

      ExecStart=/usr/local/bin/cloudflared proxy-dns --port 5053 --upstream https://dns.quad9.net/dns-query

      On the note of Firefly 3 it does look like an interesting project that would be good to run on a Raspberry Pi. Will add it to my todo list so I can look into it further but at a glance it should be a fairly straightforward guide to write out.


  5. Avatar for Matt
    Matt on

    This is great. Thanks for the guide. Is the setup any different if I am already am using CloudFlare tunnels.?

    1. Avatar for Emmet
      Emmet on

      Hi Matt,

      This should work alongside your Cloudflare tunnels as we are launching a separate instance of Cloudflared.


Leave a Reply

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