commonshost/dohnut repository overview

⁠Dohnut

Use Docker to run Dohnut in a container. Multi-arch Docker container images are provided for: ARMv6, ARMv7, ARMv8, and x86-64 (Intel/AMD). Works great on Raspberry Pi and ODROID.

Docker Hub container image: commonshost/dohnut⁠

GitHub source code repository: https://github.com/commonshost/dohnut⁠

Documentation: https://help.commons.host/dohnut⁠

⁠Example

Any options before the image name commonshost/dohnut are for Docker. Any options after the image name are for Dohnut.

$ docker run [DOCKER_OPTIONS] commonshost/dohnut [DOHNUT_OPTIONS]

Run forever as a background service, listen on port 53/udp on all network interfaces, and DNS proxy queries to Commons Host DoH.

$ docker run --detach --restart unless-stopped --net=host commonshost/dohnut --listen 0.0.0.0:53 --doh commonshost --bootstrap 1.1.1.1

Test the service by performing a DNS query on the Docker host system.

$ dig @localhost example.com

; <<>> DiG 9.10.6 <<>> @127.0.0.1 example.com
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 32488
;; flags: qr rd ra ad; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;example.com.			IN	A

;; ANSWER SECTION:
example.com.		86236	IN	A	93.184.216.34

;; Query time: 13 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Tue Feb 19 15:44:53 +08 2019
;; MSG SIZE  rcvd: 56

⁠Dohnut CLI Options

Docker's docker CLI tool⁠ can automatically install, cache, and run Dohnut on the command line. See Dohnut with Docker⁠ for detailed information.

$ docker run [DOCKER_OPTIONS] commonshost/dohnut [DOHNUT_OPTIONS]

⁠Options

⁠--doh, --upstream, --proxy

Array of URLs or shortnames of upstream DNS over HTTPS resolvers.

Queries are distributed randomly over all resolvers.

Default: [ "https://commons.host" ]

⁠--listen, --local, -l

Array of IPs and ports for the local DNS server.

Default: [ "127.0.0.1:53", "[::1]:53" ]

⁠--test, --validate, --configtest

Validate the arguments without starting the server. Process exit code 1 indicates failure, or 0 for success.

Default: false

⁠--load-balance, --lb

The strategy to use with multiple DoH resolvers.

Default: performance

⁠--load-balance performance

Best performance. Always send DNS queries to the fastest DoH resolver. Continuously monitors the round-trip-time latency to each DoH resolver using HTTP/2 PING frames.

⁠--load-balance privacy

Best privacy. Uniformly distributes DNS queries across all enabled DoH resolvers.

⁠--countermeasures

One or more special tactics to protect your privacy.

Default: []

⁠--countermeasures spoof-queries

Adds plausible deniability to any legitimate DNS query. Makes it hard for a DoH resolver to profile your DNS queries.

Whenever a DNS query is proxied, a fake query is also generated. The fake query is for a domain from a public top 1 million DNS domains list, sampled by an exponential distribution. To resist detection, the fake query is sent randomly before, after, with a delay, or not at all.

⁠--countermeasures spoof-useragent

Sends a fake User-Agent HTTP header to prevent tracking. Makes it look like every DoH request is by a different browser. Randomly samples actual user agent strings from a public data source of real-world web traffic.

⁠--bootstrap

Default: []

One or more IPv4 or IPv6 addresses of DNS resolvers. These are used to perform the initial DNS lookup for the DoH URI hostname.

If this option is not specified, the operating system resolves the DoH URI hostname based on your network settings, typically provided automatically via DHCP or manually configured. This option is used to avoid a loop when Dohnut itself is the DNS resolver of the operating system.

A possible loop scenario is when Dohnut provides transparent DoH proxying as the upstream DNS server for a Pi-hole⁠ service. If the operating system running Dohnut uses the Pi-hole server as its DNS server, a lookup loop is created. To break out of the loop, set the bootstrap option to the IP address of the DNS server of your LAN router, your ISP, or a public DNS service⁠.

Notes:

• Only the DoH URI hostname is resolved via the bootstrap DNS lookup. Actual user DNS queries are never exposed.
• DoH bootstrapping is considered failsafe. Tampering during bootstrap by a DNS resolver results in a failed DoH connection. DoH uses HTTP/2 which requires a valid TLS certificate for the DoH URI hostname. No queries are exposed without a secure HTTP/2 connection.

⁠--datagram-protocol

Default: udp6

Sets the protocol to use for local listening UDP sockets when the IP address is not specified. For example if --listen is used with only a port number. Or when a socket file descriptor is provided by a service manager like systemd (Linux) or launchd (macOS).

Set to udp4 to use IPv4. Set to udp6 to use IPv6.

⁠--config

Path to JSON config file

The JSON config file options are identical to the CLI options.

⁠--version

Show version number

⁠--help

Show help

⁠Shortnames

Public resolver names mapped to a DoH URL. Based on the @commonshost/resolvers⁠ list.

