From Alpine Linux
Revision as of 18:14, 3 December 2019 by Ianu (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


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


  • DNS traffic encryption and authentication. Supports DNS-over-HTTPS (DoH) using TLS 1.3, and DNSCrypt.
  • 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...


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:

/etc/init.d/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 = ['', '[::1]:53']


listen_addresses = [':53']

Then restart the service with

/etc/init.d/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

sudo 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

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
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 then add


Then restart the service with

/etc/init.d/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

  1. 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

/etc/init.d/dnscrypt-proxy restart