dnscrypt-proxy

Related articles
Domain name resolution
This article or section needs expansion.
Reason:
What is the difference to
dnscrypt-wrapper
? (Discuss in
Talk:Dnscrypt-proxy
)
dnscrypt-proxy
is a DNS proxy client with support for the encrypted DNS protocols
DNS over HTTPS
and
DNSCrypt
, which can be used to prevent man-in-the-middle attacks and eavesdropping.
dnscrypt-proxy
is also compatible with
DNSSEC
.
Installation
Install
the
dnscrypt-proxy
package.
Configuration
The default configuration file referred to is at
/etc/dnscrypt-proxy/dnscrypt-proxy.toml
.
Tip
While
dnscrypt-proxy
has no manual currently, the project maintains an extensive
configuration wiki
.
Startup
Note
Even though there are two ways to start the proxy, upstream recommends the
service
one.
[1]
[2]
The service can be
started
in two mutually exclusive ways (i.e. only one of the two may be
enabled
):
With the systemd service
dnscrypt-proxy.service
.
The
listen_addresses
option must be configured (e.g.
listen_addresses = ['127.0.0.1:53', '[::1]:53']
) in the configuration file when using the service.
Through socket activation using
dnscrypt-proxy.socket
.
The
listen_addresses
option must be set to empty (i.e.
listen_addresses = [ ]
) in the configuration file, since systemd is taking care of the socket configuration.
Select resolver
By leaving
server_names
commented out in the configuration file,
dnscrypt-proxy
will choose the fastest server from the sources already configured under
[sources]
[3]
.  The lists will be downloaded, verified, and automatically updated
[4]
. Thus, configuring a specific set of servers is optional.
To manually set which server is used, uncomment the
server_names
variable in the configuration file and select one or more of the servers. For example, to use Cloudflare's servers:
server_names = ['cloudflare', 'cloudflare-ipv6']
Note
This example uses Cloudflare's public DNS resolver. Replace it with a DNS resolver you trust. See
Domain name resolution#Third-party DNS services
.
A full list of resolvers is located at the
upstream page
or
Github
. If
dnscrypt-proxy
has run successfully on the system before,
/var/cache/dnscrypt-proxy/public-resolvers.md
will also contain a list. Look at the description for servers note which validate
DNSSEC
, do not log, and are uncensored. These requirements can be configured globally with the
require_dnssec
,
require_nolog
,
require_nofilter
options.
Modify resolv.conf and coordinate with other local domain name resolvers
Modify the
resolv.conf
file and replace the current set of resolver addresses with the loopback IP addresses and options
[5]
:
/etc/resolv.conf
nameserver ::1
nameserver 127.0.0.1
options edns0
Next, existing services doing domain name resolution must be configured not to overwrite the settings. See
resolv.conf#Overwriting of /etc/resolv.conf
for details.
They can be used, if they are configured to bind to different addresses than
localhost
and forward DNS requests to
localhost
port
53
. For example,
systemd-resolved
uses address
127.0.0.53
by default.
Disable any services bound to port 53
Tip
If using
#Unbound
as your local DNS cache this section can be ignored, as
unbound
runs on port 53 by default.
To see if any programs are using port
53
, run:
$ ss -lp 'sport = :domain'
If the output contains more than the first line of column names, you need to disable whatever service is using port
53
. For example,
NetworkManager may try to activate a resolver automatically
, but other network managers may have analogous components. You are ready to proceed once the above command outputs nothing more than the header line:
Netid State   Recv-Q  Send-Q   Local Address:Port     Peer Address:Port Process
Start systemd service
Finally,
start/enable
the
dnscrypt-proxy.service
unit or
dnscrypt-proxy.socket
, depending on which method you chose above.
Check if dnscrypt-proxy is working
Open the browser and head to
DnsLeakTest
and do an extended test, if the results show servers that you have set in the configuration files it means that dnscrypt-proxy is working, otherwise something is wrong.
Tips and tricks
Enabling, downloading and auto-updating filter lists / block lists
This article or section is being considered for removal.
Reason:
Overwriting files in
/usr/share/dnscrypt-proxy/utils/generate-domains-blocklist/
that are owned by the
dnscrypt-proxy
package is not a good idea. (Discuss in
Talk:Dnscrypt-proxy#automatic blocklist updates
)
Configure filter list sources in /usr/share/dnscrypt-proxy/utils/generate-domains-blocklist/domains-blocklist.conf. For example:
# NextDNS CNAME cloaking list
https://raw.githubusercontent.com/nextdns/cname-cloaking-blocklist/master/domains
# AdGuard Simplified Domain Names filter
https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt
# OISD.NL Big:
https://big.oisd.nl/domainswild
# HaGeZi Multi Pro
https://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/pro-onlydomains.txt
# HaGeZi Thread Intelligence Feeds
https://raw.githubusercontent.com/hagezi/dns-blocklists/main/wildcard/tif-onlydomains.txt
Create a service to download & combine filter lists. 
/etc/systemd/system/dnscrypt-filterlist-update.service:
[Unit]
Description=DNSCrypt Filterlist Update

[Service]
Type=oneshot
User=root
WorkingDirectory=/usr/share/dnscrypt-proxy/utils/generate-domains-blocklist/
ExecStart=generate-domains-blocklist -a domains-allowlist.txt -o blocklist.txt ; sleep 2 ; systemctl restart dnscrypt-proxy.service

[Install]
WantedBy=multi-user.target
Create a time to run on boot but also every 5 hours.
/etc/systemd/system/dnscrypt-filterlist-update.timer:
[Unit]
Description=Run 15min after boot and every 5 hours (DNSCrypt Filterlist Update)

