PowerDNS: one repository, three DNS daemons, one real build guide

One tree, three DNS daemons that do not share a build recipe

The clone is one repository but three programs. It contains the sources for the PowerDNS Recursor, the PowerDNS Authoritative Server, and dnsdist, which the file calls a DNS loadbalancer. All three build from this checkout, and each is also released on its own as a .tar.bz2, a .deb, or an .rpm package, so compiling from git is only one of the routes to a running daemon.

What the top level file gives you is a build guide for the Authoritative Server alone. For the other two it points elsewhere: the Recursor instructions live in README.md under pdns/recursordist/, and the dnsdist instructions live in README.md under pdns/dnsdistdist/. That asymmetry is the first thing to notice when something breaks. A failure in the Recursor path has no troubleshooting text at the root of the repository, and the root file does not even restate the dependency list for it. Anyone planning to run all three from one clone will be reading three different sets of instructions.

pdns-builder wraps the release build in Docker

Release builds are not done by hand here. The project ships pdns-builder, and the file states that it uses a docker-based build process. You start it from the root of the checkout, submodules included:

git submodule init
git submodule update
./builder/build.sh

Running it brings up a USAGE page that explains how to build the different releases, which means the exact list of release targets is not written down anywhere in the text you start from. The tree supports that arrangement: builder/ and builder-support/ sit next to BUILDING-PACKAGES.md, and there is one Dockerfile per product (Dockerfile-auth, Dockerfile-recursor, Dockerfile-dnsdist) plus Dockerfile-cifuzz, with a fuzzing/ directory beside them. The cost is a working Docker daemon and a submodule fetch. The payoff is a tarball built the same way the released .tar.bz2 packages are built, which matters if you need to reproduce a shipped artifact rather than invent your own flags.

The Authoritative binary carries only the modules you name

The Authoritative Server depends on Boost, OpenSSL and Lua, and needs a compiler with C++-2017 support. On Debian the file lists one package set, and a second one for when you build from git rather than from a release:

apt install g++ libboost-all-dev libtool make pkg-config default-libmysqlclient-dev libssl-dev libluajit-5.1-dev python3-venv

apt install autoconf automake ragel bison flex

autoreconf -vi

What ends up inside the binary is decided by --with-modules. Leave the option out and bind and gmysql are built in by default, while pipe-backend is compiled for runtime loading. Pass an empty string and you get a very clean version with no modules built in at all:

./configure --with-modules="" --disable-lua-records
make
# make install

Name several modules and you get those, though gpgsql in the example below also needs the PostgreSQL development headers installed:

./configure --with-modules="bind gmysql gpgsql"

A wrong module set is the quiet failure here, because it is decided at compile time and nothing in these instructions tells you how to inspect the result. Record the exact --with-modules string for every machine you build on, and check it before you go looking at your zone data.

macOS needs an OpenSSL path and FreeBSD needs gmake

Two platforms need extra instructions, and both are about the toolchain rather than about PowerDNS itself.

On macOS the Authoritative Server is available through Homebrew:

brew install pdns

If you build it yourself, the dependencies come from Homebrew too, and you have to tell configure where to find OpenSSL:

brew install boost lua pkg-config ragel openssl
./configure --with-modules="" PKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig
make -j4

Database backends are added the same way: brew install postgresql with --with-modules="gpgsql", or brew install mariadb with --with-modules="gmysql". Note that the pkgconfig argument is fixed to /usr/local/opt/openssl/lib/pkgconfig, and no alternative path is offered.

On FreeBSD the note is blunter. You need to compile using gmake, because regular make only appears to work but does not in fact. The clang compiler from the package manager does not expose all of the C++17 features needed under the default std=gnuc++14, so the standard has to be forced:

export CXXFLAGS=-std=c++17

Linux gets one line in the whole file: None really.

A C++ ABI mismatch stops the build before PowerDNS code runs

One failure mode gets its own paragraph because it is not a PowerDNS problem. If you run into C++11-related symbol trouble, the file tells you to pass CPPFLAGS=-D_GLIBCXX_USE_CXX11_ABI=0, or 1, to ./configure, so that you stay compatible with the installed dependencies. No error output is quoted, no detection command is given, and no value is named as the correct one. You get two candidates, and which one links depends on how Boost and OpenSSL were compiled on that machine.

