PowerDNS/pdns: Three DNS Servers in One Repository

The problem PowerDNS/pdns solves, and for whom

The repository is not one DNS server. It is three programs that share a C++ codebase: the Authoritative Server, which answers queries for zones you own; the Recursor, which resolves names on behalf of clients; and dnsdist, described in the README as a powerful DNS loadbalancer. A team running a public zone and a caching resolver in front of it would otherwise assemble three unrelated projects. Here the build system, the packaging and the documentation site are shared.

The audience is narrower than "anyone who needs DNS". The Authoritative Server depends on Boost, OpenSSL and Lua, and the README states it requires a compiler with C++-2017 support. That is a normal requirement for a distribution packager or a platform engineer, and an unusual one for someone who just wants a name to resolve. The README points to .deb and .rpm packages as an alternative to building, which is the path most operators will take.

How the three components fit together

The split is by role, not by layer. The Authoritative Server holds zones and answers from a backend. The README explains that when ./configure runs without --with-modules, the bind and gmysql modules are built in by default, while the pipe-backend is compiled for runtime loading. So the storage decision is a configure-time decision for the common backends. A zone served from a BIND-format file and a zone served from MySQL are the same server binary with different module sets.

dnsdist sits in front and does not store anything. The repository's docker-compose.yml shows the intended topology: dnsdist declares links to both recursor and auth, and publishes port 3053 for DNS alongside 5199 and 8083. The recursor publishes 2053 and the auth server 1053. Three separate DNS listeners, one front door. The API keys are passed as environment variables (PDNS_RECURSOR_API_KEY, PDNS_AUTH_API_KEY, DNSDIST_API_KEY), which tells you the management interfaces are expected to be reachable in this arrangement.

The Recursor and dnsdist have their own build instructions in pdns/recursordist/README.md and pdns/dnsdistdist/README.md rather than in the top-level file. If you only want dnsdist, the top-level README will not get you there.

Building the Authoritative Server from source

The README gives Debian and Ubuntu package lists. On Debian the base set is compiler, Boost, libtool, pkg-config, the MySQL client library, OpenSSL and LuaJIT. Building from a git checkout adds the autotools and parser generators. Note that the Debian list and the Ubuntu list are not identical; the Ubuntu one adds curl, yaml and sqlite packages, so do not assume the shorter list is complete on Ubuntu.

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

That is the Debian set from the README. From a git clone you also need the build tooling:

apt install autoconf automake ragel bison flex

Then generate the configure script and build. The README's minimal configuration disables all modules and Lua records, producing a server with no backends compiled in:

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

A more typical configuration names the backends explicitly. The README notes that PostgreSQL development headers are needed for gpgsql:

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

After configuring, make produces the server binary. The README shows make install commented out, so the install step is your choice rather than an automatic part of the build.

A first run with the bundled Docker compose file

The repository ships Dockerfile-auth, Dockerfile-recursor and Dockerfile-dnsdist, and docker-compose.yml wires all three together. The compose file uses the version 2.0 schema and builds each service from the repository root. It does not set the API key values, only forwards the variable names, so an unset environment variable means an unset key.

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

That is the auth service from the file. The recursor and dnsdist services follow the same pattern with their own Dockerfiles and keys. Because the host ports are 1053, 2053 and 3053 rather than 53, the stack can run without binding a privileged port. Query the auth server on 1053 and you are talking to the authoritative component; query dnsdist on 3053 and you are going through the load balancer.

One detail worth noticing: the compose file maps both TCP and UDP for port 53 in every service, which is correct for DNS, but the API ports (8081, 8082, 8083) are TCP only. The README does not document authentication for those ports beyond the API key variables, so treat them as an internal interface.

Where the single-repository design costs you

Building all three from one tree means the dependency surface is the union of all three. The Ubuntu list in the README is long, and it is long because it covers more than one program. If you want only dnsdist, you are still reading a page whose first half is about the Authoritative Server, and the README says so directly: the Recursor and dnsdist have their own README files in subdirectories.

The second cost is the backend decision. Because bind and gmysql are built in by default, a build that looks successful can still be missing the backend you intended. The README's example of an empty --with-modules string produces a server with no modules at all, which is a valid build and a useless server. There is no runtime warning described in the README for that case.

Third, the top-level README warns about itself. It states the file may lag behind and directs readers to the changelog on doc.powerdns.com. For a project with three release streams, the repository README is a starting point, not the reference.

PowerDNS compared with CoreDNS

People search for this comparison, and the difference is architectural rather than cosmetic. CoreDNS is a single Go binary configured by a Corefile, with plugins chained in order; there is no separate authoritative and recursive program, and no compile-time backend selection. PowerDNS splits the roles: the Authoritative Server serves zones from a backend you choose at configure time, and the Recursor is a distinct program with its own README and build.

The practical consequence is deployment shape. A CoreDNS deployment is typically one container and one config file. The PowerDNS compose file in this repository is three services with three API keys and six published ports. If your need is a small resolver with a plugin or two, the PowerDNS model asks for more moving parts than the problem requires. If your need is a zone database in PostgreSQL with a caching resolver and a load balancer in front, the PowerDNS components were designed for exactly that arrangement, and the compose file is the shortest demonstration of it.

Licence and the cost of staying current

The README states the project is copyright PowerDNS.COM BV and contributors under the GNU GPLv2 license, and points to the NOTICE file for the exact license and the exception used. That exception is worth reading before you redistribute a modified server, because GPL-2.0 obligations attach to distribution, not to running the software internally. Nothing here is legal advice; read COPYING and NOTICE yourself.

The upgrade cost is the module matrix. Each build pins a set of backends, and changing that set means reconfiguring and rebuilding. On the packaging path the README mentions .deb and .rpm releases, which moves that burden to the packager but also means your backend must be one the package was built with. The repository's last push was on 2026-09-22, so the tree is moving; the README's own warning about lagging behind applies to any instructions you copy from it.

Editorial conclusion

Adopt PowerDNS/pdns when you need an authoritative server with a choice of SQL or file backends, or when you want caching and load balancing in front of it. Skip it if you want a single small binary with no database and no module decision to make. Before committing, run ./configure --with-modules="bind gmysql gpgsql" once to confirm the development headers for PostgreSQL and MySQL are present, because the default build only pulls in bind and gmysql.

Frequently asked questions

Official sources

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