Overview

This article provides a short guide to setting up a DNSCrypt-Proxy server on Alpine Linux.

Also see dnscrypt.info. Source code on github.com/jedisct1/dnscrypt-proxy

Features

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

and more...

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.

Installation

Install the dnscrypt-proxy package:

apk add dnscrypt-proxy dnscrypt-proxy-openrc

Also see Alpine Linux package management .

Service commands

Enable the dnscrypt-proxy service so that it starts at boot:

rc-update add dnscrypt-proxy

Start the dnscrypt-proxy service immediately:

rc-service dnscrypt-proxy start

Note: If you are running from RAM, ensure you save your settings using the 'lbu ci' command as necessary. See Alpine local backup.

Note: Configuration options are shown in /etc/dnscrypt-proxy/dnscrypt-proxy.toml. The file includes comments that explain many of the options.

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']

With

listen_addresses = [':53']

Then restart the service with

rc-service dnscrypt-proxy restart

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

openssl req -x509 -nodes -newkey rsa:2048 -days 5000 -sha256 -keyout \ localhost.pem -out localhost.pem

Then copy to the dnscrypt-proxy folder

# cp localhost.pem /etc/dnscrypt-proxy

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

cp /usr/share/dnscrypt-proxy/example-forwarding-rules.txt /etc/dnscrypt-proxy/forwarding-rules.txt

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

home 192.168.1.1

Then restart the service with

rc-service dnscrypt-proxy restart

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

cp /usr/share/dnscrypt-proxy/example-cloaking-rules.txt /etc/dnscrypt-proxy/cloaking-rules.txt

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

rc-service dnscrypt-proxy restart

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: [1].

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: [2]

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: [3]

The referenced links are kept up to date with compliant servers and configuration options.