The Ubuntu package list goes further than the Debian one. It adds libcurl4-openssl-dev, libyaml-cpp-dev, libtolua-dev, lua5.3, gawk and libsqlite3-dev, and then adds libsodium-dev for DNSSEC ed25519 (algorithm 15) support with --with-libsodium, default-libmysqlclient-dev if you use the gmysql backend, and libpq-dev if you use gpgsql. Every one of those optional pieces is another library whose build flags your configure run has to agree with, so a build that fails late at link time may trace back to a dependency installed by apt rather than to anything in pdns/.

docker-compose.yml is a source build fixture, not a deployment

The compose file at the root builds images from the checkout instead of pulling them, so a first run compiles all three daemons before anything answers:

---
version: '2.0'
services:
  recursor:
    build:
      context: .
      dockerfile: Dockerfile-recursor
    environment:
      - PDNS_RECURSOR_API_KEY
    ports:
      - "2053:53"
      - "2053:53/udp"
      - "8082:8082"

  dnsdist:
    build:
      context: .
      dockerfile: Dockerfile-dnsdist
    environment:
      - DNSDIST_API_KEY
    links:
      - recursor
      - auth
    ports:
      - "3053:53"
      - "3053:53/udp"
      - "5199:5199"
      - "8083:8083"

  auth:
    build:
      context: .
      dockerfile: Dockerfile-auth
    environment:
      - PDNS_AUTH_API_KEY
    ports:
      - "1053:53"
      - "1053:53/udp"
      - "8081:8081"

The port layout keeps 53 free on the host: auth on 1053, recursor on 2053, dnsdist on 3053, each over TCP and UDP, with 8081, 8082 and 8083 for the web interfaces and 5199 for dnsdist alone. The three API keys arrive as environment variables, PDNS_AUTH_API_KEY, PDNS_RECURSOR_API_KEY and DNSDIST_API_KEY, and dnsdist declares links to recursor and auth, which orders startup without configuring any backend.

What the file cannot give you is durability: no volumes for zone or database state, no key generation for those three variables, no restart policy. Read it as a smoke test for your toolchain.

The file admits it can lag behind, and nothing is released here

The README says so about itself: This file may lag behind at times, and it redirects you to three places for anything current. The authoritative changelog at https://doc.powerdns.com/authoritative/changelog/, the compiling appendix for build questions, and the issue tracker for bugs, with a request to check whether the issue is already reported there first. Image documentation has its own file, Docker-README.md, and the same text is mirrored from GitHub to dockerhub.

The repository also has no GitHub releases, so there is no release to pin from these pages. A version number has to come from the .tar.bz2, .deb or .rpm package you installed, or from the changelog. The commands in the guide are written against a checkout of the default branch, which means the flags you copy can sit behind the code you actually run.

The documentation itself is buildable locally. The HTML docs come from ReStructured Text files in docs/ compiled by Sphinx, which is written in Python:

cd docs
make html-docs

The output lands in a directory called html-docs. That is the shortest way to check a flag against the current manual instead of against a file that warns it may be behind.

Everything documented here stops before the daemon runs

Read end to end, the file is a build guide and nothing more. It never names a configuration file for the Authoritative Server, never shows a zone file, never explains how DNSSEC keys are generated or stored, and does not document upgrading a running server or rolling one back. Where backends are concerned it only says that a list of available modules exists at https://doc.powerdns.com/authoritative/backends/index.html.

The consequence is concrete. You can compile pdns, install it, and still have no idea how to make it answer a query, because every runtime step lives on the documentation site rather than in the README. If your plan is to compare PowerDNS against another resolver or authoritative server, budget for that separate reading before you commit a weekend to it.

The tree also holds files the text never mentions: DEVELOPMENT.md, CODING_GUIDELINES.md, CODE_COVERAGE.md, CONTRIBUTING.md, DCO, SECURITY.md and AUTHORS. Contributor process, security reporting and coding rules are all in the repository, just not in the file most readers stop at. A meson/ directory, meson.build and meson_options.txt sit next to configure.ac, which tells you a second build system exists, but the instructions here only exercise the autotools path.

Editorial conclusion

Pick PowerDNS when you want DNS software you compile yourself with the backend modules you chose, and you are ready to read doc.powerdns.com for everything after install, because no configuration file, zone format, key handling or upgrade path appears in the README. Do not expect a packaged turnkey daemon here, since nothing is released from these pages. Before blaming your own machine, verify that your compiler, Boost and OpenSSL agree on the C++ ABI flag.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. PowerDNS/pdns on GitHub
4. Project website
5. README