[Timer]
OnBootSec=15min
OnUnitActiveSec=5h

[Install]
WantedBy=timers.target
Enable the timer:
systemctl daemon-reload
systemctl enable dnscrypt-filterlist-update.timer
Configure DNSCrypt to apply the created filter rules.
/etc/dnscrypt-proxy/dnscrypt-proxy.toml:
blocked_names_file = '/usr/share/dnscrypt-proxy/utils/generate-domains-blocklist/blocklist.txt'
log_file = '/var/log/dnscrypt-proxy/blocked-names.log'
Local DNS cache configuration
Tip
dnscrypt-proxy
can cache entries without relying on another program. This feature is enabled by default with the line
cache = true
in the configuration file.
It is recommended to run
dnscrypt-proxy
as a forwarder for a local DNS cache if not using
dnscrypt-proxy's
cache feature; otherwise, every single query will make a round-trip to the upstream resolver. Any local DNS caching program should work. In addition to setting up
dnscrypt-proxy
, you must setup your local DNS cache program.
Change port
In order to forward queries from a local DNS cache,
dnscrypt-proxy
should listen on a port different from the default
53
, since the DNS cache itself needs to listen on
53
and query
dnscrypt-proxy
on a different port. Port number
54
is used as an example in this section.
There are two methods for changing the default port:
Socket method
Edit
dnscrypt-proxy.socket
with the following contents:
[Socket]
ListenStream=
ListenDatagram=
ListenStream=127.0.0.1:54
ListenStream=[::1]:54
ListenDatagram=127.0.0.1:54
ListenDatagram=[::1]:54
When queries are forwarded from the local DNS cache to
54
,
dnscrypt-proxy.socket
will start
dnscrypt-proxy.service
.
Service method
Edit the
listen_addresses
option in
/etc/dnscrypt-proxy/dnscrypt-proxy.toml
with the following:
listen_addresses = ['127.0.0.1:54', '[::1]:54']
Example local DNS cache configurations
The following configurations should work with
dnscrypt-proxy
and assume that it is listening on port
54
.
Unbound
Configure
Unbound
to your liking (in particular, see
Unbound#Local DNS server
) and add the following lines to the end of the
server
section in
/etc/unbound/unbound.conf
:
do-not-query-localhost: no
forward-zone:
  name: "."
  forward-addr: ::1@54
  forward-addr: 127.0.0.1@54
Tip
If you are setting up a server, add
interface: 0.0.0.0@53
and
access-control:
your-network
/
subnet-mask
allow
inside the
server:
section so that the other computers can connect to the server. A client must be configured with
nameserver
address-of-your-server
in
/etc/resolv.conf
.
Restart
unbound.service
to apply the changes.
dnsmasq
Configure dnsmasq as a
local DNS cache
. The basic configuration to work with
dnscrypt-proxy
:
/etc/dnsmasq.conf
no-resolv
server=::1#54
server=127.0.0.1#54
listen-address=::1,127.0.0.1
If you configured
dnscrypt-proxy
to use a resolver with enabled
DNSSEC
validation, make sure to enable it also in dnsmasq:
/etc/dnsmasq.conf
conf-file=/usr/share/dnsmasq/trust-anchors.conf
dnssec
Restart
dnsmasq.service
to apply the changes.
pdnsd
Install
pdnsd
. A basic configuration to work with
dnscrypt-proxy
is:
/etc/pdnsd.conf
global {
    perm_cache = 1024;
    cache_dir = "/var/cache/pdnsd";
    run_as = "pdnsd";
    server_ip = 127.0.0.1;
    status_ctl = on;
    query_method = udp_tcp;
    min_ttl = 15m;       # Retain cached entries at least 15 minutes.
    max_ttl = 1w;        # One week.
    timeout = 10;        # Global timeout option (10 seconds).
    neg_domain_pol = on;
    udpbufsize = 1024;   # Upper limit on the size of UDP messages.
}

server {
    label = "dnscrypt-proxy";
    ip = 127.0.0.1;
    port = 54;
    timeout = 4;
    proxy_only = on;
}

source {
    owner = localhost;
    file = "/etc/hosts";
}
Restart
pdnsd.service
to apply the changes.
Enable EDNS0
This article or section needs expansion.
Reason:
Name the advantages/motivation for enabling this. (Discuss in
Talk:Dnscrypt-proxy
)
Extension Mechanisms for DNS
that, among other things, allows a client to specify how large a reply over UDP can be.
Add the following line to your
/etc/resolv.conf
:
options edns0
Test EDNS0
This article or section is out of date.
Reason:
OARC's DNS Reply Size Test Server has been decommissioned. (Discuss in
Talk:Dnscrypt-proxy
)
Make use of the
DNS Reply Size Test Server
, use the
drill
command line tool to issue a TXT query for the name
rs.dns-oarc.net
:
$ drill rs.dns-oarc.net TXT
With
EDNS0
supported, the "answer section" of the output should look similar to this:
rst.x3827.rs.dns-oarc.net.
rst.x4049.x3827.rs.dns-oarc.net.
rst.x4055.x4049.x3827.rs.dns-oarc.net.
"2a00:d880:3:1::a6c1:2e89 DNS reply size limit is at least 4055 bytes"
"2a00:d880:3:1::a6c1:2e89 sent EDNS buffer size 4096"
Troubleshooting
"read-only file system" or "no such file or directory" when caching file
Set the correct
ownership
of
/var/cache/dnscrypt-proxy
, usually
dnscrypt-proxy:dnscrypt-proxy
.