This article provides a short guide to setting up a DNSCrypt-Proxy server on Alpine Linux.
- DNS traffic encryption and authentication.
- Supports DNSCrypt, DNS-over-HTTPS (DoH) using TLS 1.3, Anonymized DNS and Oblivious DoH (ODoH).
- Local DOH Server
- DNS query monitoring, with separate log files for regular and suspicious queries
- Filtering: block ads, malware, and other unwanted content. Compatible with all DNS services
- Time-based filtering, with a flexible weekly schedule
- Transparent redirection of specific domains to specific resolvers
- DNS caching, to reduce latency and improve privacy
Both the dnscrypt and DoH protocols achieve the same goal of encrypting DNS traffic, keeping the data private from your ISP, or the owners of a public HotSpot. It can be run on local machines, or setup as the DNS Resolver for a house, office, or any other size group; it scales well and uses minimal resources. The user need not be concerned about 'choosing' services with either dnscrypt or DoH protocols - dnscrypt-proxy can pick the fastest resolvers that meet criteria for logging and filtering. Additionally, it supports protocols for tunneling requests using either Anonymized DNS or ODoH.
Also see Alpine Linux package management .
Enable the dnscrypt-proxy service so that it starts at boot:
Start the dnscrypt-proxy service immediately:
Also see Alpine Linux Init System.
Exposing the service on the local network
The main configuration file is /etc/dnscrypt-proxy/dnscrypt-proxy.toml. Any line starting with "#" will be ignored by dnscrypt-proxy. Replace
listen_addresses = ['127.0.0.1:53', '[::1]:53']
listen_addresses = [':53']
Then restart the service with
Enable local DOH Server
This feature is available from version 2.0.34 onwards. Firefox can be configured to use dnscrypt-proxy as a local DOH server. To do this, a certifcate needs to be generated with
Then copy to the dnscrypt-proxy folder
Next, edit the main configuration file is /etc/dnscrypt-proxy/dnscrypt-proxy.toml. Remove the "#" from the beginning of the following lines
[local_doh] listen_addresses = [':3000'] path = "/dns-query" cert_file = "localhost.pem" cert_key_file = "localhost.pem"
In this example, the URL of the local DoH server will be 'https://<host ip address>:3000/dns-query
Start by trying to open this full URL as a regular website with Firefox. The first time, Firefox will notice that the certificate is self-signed and complain about it. This is expected. Click "Advanced" and "I accept the risks". This is okay, you are only going to connect to your own machine. Next, type about:config in the URL bar, search for trr and make the following changes:
Set network.trr.custom_uri and network.trr.uri to https://127.0.0.1:3000/dns-query Set network.trr.mode to 2
Search for esni and make the following change:
Set network.security.esni.enabled to true
The ESNI specification and implementations in Firefox (and Chrome/Brave/Chromium) are still experimental, so it might break some websites. Test if its working here https://www.cloudflare.com/ssl/encrypted-sni/ (don't pay attention to the "Secure DNS" column, the green mark will only be shown when using Cloudflare).
To disable, make the following changes:
Set network.trr.mode to 0
Forwarding internal traffic to a local DNS server
You'd want to do this if you use hostnames on your local network - normally this is managed by your home router. The main configuration file is /etc/dnscrypt-proxy/dnscrypt-proxy.toml. Remove the "#" from the beginning of this line
# forwarding_rules = '/etc/dnscrypt-proxy/forwarding-rules.txt' forwarding_rules = '/etc/dnscrypt-proxy/forwarding-rules.txt'
The copy the example file
Then edit the file, and add a line for your local network. If your network is configured as ".home", and your home router is at 192.168.1.1 then add
Then restart the service with
Creating a Family Friendly DNS Service
Some providers have their own adult content blocking filters. They don't all use the same system, so researching may be worthwhile. The list of providers can be found here public-servers. It might be unwise to select only one service in case it becomes unavailable. Edit /etc/dnscrypt-proxy/dnscrypt-proxy.toml and make an adjustment like this in the Global Settings
# server_names = ['scaleway-fr', 'google', 'yandex', 'cloudflare'] server_names = ['cleanbrowsing-family']
Cloaking rules can also be used to mask certain URIs. For instance to redirect google to enforce safe search. The main configuration file is /etc/dnscrypt-proxy/dnscrypt-proxy.toml. Remove the "#" from the beginning of this line
- cloaking_rules = 'cloaking-rules.txt'
cloaking_rules = 'cloaking-rules.txt'
Then copy the example file
Then edit the file, and add the lines you like
www.google.* forcesafesearch.google.com www.youtube.com restrictmoderate.youtube.com m.youtube.com restrictmoderate.youtube.com youtubei.googleapis.com restrictmoderate.youtube.com youtube.googleapis.com restrictmoderate.youtube.com www.youtube-nocookie.com restrictmoderate.youtube.com
Then restart the service with
More General Filtering
More general filtering can be made based on properties of the server, for instance only choosing servers that don't log; google will log queries made to their servers, even encrypted ones. This is explained here: .
A selection can be made on the following properties:
# Use servers reachable over IPv4 ipv4_servers = true # Use servers reachable over IPv6 -- Do not enable if you don't have IPv6 connectivity ipv6_servers = false # Use servers implementing the DNSCrypt protocol dnscrypt_servers = true # Use servers implementing the DNS-over-HTTPS protocol doh_servers = true # Do not use servers implementing the Oblivious DNS-over-HTTPS protocol odoh_servers = false # Server must support DNS security extensions (DNSSEC) require_dnssec = false # Server must not log user queries (declarative) require_nolog = true # Server must not enforce its own blacklist (for parental control, ads blocking...) require_nofilter = true # Skip resolvers incompatible with anonymization instead of using them directly skip_incompatible = false
Anonymized DNS and Oblivious DoH
Anonymized DNS is specified for the dnscrypt protocol; configuration is detailed here: 
Anonymized DNS uses 'relays' to pass on requests. The request is encrypted first for the target resolver, and then for a 'relay' node. The relay has no knowledge of the request (since it's encrypted for the eventual resolver). The resolver has no idea of the source of the request (since the source is the 'relay'). The response is similarly encrypted, so neither the relay nor the resolver are able to map queries to clients.
Oblivious DoH achieves the same end for a variant of the DoH protocol and it's configuration is explained here: 
The referenced links are kept up to date with compliant servers and configuration options.