From cade63fd33f526ce180339b1e72f2faad39e4b70 Mon Sep 17 00:00:00 2001
From: faf0 <3429782+faf0@users.noreply.github.com>
Date: Sun, 23 Feb 2025 08:07:22 -0500
Subject: [PATCH] Add guide for DNS-Over-HTTPS (DoH) using dnscrypt-proxy

Signed-off-by: Fabian Foerg <3429782+faf0@users.noreply.github.com>
---
 docs/guides/dns/dnscrypt-proxy.md | 97 +++++++++++++++++++++++++++++++
 mkdocs.yml                        |  1 +
 2 files changed, 98 insertions(+)
 create mode 100644 docs/guides/dns/dnscrypt-proxy.md

diff --git a/docs/guides/dns/dnscrypt-proxy.md b/docs/guides/dns/dnscrypt-proxy.md
new file mode 100644
index 000000000..0029b3f59
--- /dev/null
+++ b/docs/guides/dns/dnscrypt-proxy.md
@@ -0,0 +1,97 @@
+## Configuring DNS-Over-HTTPS using `dnscrypt-proxy` [^guide]
+
+To utilize DNS-Over-HTTPS (DoH) or other encrypted DNS protocols with Pi-hole, preventing man-in-the-middle attacks between Pi-hole and upstream DNS servers, the following sections explain how to install the flexible and stable [dnscrypt-proxy](https://github.com/DNSCrypt/dnscrypt-proxy) tool.
+
+As an alternative tool to this end, consider [cloudflared](https://github.com/cloudflare/cloudflared), for which a [guide](cloudflared.md) exists as well.
+
+### Installing `dnscrypt-proxy`
+
+Raspberry Pi OS and Debian as well as Ubuntu come with packages for `dnscrypt-proxy`, which makes its installation a breeze:
+
+```shell
+sudo apt update
+sudo apt install dnscrypt-proxy
+```
+
+### Configuring `dnscrypt-proxy`
+
+By default, `FTLDNS` listens on the standard DNS port 53.
+
+To avoid conflicts with `FTLDNS`, edit `/usr/lib/systemd/system/dnscrypt-proxy.socket`, ensuring `dnscrypt-proxy` listens on a port that is not in use by other services.
+
+The following settings in `/usr/lib/systemd/system/dnscrypt-proxy.socket`, let `dnscrypt-proxy` listen on localhost on port 5053:
+
+```
+ListenStream=127.0.0.1:5053
+ListenDatagram=127.0.0.1:5053
+```
+
+If you have `cloudflared` installed, you may uninstall it, as `dnscrypt-proxy` will replace it, or choose a unique port for `dnscrypt-proxy`.
+
+Also edit `/etc/dnscrypt-proxy/dnscrypt-proxy.toml`, updating the following settings:
+
+```toml
+# Use systemd socket activation:
+listen_addresses = []
+
+# Populate `server_names` with desired DoH/DNSCrypt upstream DNS servers listed in https://dnscrypt.info/public-servers/.
+# Example for Cloudflare malware-blocking DNS:
+server_names = ['cloudflare-security']
+```
+
+### Configuring Pi-hole Upstream DNS Servers
+
+Run the following command to set the upstream DNS server of Pi-hole to your local `dnscrypt-proxy` instance:
+
+```shell
+sudo pihole-FTL --config dns.upstreams '["127.0.0.1#5053"]'
+```
+
+### Restarting Services
+
+Run the following commands to restart `dnscrypt-proxy` and `FTLDNS`:
+
+```shell
+sudo systemctl restart dnscrypt-proxy.socket
+sudo systemctl restart dnscrypt-proxy.service
+sudo systemctl restart pihole-FTL.service
+```
+
+### Reviewing Service Status
+
+Run the following commands to review the status of each restarted service:
+
+```shell
+sudo systemctl status dnscrypt-proxy.socket
+sudo systemctl status dnscrypt-proxy.service
+sudo systemctl status pihole-FTL.service
+```
+
+Each service is expected to be in active (running) state.
+Review the log files shown if a service didn't restart successfully.
+
+### Configuring Pi-hole
+
+Optionally, confirm in the Pi-hole admin web interface that upstream DNS servers are configured correctly:
+
+* Log into the Pi-hole admin web interface.
+* Navigate to "Settings" and from there to "DNS".
+* Under "Upstream DNS Servers", uncheck all boxes for public DNS servers.
+* Under "Upstream DNS Servers", ensure the box is filled with the IP address and port combination `dnscrypt-proxy` listens on, such as `127.0.0.1#5053`.
+* Click on `Save` at the bottom.
+
+### Updating `dnscrypt-proxy`
+
+Since you installed `dnscrypt-proxy` via APT, updating `dnscrypt-proxy` is a matter of running the following commands:
+
+```shell
+sudo apt update
+sudo apt upgrade
+```
+
+### Uninstalling `dnscrypt-proxy`
+
+To uninstall `dnscrypt-proxy`, run the command `sudo apt remove dnscrypt-proxy`.
+Update the Pi-hole DNS settings to use another upstream DNS server.
+
+[^guide]: Guide based on [this guide by Fabian Foerg | ffoerg.de](https://ffoerg.de/posts/2024-01-28.shtml)
diff --git a/mkdocs.yml b/mkdocs.yml
index 20ac8122c..6c7b6fe27 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -175,6 +175,7 @@ nav:
     - 'DNS':
       - 'unbound': guides/dns/unbound.md
       - 'cloudflared (DoH)': guides/dns/cloudflared.md
+      - 'dnscrypt-proxy (DoH)': guides/dns/dnscrypt-proxy.md
       - 'Upstream DNS Providers': guides/dns/upstream-dns-providers.md
     - 'VPN':
       - 'WireGuard':