Running and Configuring dnsdist¶
dnsdist is meant to run as a daemon. As such, distribution native packages know how to stop/start themselves using operating system services.
It is configured with a configuration file called dnsdist.conf
The default path to this file is determined by the SYSCONFDIR variable during compilation.
Most likely this path is /etc/dnsdist, /etc or /usr/local/etc/, dnsdist will tell you on startup which file it reads.
dnsdist is designed to (re)start almost instantly. But to prevent downtime when changing configuration, the console (see Working with the dnsdist Console) can be used for live configuration.
Issuing delta() on the console will print the changes to the configuration that have been made since startup:
> delta()
-- Wed Feb 22 2017 11:31:44 CET
addLocal('127.0.0.1:5301', false)
-- Wed Feb 22 2017 12:03:48 CET
addACL('192.0.2.1/8')
-- Wed Feb 22 2017 12:05:51 CET
addACL('2001:db8::1')
These commands can be copied to the configuration file, should they need to persist after a restart.
Running as unprivileged user¶
dnsdist can drop privileges using the --uid and --gid command line switches to ensure it does not run with root privileges.
Note that dnsdist drops its privileges after parsing its startup configuration and binding its listening and initial newServer() sockets as user root.
It is highly recommended to create a system user and group for dnsdist.
Note that most packaged versions of dnsdist already create this user.
Understanding how queries are forwarded to backends¶
Initially dnsdist tried to forward a query to the backend using the same protocol than the client used to contact dnsdist: queries received over UDP were forwarded over UDP, and the same for TCP. When incoming DNSCrypt and DNS over TLS support were added, the same logic was applied, so DoT queries are forwarded over TCP. For DNS over HTTPS, UDP was selected instead for performance reason, breaking with the existing logic.
Before 1.7.0, which introduced TCP fallback, that meant that there was a potential issue with very large answers and DNS over HTTPS, requiring careful configuration of the path between dnsdist and the backend. More information about that is available in the DNS over HTTPS section.
In addition to TCP fallback for DoH, 1.7.0 introduced three new notions:
- TCP-only backends, for which queries will always forwarded over a TCP connection (see the tcpOnly parameter of
newServer())- DNS over HTTPS backends, for which queries are forwarded over a DNS over HTTPS connection (see the dohPath parameter of
newServer())- and DNS over TLS backends, for which queries are forwarded over a DNS over TLS connection (see the tls parameter of
newServer())
To sum it up:
| Incoming | Outgoing (regular) | Outgoing (TCP-only, 1.7+) | Outgoing (TLS, 1.7+) | Outgoing (DoH, 1.7+) |
|---|---|---|---|---|
| UDP | UDP | TCP | TLS | DoH |
| TCP | TCP | TCP | TLS | DoH |
| DNSCrypt UDP | UDP | TCP | TLS | DoH |
| DNSCrypt TCP | TCP | TCP | TLS | DoH |
| DoT | TCP | TCP | TLS | DoH |
| DoH | UDP | TCP | TLS | DoH |
| DoQ | TCP | TCP | TLS | DoH |
| DoH3 | TCP | TCP | TLS | DoH |