A PowerDNS remote backend with ETCD v3 cluster as storage. It uses the official client to get the data from the cluster. Responses are authoritative for each zone found in the data. Only the DNS class IN is supported, but that's because of the limitation of PowerDNS.

There is no stable release yet, even no beta. The latest release is v0.3.0+0.1.2, the third development release, considered alpha quality. Any testing is appreciated.

• Automatic serial for SOA records (based on the cluster revision).
• Replication is handled by the ETCD cluster, no additional configuration is needed for using multiple authoritative PowerDNS servers.
  • DNS responses are nearly instantly up-to-date (on every server instance!) after data changes by using a watcher into ETCD (multi-master)
• Multiple syntax possibilities for (values of) object-supported records
  • JSON5 or YAML
  • different representations of values (e.g. an IPv4 as "192.0.2.1" or [192, 0, 2, 1], a duration as 2h, and more...)
• Short syntax for single-value objects
  • or for the last value left when using defaults (e.g. target in SRV)
• Default prefix for IP addresses
  • overrideable per entry
• Support for custom records (types), like those supported by PowerDNS but unimplemented in pdns-etcd3
• Support for automatically appending zone name to unqualified domain names
• Override of domain name appended to unqualified names (instead of zone name)
  • useful for PTR records in reverse zones
• Support for defaults and zone appending in most plain-string records (only supported ones)
  • e.g. in an SRV entry: 20 5 _ server1, the port will be searched for in default values, the name server1 will be appended with the zone name
  • same entry in JSON5 syntax: {priority: 20, weight: 5, target: "server1"} (this is longer but clearer)
