tschaffter/getdns-stubby repository overview

⁠Docker image for Stubby

⁠Introduction

Stubby⁠ is an application that acts as a local DNS Privacy stub resolver (using DNS-over-TLS). Stubby encrypts DNS queries sent from a client machine (desktop or laptop) to a DNS Privacy resolver increasing end user privacy.

This project builds Stubby from its source using the instructions available in the GitHub repository getdnsapi/getdns⁠.

Stubby provides DNS Privacy by:

• Using a default configuration which provides Strict Privacy and uses a subset of the available DNS Privacy servers⁠ that support DNS-over-TLS. These servers can be replaced by the servers of a paid alternative, for example those provided by NextDNS⁠.
• Distributing queries across all the servers specified so that the full picture of your queries is not captured by a single DNS provider (round_robin_upstreams: 1).
• Enabling Domain Name System Security Extension (DNSSEC) validation. Cloudflare provides an intuitive description of how DNSSEC works⁠.

⁠Contents

• Specification⁠
• Requirements⁠
• Usage⁠
  • Quickstart⁠
  • Configuration⁠
  • Deploying using Docker⁠
• Resolving domain names⁠
• Versioning⁠
  • GitHub tags⁠
  • Docker tags⁠
• Acknowledgments⁠
• License⁠

⁠Specification

• Project version: 1.2.1
• Getdns version: 1.7.0
• Docker image: tschaffter/getdns-stubby⁠

⁠Requirements

• [Docker Engine] >=19.03.0

⁠Usage

⁠Quickstart

1. Start Stubby using Docker: docker compose up -d

2. Resolve the IP address of github.com using dig⁠ and Stubby:

   dig @localhost +noall +answer +stats github.com
   github.com.             17      IN      A       140.82.121.4
   ;; Query time: 156 msec
   ;; SERVER: 127.0.0.1#53(127.0.0.1)
   ;; WHEN: Mon Mar 29 07:55:58 PDT 2021
   ;; MSG SIZE  rcvd: 413
   

   Copy

3. Stop Stubby: docker stop stubby

⁠Configuration

The default configuration file of Stubby is stubby.yml.example⁠.

By default, Stubby listen to the loopback interface of the host it is running on, which can not be reached when running Stubby in a container. When starting Stubby using Docker as described below, the configuration file stubby.yml⁠ is used where the value of the option listen_addresses has been updated to enable Stubby to be reached from your host or from another container as done in tschaffter/dnsmasq-stubby⁠.

# Listen to all IPv4 and IPv6 addresses (within the container).
listen_addresses:
  - 0.0.0.0
  - 0:0:0:0:0:0:0:0

⁠Deploying using Docker

Start the Stubby server. Add the option -d or --detach to run in the background.

docker-compose up

To stop the server, enter Ctrl+C followed by docker compose down. If running in detached mode, you will only need to enter docker compose down.

⁠Resolving domain names

Dig⁠ is a command line utility that performs DNS lookup by querying name servers and displaying the result to you. After starting Stubby, run the command below to resolve the IP address of github.com.

dig @localhost +noall +answer +stats github.com
github.com.             17      IN      A       140.82.121.4
;; Query time: 156 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Mon Mar 29 07:55:58 PDT 2021
;; MSG SIZE  rcvd: 413

The response includes the following information:

• The IP address of github.com is 140.82.121.4 (may change over time).
• The response is returned by the server is 127.0.0.1#53 (Stubby).

⁠Versioning

⁠GitHub tags

This repository uses semantic versioning⁠ to track the releases of this project. This repository uses "non-moving" GitHub tags, that is, a tag will always point to the same git commit identifier once it has been created.

⁠Docker tags

The artifact published by this repository is a Docker image. The versions of the image are aligned with the versions of getdns, not the versions of Stubby or the GitHub tags of this repository.

The table below describes the image tags available.

⁠Acknowledgments

The Dockerfile is adapted from the one available in the repository yegle/stubby-docker⁠.

⁠License

Apache License 2.0⁠