Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
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.
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
- 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 127.0.0.1:domain *:* users:(("unbound",pid=28146,fd=6)) tcp LISTEN 0 128 127.0.0.1:domain *:* 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-resolve. 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.tomlas documented above.
not found ELF - not found - Syntax error: ")" unexpectedor something similiar: you didn't downlaod the correct file for your operating system and CPU.
listen udp 127.0.0.1:53: bind: permission denied: you are not using a root shell (see step 1). Use
sudo -sto get one. Or
sudodoesn't exist on your system.
listen udp 127.0.0.1:53: 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
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
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:
nameserver 127.0.0.1 options edns0 single-request-reopen
Let's check that everything works by sending a first query using dnscrypt-proxy:
./dnscrypt-proxy -resolve example.com
Looks like it was successfully able to resolve
example.com? 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
cp /etc/resolv.conf.backup /etc/resolv.conf
- If you really can't resolve anything any more, even after rebooting, put this in
Step 5: Tweak the configuration file
C in the
dnscrypt-proxy terminal window to stop it.
You must still be in the
dnscrypt-proxy directory at this point.
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.
bare keys cannot contain '\n' typically means that there is a syntax error in the configuration file.
./dnscrypt-proxy to start the server, and
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
C in the
dnscrypt-proxy terminal window to stop the proxy.
Now, register this as a system service (still with
./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 example.com
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
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
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.