DNSCrypt server Docker image
Run your own caching, non-censoring, non-logging, DNSSEC-capable, DNSCrypt-enabled DNS resolver virtually anywhere!
If you are already familiar with Docker, it shouldn't take more than 5 minutes to get your resolver up and running.
Table of contents:
- DNSCrypt server Docker image
- Example installation procedures
- Join the network
- Usage with Docker Compose
- Usage with Kubernetes
- Customizing Unbound
- Deleting everything
Example installation procedures
- How to setup your own DNSCrypt server in less than 10 minutes on Scaleway
- DNSCrypt server with vultr.com
Think about a name. This is going to be part of your DNSCrypt provider name.
If you are planning to make your resolver publicly accessible, this name will
By convention, it has to look like a domain name (
example.com), but it doesn't
have to be an actual, registered domain.
You probably need to perform the following steps as
Download, create and initialize the container:
docker run --name=dnscrypt-server -p 443:443/udp -p 443:443/tcp \ --restart=unless-stopped \ -v /etc/dnscrypt-server/keys:/opt/encrypted-dns/etc/keys \ jedisct1/dnscrypt-server init -N example.com -E '192.168.1.1:443'
This will only accept connections via DNSCrypt on the standard port (443). Replace
192.168.1.1 with the actual external IP address (not the internal Docker one)
clients will connect to.
IPv6 addresses should be enclosed in brackets; for example:
Multiple comma-separated IPs and ports can be specified, as in
If you want to use a different port, replace all occurrences of
443 with the alternative port in the
command above (including
-p ...). But if you have an existing website that should be accessible on
443, the server can transparently relay non-DNS traffic to it (see below).
-v /etc/dnscrypt-server:/opt/encrypted-dns/etc/keys means that the path
/opt/encrypted-dns/etc/keys, internal to the container, is mapped to
/etc/dnscrypt-server/keys, the directory we just created before. Do not change
/opt/encrypted-dns/etc/keys. But if you created a directory in a different location, replace
/etc/dnscrypt-server/keys accordingly in the command above.
Note: on MacOS, don't use
-v ...:.... Remove that part from the command-line, as current versions of MacOS and Docker don't seem to work well with shared directories.
init command will print the DNS stamp of your server.
You can verify that the server is running with:
Note: if you previously created a container with the same name, and Docker complains that the name is already in use, remove it and try again:
docker rm --force dnscrypt-server
Updating the container
In order to install the latest version of the image, or change parameters, use the following steps:
- Update the image
docker pull jedisct1/dnscrypt-server
- Verify that the directory containing the keys actually has the keys (a
ls -l /etc/dnscrypt-server/keys
If you have some content here, skip to step 3.
Nothing here? Maybe you didn't use the
-v option to map container files to a local directory when creating the container.
In that case, copy the data directly from the container:
docker cp dnscrypt-server:/opt/encrypted-dns/etc/keys ~/keys
- Stop the existing container:
docker stop dnscrypt-server docker ps # Check that it's not running
- Rename the existing container:
docker rename dnscrypt-server dnscrypt-server-old
- Use the
initcommand again and start the new container:
docker run --name=dnscrypt-server -p 443:443/udp -p 443:443/tcp \ --restart=unless-stopped \ -v /etc/dnscrypt-server/keys:/opt/encrypted-dns/etc/keys \ jedisct1/dnscrypt-server init -N example.com -E '192.168.1.1:443' # (adjust accordingly) docker ps # Check that it's running
- Delete old container:
docker rm dnscrypt-server-old
Parameters differ from the ones used in the previous container.
For example, if you originally didn't activate relaying
but want to enable it, append
-A to the command. Or if you want to enable
-M 0.0.0.0:9100 to the end, and
-p 9100:9100/tcp after
-p 443:443/tcp (see below).
The server can be configured as a relay for the Anonymized DNSCrypt protocol by adding the
-A switch to the
The relay DNS stamp will be printed right after the regular stamp.
Metrics are accessible inside the container as http://127.0.0.1:9100/metrics.
They can be made accessible outside of the container by adding the
-M option followed by the listening IP and port (for example:
TLS (including HTTPS and DoH) forwarding
If the DNS server is listening to port
443, but you still want to have a web (or DoH) service accessible on that port, add the
-T switch followed by the backend server IP and port to the
init command (for example:
The backend server must support the HTTP/2 protocol.
The server can be used block domains. For example, the
sfw.scaleway-fr server uses that feature to provide a service that blocks websites possibly not suitable for children.
In order to do so, create a directory that will contain the blacklists:
mkdir -p /etc/dnscrypt-server/lists
And put the list of domains to block in a file named
/etc/dnscrypt-server/lists/blacklist.txt, one domain per line.
Then, follow the upgrade procedure, adding the following option to the
docker run command:
Join the network
If you want to help against DNS centralization and surveillance, announce your server and/or relay on the list of public DNS DoH and DNSCrypt servers.
The best way to do so is to send a pull request to the dnscrypt-resolvers repository.
Usage with Kubernetes
Kubernetes configurations are located in the
kube directory. Currently these assume
a persistent disk named
dnscrypt-keys on GCE. You will need to adjust the volumes
definition on other platforms. Once that is setup, you can have a dnscrypt server up
- Create a static IP on GCE. This will be used for the LoadBalancer.
example.comto your desired hostname and
127.0.0.1to your static IP.
loadBalancerIPto your static IP in both locations.
kubectl create -f kube/dnscrypt-init-job.ymlto setup your keys.
kubectl create -f kube/dnscrypt-deployment.ymlto deploy the dnscrypt server.
kubectl create -f kube/dnscrypt-srv.ymlto expose your server to the world.
To get your public key just view the logs for the
dnscrypt-init job. The public
IP for your server is merely the
dnscrypt service address.
Usage with Docker Compose
You can setup a server very quickly with Docker Compose.
- Ctrl-C after keys are setup.
docker-compose.ymlto use the start command.
Now you will have a local server running on port 5443.
Changing the Unbound configuration file
To add new configuration to Unbound, add files to the
directory. All files ending in
.conf will be processed. In this manner, you
can add any directives to the
server: section of the Unbound configuration.
Serving custom DNS records on a local network
While Unbound is not a full authoritative name server, it supports resolving
custom entries in a way that is serviceable on a small, private LAN. You can use
unbound to resolve private hostnames such as
To support such custom entries using this image, first map a volume to the zones
directory. Add this to your
docker run line:
The whole command to create and initialize a container would look something like this:
docker run --name=dnscrypt-server \ -v /etc/dnscrypt-server/zones:/opt/unbound/etc/unbound/zones \ -p 443:443/udp -p 443:443/tcp --net=host \ jedisct1/dnscrypt-server init -N example.com -E '192.168.1.1:443'
Create a new
Now, add one or more unbound directives to the file, such as:
local-zone: "example.com." static local-data: "my-computer.example.com. IN A 10.0.0.1" local-data: "other-computer.example.com. IN A 10.0.0.2"
If Unbound doesn't like one of the newly added directives, it will probably not respond over the network. In that case, here are some commands to work out what is wrong:
docker logs dnscrypt-server docker exec dnscrypt-server /opt/unbound/sbin/unbound-checkconf
In order to delete everything (containers and images), type:
docker rm --force dnscrypt-server ||: docker rmi --force jedisct1/dnscrypt-server ||:
- A minimal Ubuntu Linux as a base image.
- Caching resolver: Unbound, with DNSSEC, prefetching, and no logs. The number of threads and memory usage are automatically adjusted. Latest stable version, compiled from source. qname minimisation is enabled.
- encrypted-dns-server. Compiled from source.
Keys and certificates are automatically rotated every 8 hour.