DNS over TLS upstream server Docker container

DNS over TLS upstream server connected to DNS over TLS (IPv4 and IPv6) servers with DNSSEC, DNS rebinding protection, built-in Docker healthcheck and fine grain IPs + hostnames blocking

Announcement: Total rewrite in Go: see the new features below (in case something break, use the image with tag :shell)

Features

It can be connected to one or more of the following DNS-over-TLS providers:
- Cloudflare
- Google
- Quad9
- SecureDNS
- LibreDNS
- Quadrant
- CleanBrowsing
- CIRA Canadian Shield
Split-horizon DNS (randomly pick one of the DoT providers specified for each request)
Block hostnames and IP addresses for 3 categories: malicious, surveillance and ads
Block custom hostnames and IP addresses using environment variables
One line setup
Runs without root
Small 39.4MB Docker image (uncompressed, amd64)
Click to show base components
- Alpine 3.11
- Unbound 1.10.0 ~~built from source~~ (from Alpine packages)
- Files and lists built periodically
- Go static binary built from this source
Resolves using IPv4 and IPv6 when available
Compatible with amd64, i686 (32 bit), ARM 64 bit, ARM 32 bit v7 and ppc64le 🎆
DNS rebinding protection
DNSSEC Validation

Diagrams are shown for router and client-by-client configurations in the Connect clients to it section.

Setup

Launch the container with
```
docker run -d -p 53:53/udp qmcgaw/cloudflare-dns-server
```
You can also use docker-compose.yml with:
```
docker-compose up -d
```
More environment variables are described in the environment variables section.
See the Connect clients to it section, you can also refer to the Verify DNS connection section if you want.

Environment variables

Environment variable	Default	Description
`PROVIDERS`	`cloudflare`	Comma separated list of DNS-over-TLS providers from `cloudflare`, `google`, `quad9`, `quadrant`, `cleanbrowsing`, `securedns`, `libredns` and `cira`
`VERBOSITY`	`1`	From 0 (no log) to 5 (full debug log)
`VERBOSITY_DETAILS`	`0`	From 0 to 4 (higher means more details)
`BLOCK_MALICIOUS`	`on`	`on` or `off`, to block malicious IP addresses and malicious hostnames from being resolved
`BLOCK_SURVEILLANCE`	`off`	`on` or `off`, to block surveillance IP addresses and hostnames from being resolved
`BLOCK_ADS`	`off`	`on` or `off`, to block ads IP addresses and hostnames from being resolved
`BLOCK_HOSTNAMES`		comma separated list of hostnames to block from being resolved
`BLOCK_IPS`		comma separated list of IPs to block from being returned to clients
`UNBLOCK`		comma separated list of hostnames to leave unblocked
`LISTENINGPORT`	`53`	UDP port on which the Unbound DNS server should listen to (internally)
`CACHING`	`on`	`on` or `off`. It can be useful if you have another DNS (i.e. Pihole) doing the caching as well on top of this container
`PRIVATE_ADDRESS`	All IPv4 and IPv6 CIDRs private ranges	Comma separated list of CIDRs or single IP addresses. Note that the default setting prevents DNS rebinding
`CHECK_UNBOUND`	`on`	`on` or `off`. Check resolving github.com using `127.0.0.1:53` at start
`IPV4`	`on`	`on` or `off`. Uses DNS resolution for IPV4
`IPV6`	`on`	`on` or `off`. Uses DNS resolution for IPV6

Extra configuration

You can bind mount an Unbound configuration file include.conf to be included in the Unbound server section with -v $(pwd)/include.conf:/unbound/include.conf:ro, see Unbound configuration documentation

Connect clients to it

Option 1: Router (recommended)

All machines connected to your router will use the 1.1.1.1 encrypted DNS by default

Configure your router to use the LAN IP address of your Docker host as its primary DNS address.

Access your router page, usually at http://192.168.1.1 and login with your credentials
Change the DNS settings, which are usually located in Connection settings / Advanced / DNS server
If a secondary fallback DNS address is required, use a dull ip address such as the router's IP 192.168.1.1 to force traffic to only go through this container

To ensure network clients cannot use another DNS, you might want to

