DoTH-DNS

Your server doth DNS the safe way if you use DoTH-DNS.

Utilizes the power of the DNS sinkhole pi-hole and the recursive DNS resolver unbound to create a DNS server under your own authority with the added benefit to be able to also use encrypted Transport Protocols.

By default DNS traffic is send unencrypted to port 53 also called Do53 (DNS over port 53). DNS over HTTPS (DoH) and DNS over TLS (DoT) are both encrypted alternative Transport Protocols which are both supported by the DoTH-DNS stack, hence the name.

Disclaimer

This project is not actively maintained. Nonthenless are issues or PRs welcome.

The versioning and development of this project is rather wild. In its core it was always the same: bringing docker containers up to run the DoTH-DNS stack, but the way this is achieved changes over the course of different versions. You may see the Changelog for more information. This means also that the handling of the stack may change in future versions.

Use at own risk see the License file for more details.

WARNING: This project was created for use in a local network. If you want to use it on a VPS or in an cloud environment be sure to properly secure your environment and know what you do.

Usage

Prerequisites and what to know before starting

Operating system

In the following section I explain how to run the stack on ubuntu. If you use another linux distro the commands shown may differ.

I don't own a Mac and don't use Windows for such things, so I can not help you there. You will have to modify this guide to fit your system yourself. Sorry.

Processor architecture

I run this stack on a x86 maschine. If you want to run this on an ARM maschine, e.g. RaspberryPi you need to make some adjustments.

WARNING: I did not test these changes in practice.

1. pihole and traefik should work fine as is.
2. The doh_server image needs to be build on the host anyways.
3. The unbound image needs to change to the mvance/unbound-rpi image by changing it in the docker-compose.yaml file.

SSL Certificates

Because of the TLS encryption we need certificates accordingly.

traefik proxy supports different setups for certificates:

1. By default traefik creates a self signed wildcard certificate.

   This is ok for testing and works in the sense that a TLS secured connection can be established, but your browser will complain that the connection is not secure. I am not sure but this will most certainly block when trying to establish a DoH or DoT connection.

2. Self configured certificates - self-signed and/or official ones.

   Here you need to pass the certificate files into the docker container yourself and also configure a certificate store for traefik by updating the docker-compose.yaml file.

   See traefik's documention for more information (link in the resources section).

3. Automatic generation of certificates with letsencrypt and the ACME protocol.

   letsencrypt is a nonprofit Certificate Authority (CA) and provides free and automated certificates. Only caveat is that you need a real domain and a domain registrar that is supported by the lego library which traefik uses, but there are a lot of supported ones.

   See traefik's documention for more information (link in the resources section).

   Because the certification process is easily automated I use this approach with my domain from name.com. This approach also works when the stack, like mine, only runs in your LAN and is not visible to the internet, thanks to the DNS-01 challenge.

Additional Software

1. To get the source we use git. Alternatively you could download the zip archive and extract it.

2. To run the stack we need docker and docker-compose.

   You need root permissions to work with docker. To remove the need of using sudo, you can add the docker group to your user. After adding the group you need to log out and in again.

   sudo usermod -aG docker USERNAME

3. To create a user/password combo for the .htpasswd file for password protection of the traefik dashboard we need the htpasswd utility from the apache2-utils package. Alternatively you can use e.g. this online tool.

4. To edit files I use the nano text editor.

To install all run this:

sudo apt install git docker.io docker-compose apache2-utils nano

Configuration

.env file

The run configuration is done inside the .env file in the root directory of this repository.

• HOST_IP - (Mandatory)

  This is the IPv4 address of the docker host system and is needed for pihole.

• DOMAIN - (Mandatory)

  This is the domain you want to use for your DNS server.

• HOSTNAME - (Optional; defaults to dns_server)

  This sets the hostname of the containers.

• PIHOLE_WEBPASSWORD - (Optional; unset by default -> no password)

  The password you want to use for the pihole dashboard. Can be changed again later.

• TIMEZONE - (Optional; defaults to Europe/Berlin)

  TZ database name of your timezone which gets uses for timestamps etc.

  You can see a list of thouse names at link.

• ACME_EMAIL - (Mandatory)

  Email address used for registration at letsencrypt (no account needed).