• ALIAS support
• Multi-level defaults and options, overridable
• Upgrade data structure (if needed for new program version) without interrupting service
• Run standalone for usage as a Unix or HTTP connector
  • This could be needed for big data sets, because the initialization from PowerDNS is done lazily (at least as of v4) on first request (which possibly could time out on "big data"…) :-(

• Reduce redundancy in the data by automatically deriving corresponding data
  • A ⇒ PTR (in-addr.arpa)
  • AAAA ⇒ PTR (ip6.arpa)
  • …
• "Collect record", automatically combining A and/or AAAA records from "server records"
  • e.g. etcd.example.com based on etcd-1.example.com, etcd-2.example.com, …
• "Labels" for selectively applying defaults and/or options to record entries
  • sth. like com/example/-options-ptr → {"auto-ptr": true} and com/example/www/-options-collect → {"collect": …} for com/example/www-1/A+ptr+collect without global options
  • precedence betweeen QTYPE and id (id > label > QTYPE)
• DNSSEC support (PowerDNS DNSSEC-specific calls)

• Support more encodings for values
  • EDN by go-edn
  • TOML by pelletier/go-toml or BurntSushi/toml
  • …
• DNS update support
• Prometheus exporter
• ZeroMQ connector

git clone https://github.com/nixn/pdns-etcd3.git
cd pdns-etcd3
make

NOTE: A plain go build will also work, but you will get a dynamically linked executable and incomplete version information in the binary. The build command in Makefile produces a static build with setting the version string properly. For convenience, it is repeated here:

export CGO_ENABLED=0
go build -o pdns-etcd3 -a -ldflags="-extldflags=-static -X main.gitVersion=$(git describe --always --dirty)"

Of course, you need an up and running ETCD v3 cluster and a PowerDNS installation.

You have to decide in which mode you want to use the backend: either the pipe mode or a standalone mode.

In pipe mode the backend is launched by PowerDNS dynamically and communicates with it via standard input and output. All the configuration options must be given in the PowerDNS configuration file. But since PowerDNS (at least as of v4) initiates the backend lazily, the 'initialize' call occurs with the first (client) request and the backend has to be fast enough to connect to ETCD, read all data, and reply to this first request. This can be too long, if there is much data to read.

Example PowerDNS configuration file:

launch=remote
remote-connection-string=pipe:command=/path/to/pdns-etcd3[,pdns-version=3|4|5][,<config>][,prefix=<string>][,timeout=<integer>][,dial-keep-alive-time=<duration>][,dial-keep-alive-timeout=<duration>][,auto-sync-interval=<duration>][,permit-without-stream=<bool>][,log-<level>=<components>]
# since in pipe mode every instance connects to ETCD and loads the data for itself (uses memory), possibly do this:
distributor-threads=1

<config> is one of config-file=... or endpoints=... (see "Parameters" below for details on the value). config-file overrides endpoints.

All other modes are so-called "standalone" modes: the backend must be launched outside of PowerDNS (manually, e.g. as a system service). The standalone mode creates a listening socket and waits for connections (from PowerDNS). It takes the ETCD related parameters from the command line and connects to it right after starting up. Then it accepts connections on the socket and serves them. If the standalone mode begins with an 'initialize' call, only the non-ETCD parameters are available to it.

The data is loaded only once (uses memory only once). The data is loaded before accepting connections from PowerDNS, so it is available directly after a PowerDNS instance has connected. It is okay to have parallel accesses to the instance, the data access is protected by mutexes (including updates).

A standalone mode is started by passing the -standalone=<connector-url> flag to pdns-etcd3. The <connector-url> must be a valid URL, specific for each mode.

The unix mode uses a UNIX domain socket, thus it can only run on the same system as PowerDNS. The <connector-url> looks like:

unix:///path/to/pdns-etcd3-socket[?relative=<bool>]

It gives the path to the socket file (which is then used in the PowerDNS configuration, see below). relative is false by default, so the path is taken as an absolute path. When set to true, the leading slash is ignored and the path is taken as a relative path.

The unix mode takes an 'initialize' call, so one can pass parameters to it, which are defined in the PowerDNS configuration.

Example PowerDNS configuration file:

launch=remote
remote-connection-string=unix:path=/path/to/pdns-etcd3-socket[,pdns-version=3|4|5][,log-<level>=<components>]
distributor-threads=3

The HTTP mode uses an HTTP listening socket, thus can serve PowerDNS instances from virtually everywhere, based on the listening address. The <connector-url> looks like:

http://<address>:<port>

One has to give both, <address> and <port>. To listen on all interfaces, the URL could look like: http://0.0.0.0:8053.

The HTTP mode does not take an 'initialize' call.

In the PowerDNS configuration, the parameters post and post_json must be both set to a truthy value (e.g. yes). The requests would be rejected otherwise.

Example PowerDNS configuration file:

launch=remote
remote-connection-string=http:url=http://localhost:8053/,post=yes,post_json=yes

Because there is no 'initialize' call, the version of a connecting PowerDNS cannot be known (and is not passed in the requests). Thus, when one has to change the assumed version, they can use the -pdns-version option (see below).

All parameter keys must be given exactly as denoted here (no case modifications). The ETCD related parameters in standalone mode are given as command line "options", starting with a -: e.g. -config-file=....

The parameters in detail (the ETCD related parameters, which have to be passed as command line argument in standalone mode, are tagged by #STANDALONE):

• config-file=/path/to/etcd.conf #STANDALONE
  The path to an ETCD (client) configuration file, as accepted by the official client (see etcd/client/v3/config.go, TODO find documentation)
  TLS and authentication is only possible when using such a configuration file.
  Overrides endpoints parameter. Defaults to not set.
• endpoints=<IP:Port>[|<IP:Port>|...] #STANDALONE
  For a simple connection use the endpoints given here. endpoints accepts hostnames too (instead of IP), but be sure they are resolvable before PowerDNS has started.
  Defaults to [::1]:2379|127.0.0.1:2379.
• prefix=<string> #STANDALONE
  Every entry in ETCD will be prefixed with that. It is not interpreted or changed in any way, also the data watcher uses it, so any other keys under another prefix do not affect DNS data.
  Tip: Let the prefix start and end with /, so you can use etcdkeeper for easier web-based data management.
  There is no default (= empty).
• timeout=<duration> #STANDALONE or
  timeout=<integer> config file (in milliseconds, e.g. 1500 for 1.5 seconds)
  An optional parameter which sets the dial timeout to ETCD. Must be a positive value (>= 1ms).
  Defaults to 2 seconds.
• dial-keep-alive-time=<duration> #STANDALONE
  Interval at which the client sends keep-alive pings to ETCD on the underlying gRPC (HTTP/2) connection. These pings allow the client to detect a dead endpoint (e.g. a host that vanished without sending a TCP RST/FIN) and rotate to another endpoint instead of waiting for the kernel TCP timeout (~13–15 minutes). Set to 0 to disable keep-alive pings.
  Defaults to 10 seconds.
• dial-keep-alive-timeout=<duration> #STANDALONE
  Time the client waits for an acknowledgement after sending a keep-alive ping. If no ack arrives within this timeout, the connection is considered dead and the client reconnects (to another endpoint if available).
  Defaults to 5 seconds.
• auto-sync-interval=<duration> #STANDALONE
  Interval at which the client refreshes its view of the ETCD cluster member list. This makes new endpoints (e.g. cluster members added or rotated in after the client connected) reachable without restarting the backend. Set to 0 to disable.
  Defaults to 1 minute.
• permit-without-stream=<bool> #STANDALONE
  When true, the client sends keep-alive pings even when no RPC stream is active on the connection. This is needed to detect a dead endpoint while the backend is idle (e.g. between watch events on a low-traffic deployment).
  Defaults to true.
• pdns-version=3|4|5
  The (major) PowerDNS version. Version 3 and 4 have incompatible protocols with the backend, so one must use the proper one. Version 5 is accepted, but works currently the same as 4 (no relevant API changes yet).
  Defaults to 4.
• log-<level>=<components> #STANDALONE and config file
  Sets the logging level of <components> to <level> (see below for values). <components> is one or more of the component names, separated by +. This parameter can be "repeated" for different logging levels. In standalone mode, the levels are set separately for the program and the clients (PowerDNS connections).
  Example: log-debug=main+pdns,log-trace=etcd+data
  Defaults to info for all components.

One can see all available command-line (standalone) parameters with a short description, when running pdns-etcd3 -help.

See ETCD structure. The structure lies beneath the prefix parameter (see above).

pdns-etcd3 is tested on different PowerDNS versions (3.y.z, 4.y.z, and 5.y.z) and uses an ETCD v3 cluster (API 3.0 or higher). It's only one version of each minor (.y), but most likely all (later and earlier) "patch" versions (.z) are compatible. Therefore, each release shall state which exact versions were used for testing, so one can be sure to have a working combination for deploying, when using those (tested) versions.

TODO describe (recommended) cache settings

There is much logging in the program for being able to test and debug it properly. It is structured and leveled, utilizing logrus. The structure consists of different components, namely main, pdns, etcd and data; the (seven) logging levels are taken from logrus. For each component an own logging level can be set, so that one can debug only the component(s) of interest. In the standalone modes the components are "doubled"; there is the program side with its components (main, etcd, data) and the (PDNS) client side (main, pdns), which can be configured separately. In pipe mode there is only one of each component.

The components in detail:

• main - The main thread / loop of the program, e.g. setting up logging, creating data objects, processing signals and events, etc.
• pdns - The communication with PowerDNS, e.g. incoming requests and sending results.
• etcd - The communication with ETCD, e.g. real queries against it, connection issues, watcher, etc.
• data - Everything concerning the values (records, ...), parsing data from ETCD, searching records for requests etc.

The levels in detail:

• panic - Something like the world's end. Actually not used.
• fatal - Errors which prevent the program to continue service. After a fatal error the program exits. (Mostly in main component.)
• error - Errors which don't prevent the program to continue service. Different meanings for different components.
• warning (or warn) - Not errors, but situations where it could be done better. An admin should take care of those.
• info - Useful information on the program, something like "initialized, ready for service". This is the default level for each component.
• debug - "Big steps", like "sending request to ETCD", "Handling event" or "default value not found for X"
• trace - Small steps and all values, e.g. "found default value for X in Y" or "record: www.example.com./A#some-id = 192.0.2.12"

Copyright © 2016-2026 nix https://keybase.io/nixn

Distributed under the Apache 2.0 license, available in the file LICENSE.

If you like pdns-etcd3, please consider donating to support the further development. Thank you!

Bitcoin (BTC): 1pdns4U2r4JqkzsJRpTEYNirTFLtuWee9
Monero (XMR): 4CjXUfpdcba5G5z1LXAx3ngoDtAHoFGdpJWvCayULXeaEhA4QvJEHdR7Xi3ptsbhSfGcSpdBHbK4CgyC6Qcwy5Rt2GGDfQCM7PcTgfEQ5Q
Ethereum (ETH): 0x003D87efb7069e875a8a1226c9DadaC03dE1f779

These addresses are dedicated to pdns-etcd3 development. For my general development, other projects and personal donation addresses see my profile or my web page.