Installing dnsdist

dnsdist only runs on UNIX-like systems and there are several ways to install dnsdist. The fastest way is using packages, either from your own operating system vendor or supplied by the PowerDNS project. Building from source is also supported.

Installing from Packages

If dnsdist is available in your operating system’s software repositories, you can install it from there. However, the version of dnsdist in the repositories might be an older version that might not have a feature that was added in a later version. Or you might want to be brave and try a development snapshot from the master branch. PowerDNS provides software repositories for the most popular distributions. Visit https://repo.powerdns.com for more information and installation instructions.

Debian

For Debian and its derivatives (like Ubuntu) installing the dnsdist package should do it:

apt-get install -y dnsdist

Red Hat

For Red Hat, CentOS and its derivatives, dnsdist is available in EPEL:

yum install -y epel-release
yum install -y dnsdist

FreeBSD

dnsdist is also available in FreeBSD ports.

Installing from Source

In order to compile dnsdist, a modern compiler with C++ 2017 support, a Python 3 interpreter with the YAML module, and either GNU make or meson with ninja are required. dnsdist depends on the following libraries:

Since 2.0.0, the optional yaml configuration requires a Rust development environment, including rustc and cargo.

Should dnsdist be run on a system with systemd, it is highly recommended to have the systemd header files (libsystemd-dev on Debian and systemd-devel on CentOS) installed to have dnsdist support systemd-notify.

From tarball

Release tarballs are available from the downloads site, snapshot and pre-release tarballs can be found as well.

The release tarballs have detached PGP signatures, signed by one of these PGP keys:

There is a PGP keyblock with these keys available on https://dnsdist.org/_static/dnsdist-keyblock.asc.

Older (1.0.x) releases can also be signed with one of the following keys:

To compile from tarball:

  • Untar the tarball and cd into the source directory
  • Run ./configure
  • Run make or gmake (on BSD)

From git

To compile from git, these additional dependencies are required:

dnsdist source code lives in the PowerDNS git repository but is independent of PowerDNS.

git clone https://github.com/PowerDNS/pdns.git
cd pdns/pdns/dnsdistdist
autoreconf -i
./configure
make

Using meson

dnsdist can also be compiled with meson and ninja. For example:

meson setup build
meson compile -C build

OS Specific Instructions

None, really.

Build options

Our configure script and meson_options.txt counterpart provides a fair number of options with regard to which features should be enabled, as well as which libraries should be used. Run ./configure --help or meson configure for the list of supported options.

In addition to these options, more features can be disabled at compile-time by defining the following symbols:

  • DISABLE_BUILTIN_HTML removes the built-in web pages
  • DISABLE_CARBON for carbon support
  • DISABLE_COMPLETION for completion support in the console
  • DISABLE_DELAY_PIPE removes the ability to delay UDP responses
  • DISABLE_DEPRECATED_DYNBLOCK for legacy dynamic blocks not using the new DynBlockRulesGroup interface
  • DISABLE_DYNBLOCKS disables the new dynamic block interface
  • DISABLE_ECS_ACTIONS to disable actions altering EDNS Client Subnet
  • DISABLE_FALSE_SHARING_PADDING to disable the padding of atomic counters, which is inserted to prevent false sharing but increases the memory use significantly
  • DISABLE_HASHED_CREDENTIALS to disable password-hashing support
  • DISABLE_LUA_WEB_HANDLERS for custom Lua web handlers support
  • DISABLE_OCSP_STAPLING for OCSP stapling
  • DISABLE_OPENSSL_ERROR_STRINGS to disable the loading of OpenSSL’s error strings, reducing the memory use at the cost of human-readable error messages
  • DISABLE_NPN for Next Protocol Negotiation, superseded by ALPN
  • DISABLE_PROMETHEUS for prometheus
  • DISABLE_PROTOBUF for protocol-buffer support, including dnstap and Open Telemetry Tracing
  • DISABLE_RECVMMSG for recvmmsg support
  • DISABLE_RULES_ALTERING_QUERIES to remove rules altering the content of queries
  • DISABLE_SECPOLL for security polling
  • DISABLE_WEB_CACHE_MANAGEMENT to disable cache management via the API
  • DISABLE_WEB_CONFIG to disable accessing the configuration via the web interface

Additionally several Lua bindings can be removed when they are not needed, as they increase the memory required during compilation and the size of the final binary:

  • DISABLE_CLIENT_STATE_BINDINGS
  • DISABLE_COMBO_ADDR_BINDINGS
  • DISABLE_DNSHEADER_BINDINGS
  • DISABLE_DNSNAME_BINDINGS
  • DISABLE_DOWNSTREAM_BINDINGS
  • DISABLE_NETMASK_BINDINGS
  • DISABLE_NON_FFI_DQ_BINDINGS
  • DISABLE_PACKETCACHE_BINDINGS
  • DISABLE_POLICIES_BINDINGS
  • DISABLE_QPS_LIMITER_BINDINGS
  • DISABLE_SUFFIX_MATCH_BINDINGS
  • DISABLE_TOP_N_BINDINGS

Finally a build flag can be used to make use a single thread to handle all incoming UDP queries from clients, no matter how many addLocal() directives are present in the configuration. It also moves the task of accepting incoming TCP connections to the TCP workers themselves, removing the TCP acceptor threads. This option is destined to resource-constrained environments where dnsdist needs to listen on several addresses, over several interfaces, and one thread is enough to handle the traffic and therefore the overhead of using multiples threads for that task does not make sense. This option can be enabled by setting USE_SINGLE_ACCEPTOR_THREAD.