🐑 Commons Host




Table of Contents


Try out Dohnut using the npx tool that is included with Node.js. This downloads and installs Dohnut to a temporary directory, runs the dohnut command, and then cleans up all files without a trace once the process terminates. It always downloads the latest version so this can also be used to auto-update Dohnut as part of long-running service processes.

$ npx dohnut [OPTIONS]

Installing Dohnut as a global command is a good way to pin a specific version and minimise startup time.

$ npm install --global dohnut
$ dohnut [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]


--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: [ "", "[::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.


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.


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.



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.


Default: Current working directory

Specifies the path to a directory where data is saved. Speeds up process restarts.

Only used by the spoof-queries feature. By saving a local copy of the popular domain names list, this avoids repeated download and processing.


Path to JSON config file

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


Show version number


Show help


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


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

--listen ::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 ::

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

--listen 8053

Listen on 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

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.


Load options from a JSON file

--config ~/dohnut-options.json

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.

Example Option Environment Variable
Single value --load-balance performance DOHNUT_LOAD_BALANCE=performance
Multiple values --bootstrap DOHNUT_BOOTSTRAP=""