jqtype/dnscrypt-server-modns repository overview

This repo is a forked version of dnscrypt-server-docker⁠. From the original version, this has been modified to employ a PoC implementation of μODNS that is a multiple-relay-based anonymization protocol for DNS queries.

μODNS has been designed to protect user privacy in DNS even if a relay(s) collude with a resolver(s), which cannot be solved in existing DNS anonymization protocols. For the detailed information of μODNS, please refer to our concept paper below:

Our PoC μODNS relays have been implemented as a fork of encrypted-dns-server⁠ and are available at https://github.com/junkurihara/encrypted-dns-server-modns⁠. Publicly available relays for PoC μODNS are listed at https://github.com/junkurihara/experimental-resolvers⁠.

Docker image of dnscrypt-server-modns is available at DockerHub⁠, which is integrated with the internal Unbound full-service resolver. A vanilla docker image of only encrypted-dns-server-modns is also given here⁠.

⁠Configuration

Unlike the original dnscrypt-server-docker, configuration of .env and docker-compose.yml is needed for easy deployment.

# your server name
DOMAIN_NAME=xxxxxx.com

# exposed addresses reachable from the Internet.
IPV4_ADDR=xxxxx
IPV6_ADDR=xxxxxx

# exposed port to the Internet
PORT=50443

# If Debug=true, then you can see debug messages in the log file.
DEBUG=true

# Log rotation setting for log file.
LOGROTATE_SIZE=10M
LOGROTATE_NUM=10

version: "3"
services:
  dnscrypt-server:
    image: jqtype/dnscrypt-server-modns:latest
    container_name: dnscrypt-server
    ## Comment out the following two lines if you build this image yourself.
    # build:
    #   context: ./
    ulimits:
      nofile:
        soft: 90000
        hard: 90000
    restart: unless-stopped
    env_file: .env
    ports:
      - ${PORT}:${PORT}/udp
      - ${PORT}:${PORT}/tcp
    expose:
      - 9100 # for prometheus server working in same docker internal network
      - 553  # expose unbound port
    command: init -A -N ${DOMAIN_NAME} -E '${IPV4_ADDR}:${PORT},[${IPV6_ADDR}]:${PORT}' -M 0.0.0.0:9100
    # make sure that ./data and ./log have been created.
    volumes:
      - ./.env:/opt/encrypted-dns/etc/.env
      - ./data/keys:/opt/encrypted-dns/etc/keys
      - ./data/lists:/opt/encrypted-dns/etc/lists
      - ./log/dnscrypt-server:/var/log/dnscrypt-server
    # network_mode: "host"
    networks:
      net-modns:

networks:
  net-modns:
    name: net-modns
    driver: bridge
    ipam:
      driver: default
      config:
        - subnet: 192.168.53.0/24 # change as you like

If you want to configure the setting of encrypted-dns-server-modns, it should be done directly by modifying ./encrypted-dns.toml.in and then build your own image! The configuration is given here⁠.

NOTE: IPv6 may not work due to Docker environment. (network_mode=host maybe required.)

If you deploy your own μODNS relay, please make a PR to the PoC μODNS relay list⁠!

Below is the original README.md.

⁠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⁠
  • Updating the container⁠
  • Anonymized DNS⁠
  • Prometheus metrics⁠
  • TLS (including HTTPS and DoH) forwarding⁠
  • Filtering⁠
• Join the network⁠
• Usage with Kubernetes⁠
• Customizing Unbound⁠
  • Changing the Unbound configuration file⁠
  • Serving custom DNS records on a local network⁠
  • Troubleshooting⁠
• Deleting everything⁠
• Details⁠

⁠Example installation procedures

• How to setup your own DNSCrypt server in less than 10 minutes on Scaleway⁠
• DNSCrypt server with vultr.com⁠

⁠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:

1. Update the image

docker pull jedisct1/dnscrypt-server

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

1. Stop the existing container:

docker stop dnscrypt-server
docker ps # Check that it's not running

1. Rename the existing container:

docker rename dnscrypt-server dnscrypt-server-old

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

1. Delete old container:

docker rm dnscrypt-server-old

1. 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 192.0.2.53 to your static IP.
• Edit kube/dnscrypt-srv.yml and change loadBalancerIP to your static IP.
• 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.

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