Block the outbound UDP 53 port on your router firewall
Block the outbound TCP 853 port on your router firewall, except from your Docker host
If you have Deep packet inspection on your router, block DNS over HTTPs on port TCP 443

Option 2: Client, one by one

You have to configure each machine connected to your router to use the Docker host as their DNS server.

Docker containers

Connect other Docker containers by specifying the DNS to be the host IP address 127.0.0.1:

docker run -it --rm --dns=127.0.0.1 alpine

For docker-compose.yml:

version: '3'
services:
  test:
    image: alpine:3.11
    network_mode: bridge
    dns:
      - 127.0.0.1

If the containers are in the same Docker network, you can simply set the dns to the LAN IP address of the DNS container (i.e. 10.0.0.5)

Windows

Open the control panel and follow the instructions shown on the screenshots below.

Enter the IP Address of your Docker host as the Preferred DNS server (192.168.1.210 in my case) You can set the Cloudflare DNS server address 1.1.1.1 as an alternate DNS server although you might want to leave this blank so that no domain name request is in plaintext.

When closing, Windows should try to identify any potential problems. If everything is fine, you should see the following message:

Mac OS

Follow the instructions at https://support.apple.com/kb/PH25577

Linux

You probably know how to do that. Otherwise you can usually modify the first line of /etc/resolv.conf by changing the IP address of your DNS server.

Android

See this

iOS

See this

Build the image yourself

Build the latest Docker image

With git

docker build -t qmcgaw/cloudflare-dns-server https://github.com/qdm12/cloudflare-dns-server.git

With wget and unzip

wget -q "https://github.com/qdm12/cloudflare-dns-server/archive/master.zip"
unzip -q "master.zip"
cd *-master
docker build -t qmcgaw/cloudflare-dns-server .
cd .. && rm -r master.zip *-master

Build an older Docker image (you need wget and unzip)
1. Go to the commits and find which commit you want to build for
2. You can click on the clipboard next to the commit, in example you pick the commit da6dbb2ff21c0af4cee93fdb92415aee167f7fd7
3. Open a terminal and set COMMIT=da6dbb2ff21c0af4cee93fdb92415aee167f7fd7
4. Download the code for this commit and build the Docker image, either:
  - With git
```
git clone https://github.com/qdm12/cloudflare-dns-server.git temp
cd temp
git reset --hard $COMMIT
docker build -t qmcgaw/cloudflare-dns-server .
cd .. && rm -r temp
```
  - With wget and unzip
```
wget -q "https://github.com/qdm12/cloudflare-dns-server/archive/$COMMIT.zip"
unzip -q "$COMMIT.zip"
cd *-$COMMIT
docker build -t qmcgaw/cloudflare-dns-server .
cd .. && rm -r "$COMMIT.zip" *-$COMMIT
```

Firewall considerations

This container requires the following connections:

UDP 53 Inbound (only if used externally)
TCP 853 Outbound to 1.1.1.1 and 1.0.0.1

Verify DNS connection

Verify that you use Cloudflare DNS servers: https://www.dnsleaktest.com with the Standard or Extended test
Verify that DNS SEC is enabled: https://en.internet.nl/connection

Note that https://1.1.1.1/help does not work as the container is not a client to Cloudflare servers but a forwarder intermediary. Hence https://1.1.1.1/help does not detect a direct connection to them.

Development

Setup your environment
Using VSCode and Docker
1. Install Docker
  - On Windows, share a drive with Docker Desktop and have the project on that partition
  - On OSX, share your project directory with Docker Desktop
2. With Visual Studio Code, install the remote containers extension
3. In Visual Studio Code, press on F1 and select Remote-Containers: Open Folder in Container...
4. Your dev environment is ready to go!... and it's running in a container 👍
Locally

Install Go, Docker and Git; then:
```
go mod download
```
And finally install golangci-lint

Commands available:

# Build the binary
go build cmd/main.go
# Test the code
go test ./...
# Lint the code
golangci-lint run
# Build the Docker image
docker build -t qmcgaw/cloudflare-dns-server .

See Contributing for more information on how to contribute to this repository.

TO DOs

GolangCI-lint
Periodic SHUP signal to reload block lists
Build Unbound binary at image build stage
- smaller static binary
- Bundled with Go static binary on a Scratch image
Branch with Pihole bundled

juhovan/cloudflare-dns-server