• ACME_CASERVER - (Optional; defaults to https://acme-v02.api.letsencrypt.org/directory)

  This is the server to get the certificates from. By default the production server is used. When you test things you should set the staging server to avoid the weekly rate limiting.

  Staging server: https://acme-staging-v02.api.letsencrypt.org/directory

• ACME_DNSCHALLENGE_PROVIDER - (Optional; defaults to namedotcom)

  The domain registrar or the DNS provider for your domain, if they are not the same.

• NAMECOM_USERNAME - (Optional; unset by default)

  This is you name.com username.

• NAMECOM_API_TOKEN - (Optional; unset by default)

  This is your name.com API Token, which you can create at link.

DoH Server

If you need to modify the DoH server config, what you most certainly not, you can find the config file here: doh-docker/data/doh-server.conf.

pihole

The pihole configuration files and directory you can find here: pihole-docker/data.

traefik

If you need to create a traefik config file put it here: traefik-docker/data.

unbound

If you need to modify the unbound boot script, what you most certainly not, you can find it here: unbound-docker/scripts/unbound.sh.

unbound's config files can be found here: unbound-docker/data/unbound.conf.d. Here you most certainly only want to change things in the default.conf file or add another custom file.

Step by Step Setup

All following steps are run from the command line:

1. Git clone this repository via HTTPS:

   git clone https://github.com/Cielquan/DoTH-DNS

2. Open the directory:

   cd DoTH-DNS

3. Build the doh_server docker image:

   docker build --tag cielquan/doh_server:latest doh-docker

4. Create .htpasswd file for password protection of the traefik dashboard

   • via the htpasswd utility:

     htpasswd -c traefik-docker/data/.htpasswd USERNAME

   • or when you created the user/password combi online, create the file and copy it there:

     nano traefik-docker/data/.htpasswd

   • If you do not want or need password protection you need to remove TraefikAuth from the traefik.http.routers.Traefik.middlewares label for the traefik container in the docker-compose.yaml file.

5. Create a .env file and edit it with your configuration (see configuration section):

   nano .env

6. Start all containers:

   docker-compose up -d

Logs

In unbound-docker/data/var/log you can find unbounds log file, which will be recreated each boot.

All other container do not log to a file but stdout/stderr. You can see them by running

docker-compose logs CONTAINERNAME

How to use the DNS server stack

Do53

To normally use your new DNS server simply provide your set HOST_IP as your DNS server e.g. in your DHCP server.

DoH

To use DoH you need to set https://doh.DOMAIN/dns-query URL in the corresponding DoH settings of your used software.

DoT

To use DoT you either need to set https://dot.DOMAIN URL or HOST_IP with port 853 in the DoT settings of your used software.

pihole

At the URL https://pihole.DOMAIN you can find the pihole dashboard where you can set your blocklists, etc.

traefik

At the URL https://traefik.DOMAIN you can find the traefik dashboard which has only informational use.

Updates

When there are new version of one or more of the used containers simply replace the container. Because the configuration of all containers is mapped to directories and files outside, they are preserved.

1. Stop the container

   docker-compose stop CONTAINERNAME

2. Remove the container

   docker-compose rm CONTAINERNAME

3. Pull the new image

   docker-compose pull CONTAINERNAME

4. Start the container

   docker-compose up -d CONTAINERNAME

Resources / Help

Here are some external links for further information that may help if you have issues.
If the documention does not help, open an issue and I will try to help.

• Pi-hole documentation link
• Pi-hole docker image repository link
• Unbound documentation link
• Unbound docker image for x86 (normal pc) link
• Unbound docker image for ARM (RaspberryPi) link
• traefik proxy documentation link
• traefik proxy letsencrypt documentation link
• dns-over-https repository link
• dns-over-https docker image repository link
• Docker documentation link
• Similar project without DoH and DoT link
• Pi-hole blog post about slow loading sides and blocking QUIC protocol link
• Pi-hole guide about pi-hole + unbound link
• Two Blog post realizing a similar construct link 1 link 2

FAQ

Where does the name come from

Firstly the name DoTH-DNS is a word construct resulting from the ability to use DoT and DoH for DNS queries.

Secondly doth is an archaic word for third person singular present tense of do, which matches the name perfectly well, because it does DNS (see slogan at top).

Where is the python CLI app?

The python CLI app from v7 lifes on the python-cli-pihole4 branch and is also still available from PyPI.

Because as of now I find the CLI app solution over-engineered so I switched back to a simpler docker-compose setup.

WARNING: The app was build for pihole v4 which is outdated and I am unsure if it works with pihole v5. Also traefik proxy will release its next major version soon, which is incompatible with the config used in the app.

Known issues

• There is an issue with alpine linux 1.13 which breaks the build of the doh_server container on presumably ARM hardware (e.g. RaspberryPi).
  See issue #8.

Acknowledgements

Thanks to the creators, maintainers and developers of the software and linked resources used in this project.

Special thanks to:

• the dns-over-https project and its docker version as a base for my Dockerfile.
• the docker-pihole-unbound project for the inspiration.
• this blog post and this blog post for being the first foundation of this project.