buckaroogeek/doh-client repository overview

⁠DNS-Over-HTTPS (DOH) Client

### IMPORTANT NOTE ###

I am no longer maintaining this DOH Client image. I recommend checking out https://hub.docker.com/r/m13253/dns-over-https-client⁠.

⁠Goal

Use DNS-Over-HTTPS (DOH) for DNS queries from my home network.

⁠Update Notes

28 Jan 2025 - Tag 2.2.20. Upstream v2.3.8 release. Primarily dependency updates.

10 Nov 2024 - Tag 2.2.19. Upstream v2.3.7 release. Primarily dependency update.

8 Feb 2024 - Tag 2.2.18. Upstream v2.3.5 tag. Primarily dependency update.

5 Dec 2023 - Tag 2.2.17. Current updates from upstream (dependencies updates). Update golang to address CVE-2023-39326.

11 Nov 2023 - Updated to v. 2.3.4 upstream. Dependencies have been updated.

29 Jan 2023 - Updated to v. 2.3.3 upstream. The primary fix in v.2.3.3 resolves a problem that affected the doh-server. Dependencies have also been updated.

17 Aug 2022 - updated to current upstream. Upstream has updated go dependencies. See https://github.com/m13253/dns-over-https/pull/131⁠.

4 June 2022 - updated to current upstream head (doh-client v2.3.2. Update to go 1.18 and go dependencies. See https://github.com/m13253/dns-over-https/pull/128⁠ for details.

27 Sept 2021 - updated to current upstream head (doh-client v2.3.1). Still experimenting with multiarch build (linux/amd64, linux/arm64) using buildah.

8 Mar 2021 - Incorporate DOH client v2.2.5 from upstream. Important Note - I dropped the latest tag.

2 August 2020 - 2.2.9/latest. Updated to upstream DNS-Over-HTTPS version 2.2.3. Star Brilliant has incorporated a number of contributions. Please note this is a multiarch build (amd64 and arm64) and still considered experimental on my part. I do use the current version on my Synology docker host (intel cpu so it uses the amd64 arch).

27 July 2020 - it would help if the issue tracker was enabled on the github repository. Done.

26 July 2020 - 2.2.8/latest. IMPORTANT NOTE: With 2.2.8/latest I am trying a multiarch build for both amd64 and arm64 architectures. There are some minor updates to the golang/alpine base image but no DOH client code changes. If 2.2.8 fails or the arm64 images does not work for you please let me know as an issue in the github repository. I do not have arm64 hardware to test with and have not yet tried to run an arm64 vm to test. Please keep that in mind. The arm64 build is experimental at this time.

14 June 2020 - 2.2.7/latest. Updated to current golang/alpine image. DOH client code unchanged.

2 June 2020 - 2.2.6/latest. Updated to current golang/alpine image. Updated versions of component go libraries. DOH client code unchanged.

18 May 2020 - 2.2.5/latest. Updated to current golang/alpine image. No other changes.

⁠Solution

My home network currently uses a Pi-Hole⁠ server for DNS. The Pi-Hole, in turn, sends queries to an internet hosted DNS provider such as Google (8.8 .8.8). Addng a DOH client as the DNS provider to the Pi-Hole will encrypt (almost) all DNS traffic from the home network with https.

Since the Pi-Hole already runs as a docker container, as well as the network administrative application (Ubiquiti), it makes sense to also deploy the DOH client via docker.

As the home network uses a private subnet, the Pi-Hole provides DNS via the normal, unecrypted traffic on port 53. If my network is compromised, my problems are much larger than unencrypted DNS traffic! I therefore do not plan to deploy a DOH server on the home network. The DOH client takes on the task of encrypting DNS traffic from the home network to upstream DNS providers.

⁠Usage and Technical Notes

Star Brilliant ([email protected]⁠) has published a go language based DOH (dns over https) client and server at GitHub (https://github.com/m13253/dns-over-https⁠). My fork of Star Brilliant repository is used for this Docker repository. I thank Star Brilliant and colleagues for their work creating and publishing this code base.

The client dockerfile (Dockerfile.client) is used unchanged from the attached github repository. The only change in the dockerfile from the original codebase is to explic itly expose udp and tcp for port 53. I also include a docker-compose.yaml file that is used to deploy this image to a Synology NAS on my home network.

A few notes about this image. As noted above, the Dockerfile.client dockerfile is used unchanged except for exposing 53/udp. The image includes the default doh-client.con f file at /doh-client.conf. The configuration file is modified during the build by the two (2) sed scripts in the dockerfile. The sed scripts configure the client to listen to all connections on ports 53 and 5380. Port 53 used to is listen and respond to DNS requests from the home network (specifically the Pi Hole server in my case).

The default configuration file can be substituted by another instance of the configuration file when the container is created via either an argument to the docker run command or via the command option in a docker-compose.yaml file. With both alternatives the location of the new configuration file is passed to the new container when it starts. See the command and volumes lines in the docker-compose.yaml file (https://github.com/buckaroogeek/dns-over-https/blob/master/docker-compose.yaml⁠).

This particular docker-compose.yaml file uses a docker macvlan to provide an IP to the container. The same macvlan is used for other containers on the docker host including the Pi Hole server, a Unifi network controller, and a private docker repository for development. I have removed those service definitions from this docker-compose.yaml file. Using a docker macvlan on any linux docker host creates a complication in that there is no network path between the host IP and the docker macvlan IP space unless additional steps are taken. See the excellent overview of the problem at https://blog.oddbit.com/post/2018-03-12-using-docker-macvlan-networks/⁠. I have a small script to correct this complication on the docker host. Other network configurations are possible but beyond the scope of this readme.

The github project with the complete docker-compose.yaml file that includes a pihole container, doh client container, and a unifi network controller can be found at https://github.com/buckaroogeek/unifi-pihole-doh-docker⁠.

⁠Configuration File

The doh-client.conf configuration file can be used to manage:

• the IP range allowed to submit DNS queries - by default this is 0.0.0.0 for the docker version;
• the list of up stream DOH servers queried for a response;
• the method of selecting an upstream server if more than one is available (e.g. random, round robin and so on);
• domain names that bypass the DOH process and are resolved using standard DNS queries (such as pool.ntp.org).
• bootstrap DNS provider - the DNS provider used to resolve the IP addresses of DOH servers and the bypass domain names;
• additional settings - all are well commented.

⁠Options

⁠Examples

Changing the configuration file with docker run (untested; the :Z postfix on the volume is needed for selinux, otherwise drop):

docker run -itd --name doh-client -p 8053:53 -v /hostpath:/etc/doh:Z buckaroogeek/doh-client -conf /etc/doh/doh-client.conf    

Incomplete fragment from a docker-compose.yaml file that sets the location for the configuration file:

services:
  doh-client:     #DOH Client for local network
    container_name: doh-client
    image: buckaroogeek/doh-client:2.2.13
    hostname: dohclient
    domainname: lan
    networks:
      macvlan1:
        ipv4_address: 192.168.110.203
    command: ["-conf=/etc/doh/doh-client.conf"]  # override default config
    volumes:
      - /volume1/docker/dohclient:/etc/doh  #location for config on docker host
    ports:
      - 53/tcp
      - 53/udp
      - 5380/tcp
    restart: unless-stopped
 

⁠Source Code Notes

The buckaroogeek/dns-over-https github repository is a clone of the upstream repository maintained by Star Brilliant. I have added a directory that contains a supplemental script file I use to build the OCI container image. I use the shell file (./notes-buildah/multi) to implement the multi-arch images and necessary manifests using buildah. Buildah requires authentication with docker Hub before deploying the image to hub. The authentication commands are not in the notes or shell scripts. The steps in the multi shell file have recently been updated to incorporate new buildah features (specifically --platform to list the archs using go arch definitions; see man buildah).

⁠Credit

Original source code: https://github.com/m13253/dns-over-https⁠