Installing dnscrypt-proxy on macOS
Updated: 2019-06-24 13:32 CET
Step 1 - Get a root shell
Terminal application located in
/Applications/Utilities folder, or any third-party terminal, to get a command-line prompt.
Type the following command to get a root shell:
Type your system password, Terminal shows
bash-3.2# as the new prompt. Just if you need to do so, you can go back to the previous prompt by typing
exit then hit return.
Step 2 - Download and run dnscrypt-proxy in Terminal
Download the macOS version,
dnscrypt-proxy-macos-#.##.tar.gz, from dnscrypt-proxy binaries.
Extract it wherever you want, it can be in your home folder, in
/Applications folder, or wherever you want, really.
It is totally possible to have the executable file in one place, the configuration files 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 does not work! Start with something boring, and gradually tweak it, if you really need to.
Do NOT change your DNS settings at this point.
In Terminal, go to the folder where you just extracted it using the
cd command, i.e. something like:
ls -l command should list a dozen of files, among which you must see
Create the required configuration file using the provided example file, pay attention to type its name correctly:
cp example-dnscrypt-proxy.toml dnscrypt-proxy.toml
Be sure to be in the dnscrypt-proxy folder, where you have extracted it, and type the following command to start its installation:
A dozen of
[Notification] lines appear during the installation.
At the end, the prompt will not come back if dnscrypt-proxy is running.
If and only if, you need to get the prompt back, type
ctrl-C to stop dnscrypt-proxy in Terminal.
To restart it, while it's not yet installed as a system service, just type the previous command here above.
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: make a copy of
dnscrypt-proxy.toml, the required config file, as explained above.
not found ELF - not found - Syntax error: ")" unexpectedor something similiar: you didn't download the correct archive for macOS.
listen udp 127.0.0.1:53: bind: permission denied: you are not using a root shell as explain in Step 1. Use
sudo -sto get one.
listen udp 127.0.0.1:53: bind: address already in use: something is already listening to the default DNS port. Maybe something else, a VPN, an ad-blocker, a firewall, maybe another instance of dnscrypt-proxy that you didn't stop before starting the new one.
No errors? Amazing!
Don't close this Terminal window yet, or dnscrypt-proxy will be stopped!
We must change the current macOS DNS settings.
Step 3 - Change macOS DNS settings
System Preferences... in the
Click on the
Select your service, most likely
Ethernet, the one on the top of the list, the one currently in use.
If required, unlock the
Locker on the bottom left to be able to apply the following changes.
Click on the
Advanced... button then on the
If you don't feel confident, just in case dnscrypt-proxy doesn't work, and want to fail over your current settings, add
22.214.171.124, or keep your existing IPs AFTER
127.0.0.1 which must be the first at the top of the list!
You can always remove that later when everything will work fine.
Select each IP, one after another, and click on the
- button to remove all of them from the
DNS Servers list.
When the list is empty, click on the
+ button and enter exactly this IP
Click on the
Don't forget to click on the
Apply button to save these changes!
System Preferences and go back to Terminal.
cmd-N to open a new Terminal window, do not close the one running dnscrypt-proxy.
Check that everything works by sending a first query using dnscrypt-proxy:
./dnscrypt-proxy -resolve example.com
Does it looks like it has successfully resolve example.com?
Sweet! Test 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, open the network preferences pane, and delete
127.0.0.1 from the first line.
If it still does not work, delete all the new IPs you might have manually entered.
Step 4 - Tweak the configuration file
ctrl-C in the dnscrypt-proxy Terminal window to stop it, the prompt must appear.
You must still be in the dnscrypt-proxy folder 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.
./dnscrypt-proxy to start the server, and
ctrl-C to stop it.
Test, tweak, stop, test, tweak, stop until you are satisfied.
bare keys cannot contain '\n' typically means that there is a syntax error in
dnscrypt-proxy.toml configuration file.
Are you satisfied? Good, let's install it permanently.
Step 5 - Install dnscrypt-proxy as a system service
ctrl-C in the dnscrypt-proxy Terminal window to be sure to stop the proxy.
To register it as a system service, you must still have root privileges, type:
./dnscrypt-proxy -service install
If you use a third-party firewall, an anti-virus, an anti-malware... or similar, read the chapter 'Cohabitation with dnscrypt-proxy' at the end of this page to solve potential conflicts.
This assumes that the
dnscrypt-proxy executable and the
dnscrypt-proxy.toml configuration file are in the same directory.
If you didn't follow these recommendations, you are on your own to modify the
/Library/LaunchDaemons/dnscrypt-proxy.plist file to add the required
If it does not report any errors, your macOS version is compatible with the built-in installer.
Let's install it as a permanent background service!
If you stop or uninstall dnscrypt-proxy service, be sure to restore/have IP(s) of
DNS Servers in macOS
System Preferences - Network panel -
DNS tab! For example, 126.96.36.199 and/or 188.8.131.52. will make it.
These commands apply only to dnscrypt-proxy running as a service!
— Start the service
./dnscrypt-proxy -service start
— Stop the service
./dnscrypt-proxy -service stop
— Restart the service after any of the configuration files has been changed
./dnscrypt-proxy -service restart
— Check that DNS resolution works
./dnscrypt-proxy -resolve example.com
— Uninstall the service
./dnscrypt-proxy -service uninstall
— Delete dnscrypt-proxy
To completely uninstall it, uninstall the service, move the folder where you have decompressed the archive to the trash and empty the trash.
To find which version is currently in use, type
./dnscrypt-proxy -version 2.0.25
Step 2, here above, explains how to download the latest version.
Replace only the Unix executable file
dnscrypt-proxy (~11 MB) with the latest version.
Restart the service, type
./dnscrypt-proxy -service restart
Cohabitation with dnscrypt-proxy
First, check that you are using the latest version!
Then, verify that your configuration file is using correct values, that there is no typing errors,...
Also verify that you have not defined an 'impossible/blocking' configuration, carefully read the Configuration chapter in this manual.
— Little Snitch
During the installation, Little Snitch firewall will show several alerts, like:
Terminal via dnscrypt-proxy wants to connect to ... TCP port ...
dnscrypt-proxy wants to connect to ... on UDP/TCP port ...
You must 'Allow' them 'Forever' to run dnscrypt-proxy without problem.
As dnscrypt-proxy service file is not signed, Little Snitch warns you that it might be a 'Suspicious process', it is normal, no need to worry! Always download dnscrypt-proxy from github.com, and if you are paranoid, check it with Minisign tool and/or build it yourself.
— Drive Pulse
During the installation of dnscrypt-proxy as a service, Drive Genius - Drive Pulse might issue an alert if its preference 'Watch Launch Items Changes' is enabled.
It just informs you that the
dnscrypt-proxy.plist file has been added to macOS
/Library/LaunchDaemons/ folder. You must click the
Ignore this change button to accept this installation.
See chapter 'Making things go fast - IPv6 blocking' for DNSmasq.
Control dnscrypt-proxy from the menu bar
Bitbar is a really nice tool to add very useful features to your macOS menu bar.
This includes dnscrypt-proxy switcher to control
dnscrypt-proxy from the menu bar.
So you can keep dnscrypt-proxy always running as a background service, and just toggle it on and off using this menu bar tool.
Error 127.0.0.1:53: bind: address already in use
mDNSResponder listens to port 53 when applications using the native hypervisor run. Docker is an example of an application using this.
mDNSResponser also listens to port 53 when Internet sharing has been enabled.
It is quite annoying, because at the same time macOS doesn't allow to set a specific port for DNS queries. And
mDNSResponder's DNS proxy listens to all IPs, effectively preventing another local DNS resolver or proxy from running.
mDNSResponder's DNS proxy can be disabled in its configuration file:
As this file is in
/System, changing it first requires to disable SIP.
Another workaround is to listen to a different port, and use a local firewall rule to redirect port 53 to it.