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
Installation
Join the network
Usage with Docker Compose
Usage with Kubernetes
Customizing Unbound
Deleting everything
Details

Example installation procedures

Installation

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 be public. By convention, it has to look like a domain name (example.com), but it doesn't have to be an actual, registered domain.

Let's pick example.com here.

You probably need to perform the following steps as root.

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: [2001:0db8::412f]:443.

Multiple comma-separated IPs and ports can be specified, as in -E '192.168.1.1:443,[2001:0db8::412f]:443'.

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 port 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.

The init command will print the DNS stamp of your server.

Done.

You can verify that the server is running with:

docker ps

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 state directory):

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 init command 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

Done!

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 metrics, append -M 0.0.0.0:9100 to the end, and -p 9100:9100/tcp after -p 443:443/tcp (see below).

Anonymized DNS

The server can be configured as a relay for the Anonymized DNSCrypt protocol by adding the -A switch to the init command.

The relay DNS stamp will be printed right after the regular stamp.

Prometheus metrics

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: -M 0.0.0.0:9100).

These metrics can be indexed with Prometheus and dashboards can be created with Grafana.

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: -T 10.0.0.1:4443).

The backend server must support the HTTP/2 protocol.

Filtering

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: -v /etc/dnscrypt-server/lists:/opt/encrypted-dns/etc/lists.

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 in minutes.

Create a static IP on GCE. This will be used for the LoadBalancer.
Edit kube/dnscrypt-init-job.yml. Change example.com to your desired hostname and 127.0.0.1 to your static IP.
Edit kube/dnscrypt-srv.yml and change loadBalancerIP to your static IP in both locations.
Run kubectl create -f kube/dnscrypt-init-job.yml to setup your keys.
Run kubectl create -f kube/dnscrypt-deployment.yml to deploy the dnscrypt server.
Run kubectl create -f kube/dnscrypt-srv.yml to 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.

Run docker-compose up
Ctrl-C after keys are setup.
Edit docker-compose.yml to use the start command.
Run docker-compose up

Now you will have a local server running on port 5443.

Customizing Unbound

Changing the Unbound configuration file

To add new configuration to Unbound, add files to the /opt/unbound/etc/unbound/zones 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 my-computer.example.com within your LAN.

To support such custom entries using this image, first map a volume to the zones directory. Add this to your docker run line:

-v /etc/dnscrypt-server/zones:/opt/unbound/etc/unbound/zones

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 .conf file:

touch /etc/dnscrypt-server/zones/example.conf

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"

Troubleshooting

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

Deleting everything

In order to delete everything (containers and images), type:

docker rm --force dnscrypt-server ||:
docker rmi --force jedisct1/dnscrypt-server ||:

Details

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.