diff --git a/docs/guides/dns/dnscrypt-proxy.md b/docs/guides/dns/dnscrypt-proxy.md new file mode 100644 index 000000000..82e93d03c --- /dev/null +++ b/docs/guides/dns/dnscrypt-proxy.md @@ -0,0 +1,90 @@ +## 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'] +``` + +### 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 + +Log into the Pi-hole admin web interface. +Navigate to Settings and from there to the DNS tab. + +Under "Upstream DNS Servers" on the left, uncheck all boxes for public DNS servers. +Under "Upstream DNS Servers" on the right, check only the box for "Custom 1 (IPv4)" and fill the box with the IP address and port `dnscrypt-proxy` listens on, such as `127.0.0.1#5053`: +![Screenshot of Pi-hole DNS configuration](/images/DoHConfig.png) + +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 54e715948..a8c5d2427 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -153,6 +153,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':