Skip to content

Installation linux

Frank Denis edited this page Sep 14, 2019 · 26 revisions

Installing dnscrypt-proxy on Linux

Unfortunately, providing universal installation instructions for Linux is impossible, since there are many distributions, working their own way, especially when it comes to configuring system settings (DNS).

Furthermore, recent Linux distributions depend on systemd and often install a DNS service by default. Extra steps are thus needed to either remove it, or combine it with dnscrypt-proxy.

If you are new to Linux, installing a new DNS cache and changing the DNS settings may surprisingly be one of the most complicated tasks you will ever have to do. Usually you will want just a single program to serve the DNS protocol on port 53 by way of disabling the competing services.

Distribution-specific instructions

Installation on Linux: overview

Kernel requirements (from golang's minimum requirements):

  • Kernel version 2.6.23 or later.
  • Linux/ARMv5 requires much newer kernels, at least v3.1 (for __kuser_cmpxchg64).
  • We don't support CentOS 5. The kernel is too old (2.6.18).
  • For little-endian MIPS64, kernel version 4.1 is known to fail, and 4.8 works.

Step 1: Get a root shell

On most Linux distributions, the sudo -s command will do the job.

Step 2: check what else is possibly already listening to port 53

If you already have a local DNS cache, it has to be eventually replaced with dnscrypt-proxy. Both can be used simultaneously, but this is outside of the scope of this guide (or, at least, of this Wiki page).

Type the following command:

ss -lp 'sport = :domain'

This may ouptut something similar to:

tcp    LISTEN     0      128                *:*                     users:(("unbound",pid=28146,fd=6))
tcp    LISTEN     0      128                *:*                     users:(("unbound",pid=28146,fd=4))

Uninstall the corresponding package (in the above example: unbound), with a distribution-specific command such as apt-get remove or pacman -R, then check again with ss -lp 'sport = :domain': there shouldn't be anything listening to the domain port any more.

You may also see the port being served by systemd-resolved. That one cannot be uninstalled, but can be disabled with the following commands:

systemctl stop systemd-resolved
systemctl disable systemd-resolved

Check that nothing is listening to port 53 any more:

ss -lp 'sport = :domain'

Looks fine? Let's move to the next step.

Step 3: download and run dnscrypt-proxy

Download dnscrypt-proxy here: dnscrypt-proxy binaries.

There are quite a few files here, but you only need one, matching your operating system and architecture.

dnscrypt-proxy-linux_x86_64-*.tar.gz is the one most people want.

So, download this file and extract it wherever you want. In can be in your home directory, in /opt/dnscrypt-proxy, or wherever you want, really.

It is totally possible to have the executable file in one place, the configuration file in another place, the cache files elsewhere and the log files yet somewhere else.

But if this is the first time you install the software, and you don't have any good reasons to makes things more complicated than they should be, just keep everything in the same directory. At least to start with, and to ensure that everything works as expected.

Then, go crazy if you like. But please don't change everything before even starting the proxy once, and then complain that "it doesn't work". Start with something boring, and gradually tweak it. If you really need to.

Also, do not change your DNS settings at this point.

Just create a configuration file based on the example one:

cp example-dnscrypt-proxy.toml dnscrypt-proxy.toml

And now, for something intense, go to the dnscrypt-proxy directory, and type:


Does it look like it started properly? If not, try to find out why. Here are some hints:

  • dnscrypt-proxy.toml: no such file or directory: copy the example configuration file as dnscrypt-proxy.toml as documented above.
  • not found ELF - not found - Syntax error: ")" unexpected or something similiar: you didn't downlaod the correct file for your operating system and CPU.
  • listen udp bind: permission denied: you are not using a root shell (see step 1). Use sudo -s to get one. Or su if sudo doesn't exist on your system.
  • listen udp bind: address already in use: something is already listening to the DNS port. Maybe something else, maybe a previous instance of dnscrypt-proxy that you didn't stop before starting a new one. Go back to step 2 and try again.
  • dnscrypt-proxy.socket: TCP_NODELAY failed: Protocol not available: Those warnings are expected when using systemd socket activation and can be safely ignored. They happen because systemd tries to apply TCP only options for UDP socket. This shouldn't affect functionality.
  • dnscrypt-proxy.socket: TCP_DEFER_ACCEPT failed: Protocol not available: ditto.
  • systemctl failed: you jumped the gun and didn't follow the instructions above.
  • <something about IPv6 not being available>: edit dnscrypt-proxy.toml and remove , [::1]:53 from listen_addresses.

No errors? Amazing!

Don't close the terminal window yet. We're going to change the system DNS settings.

Step 4: change the system DNS settings

Does your system have a directory called /etc/resolvconf (not the resolv.conf file)? If this is the case, remove it:

apt-get remove resolvconf

Now, make a backup of the /etc/resolv.conf file:

cp /etc/resolv.conf /etc/resolv.conf.backup

Then delete the /etc/resolv.conf file (important, since this can be a dangling link instead of an actual file):

rm -f /etc/resolv.conf

And create a new /etc/resolv.conf file with the following content:

options edns0

Let's check that everything works by sending a first query using dnscrypt-proxy:

./dnscrypt-proxy -resolve

Looks like it was successfully able to resolve Sweet! Try a few more things: web browsing, file downloads, use your system normally and see if you can still connect without any DNS-related issues.

If anything ever goes wrong and you want to revert everything:

  • If you uninstalled resolvconf, reinstall it with apt-get install resolv.conf
  • Restore the /etc/resolv.conf backup: cp /etc/resolv.conf.backup /etc/resolv.conf
  • If you really can't resolve anything any more, even after rebooting, put this in /etc/resolv.conf: nameserver

Step 5: Tweak the configuration file

Hit Control and C in the dnscrypt-proxy terminal window to stop it.

You must still be in the dnscrypt-proxy directory at this point.

The dnscrypt-proxy.toml file has plenty of options you can tweak. Tweak them if you like. But tweak them one by one, so that if you ever screw up, you will know what exact change made this happen.

The message bare keys cannot contain '\n' typically means that there is a syntax error in the configuration file.

Type ./dnscrypt-proxy to start the server, and Control-C to stop it. Test, tweak, stop, test, tweak, stop until you are satisfied.

Are you satisfied? Good, let's jump to step 6!

Step 6: install the proxy as a system service

Hit Control and C in the dnscrypt-proxy terminal window to stop the proxy.

Now, register this as a system service (still with root privileges):

./dnscrypt-proxy -service install

If it doesn't spit out any errors, this is great! Your Linux distribution is compatible with the built-in installer.

This assumes that the executable and the configuration file are in the same directory. If you didn't follow these recommendations, you're on your own modifiying the unit files.

Now that it's installed, it can be started:

./dnscrypt-proxy -service start


If it does spit out errors, steps to your Linux distribution are required. Stay calm, do not drink coffee but hit the gym instead, then look for specific instructions.

Failed to start DNSCrypt client proxy: "systemctl" failed: exit status 5 means that you tried to start the service without installing it first.

Want to stop the service?

./dnscrypt-proxy -service stop

Want to restart the currently running service after a configuration file change?

./dnscrypt-proxy -service restart

Want to uninstall the service?

./dnscrypt-proxy -service uninstall

Want to check that DNS resolution works?

./dnscrypt-proxy -resolve

Want to completely delete that thing?

Delete the directory. Done.

Running as a non-root user

The following command adds the required attributes to the dnscrypt-proxy file so that it can run as a non-root user:

sudo setcap cap_net_bind_service=+pe dnscrypt-proxy

This may not work on some distributions and file systems.

If the content of /etc/resolv.conf doesn't stick

Edit it, then type the following command (in a root console) to lock it:

chattr +i /etc/resolv.conf

To unlock it:

chattr -i /etc/resolv.conf

If you can only reach DNS-over-HTTPS server

When running dnscrypt-proxy, it can be the case that it only successfully reaches DNS-over-HTTPS (DoH) servers, but not DNSCrypt servers. A symptom is that, when running ./dnscrypt-proxy the only servers that do not time out are DoH servers, e.g.:

[NOTICE] [securedns] TIMEOUT
[NOTICE] [securedns-doh] OK (DoH) - rtt: 40ms

In that case, make sure that dnscrypt-proxy can connect peers not only on TCP 443 (HTTPS, and hence DoH), but also on UDP 443. If you are using iptables on Linux, you can add the following rule

iptables -A OUTPUT -p udp --sport 443 -j ACCEPT

and then restart dnscrypt-proxy.


In order to install a new version, just replace the executable file (dnscrypt-proxy) with the new version, and restart the service.

Usage with systemd

dnscrypt-proxy can be started with systemd.

Since this is a complicated topic for experienced Linux users, there is a dedicated page: dnscrypt-proxy with systemd.

Automatic updates of the proxy

The easiest way to keep the proxy up to date is to use an operating system or distribution that always ships up-to-date packages.

As an alternative, for Linux, these instructions might help: Updates.

Clone this wiki locally
You can’t perform that action at this time.