• cleanbrowsing
• cloudflare
• commonshost
• google
• keoweon
• mozilla
• nekomimi
• powerdns
• quad9
• rubyfish
• securedns

⁠Examples

Only allow localhost connections. Proxy to the Commons Host DoH service.

--listen 127.0.0.1 ::1 --doh commonshost

Use a custom resolver

--doh https://localhost/my-own-resolver

Multiple DoH service can be used. Shortnames for popular services are supported.

--doh commonshost cloudflare quad9 cleanbrowsing https://example.com

Listen on all network interfaces using both IPv6 and IPv4.

--listen :: 0.0.0.0

Listen on a non-privileged port (>=1024).

--listen 8053

Listen on 127.0.0.1:53 using UDP over IPv4.

--port 53 --datagram-protocol udp4

Listen on [::1]:53 using UDP over IPv6.

--port 53 --datagram-protocol udp6

Check the syntax of the URL and IP address arguments. No connections are attempted.

--test --doh https://example.com --listen 192.168.12.34

Send queries to one of multiple DoH services at random for increased privacy.

--load-balance privacy --doh quad9 cloudflare commonshost

Send queries to the fastest DoH service by measuring ping round-trip-times.

--load-balance performance --doh quad9 cloudflare commonshost

Randomly send fake DNS queries as disinformation to deter tracking by resolvers.

--countermeasures spoof-queries

Mimic popular web browsers by including a random User-Agent header with each request. Default is no User-Agent header.

--countermeasures spoof-useragent

Bypass the operating system DNS settings to resolve the DoH service hostnames.

--bootstrap 192.168.1.1 1.1.1.1 8.8.8.8 9.9.9.9

Load options from a JSON file

--config ~/dohnut-options.json

⁠Docker CLI Options

See the Docker reference documentation⁠ for docker run.

⁠Background Service Daemon

Using the --detach or -d Docker option to run Dohnut as a background service, aka daemon.

The --restart unless-stopped Docker option automatically runs Dohnut when Docker starts (i.e. at system boot), and restart the process if it crashes.

⁠Bootstrapping

Use the --bootstrap [DNS server IP address] for the initial DNS lookup of the DoH resolver.

Dohnut resolves the DoH service's address using plaintext DNS over UDP, as per the operating system's DNS settings, unless overridden with the --bootstrap option. This lookup will fail if Dohnut itself is part of the OS' DNS chain. For example if Dohnut is configured as the upstream resolver to Pi-hole, or used directly as the operating system's DNS server via DHCP or static network configuration. In such cases, a circular DNS dependency is created which prevents Dohnut from connecting to its DoH resolver.

The bootstrap DNS service is only used for the initial connection to the DoH resolver. All subsequent queries are encrypted and sent directly to the DoH resolver.

Example error: Without the bootstrap option, Dohnut is unable to resolve the domain commons.host which is set as its DoH resolver.

Worker 1: session error getaddrinfo EAI_AGAIN commons.host commons.host:443

Solution: Set the --bootstrap option to the IP address of a public DNS service, for example 1.1.1.1 (Cloudflare) or 8.8.8.8 (Google).

$ dohnut [...] --bootstrap 1.1.1.1

⁠Networking

Dohnut run inside a container so Docker needs to map its listening ports to the host's network.

The simplest method is to expose the host network directly to the container.

$ docker run --detach --restart unless-stopped --net=host commonshost/dohnut --listen 0.0.0.0:53 --doh commonshost --bootstrap 1.1.1.1

Service using IPv4:

$ docker run --detach --restart unless-stopped --publish 0.0.0.0:53:53/udp commonshost/dohnut --listen 0.0.0.0:53 --doh commonshost --bootstrap 1.1.1.1

Service using IPv6:

$ docker run --detach --restart unless-stopped --publish [::]:53:53/udp commonshost/dohnut --listen [::]:53 --doh commonshost --bootstrap 1.1.1.1

Please ensure that Dohnut is only exposed to a private LAN or localhost. Running a public, open DNS resolver exposed to public Internet traffic is strongly discouraged. Plaintext DNS/UDP is a potential source of traffic amplification in DDoS attacks⁠.

Expose Dohnut on 127.0.0.1 or 0.0.0.0 for localhost-only or all network interfaces respectively.

DNS uses port 53 by default but one use case of re-mapping to another port is when Dohnut is used as a local proxy for another resolver like resolved or Pi-hole⁠. For example to run Dohnut on port 53000 and only be accessible from the local host:

$ docker run --detach --restart unless-stopped --publish 127.0.0.1:53000:53/udp commonshost/dohnut --listen 0.0.0.0:53 --doh commonshost --bootstrap 1.1.1.1

⁠Environment Variables

All command line interface options can also be specified as environment variables.

Environment variable names must be uppercase and begin with the DOHNUT_ prefix. Hyphens are replaced with _ underscores.

Environment variables with multiple values must be space-separated. In Bash the values will need to be quoted, but .env configuration files (e.g. Docker Compose, systemd) do not require quotes.