pdns-etcd3

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 last release (and first ever) was 0.1.0+0.1.0, the first development release considered alpha quality. Any testing is appreciated.

Features

• 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 respoonses 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 JSON-supported records
• 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
• Multi-level defaults and options, overridable
• Upgrade data structure (if needed for new program version) without interrupting service

Planned

• Reduce redundancy in the data by automatically deriving corresponding data
  • A ⇒ PTR (in-addr.arpa)
  • AAAA ⇒ PTR (ip6.arpa)
  • …
• Default prefix for IP addresses
  • overrideable per entry
• Override of domain name appended to unqualified names (instead of zone name)
  • useful for PTR records in reverse zones
• Short syntax for single-value objects
  • or for the only value left when using defaults (e.g. target in SRV)
• Support for defaults and zone appending (and possibly more) in plain-string records (those which are also JSON-supported/implemented)
• "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, …
• Support more encodings for values (beside JSON)
  • JSON5 by flynn/json5 (replace default JSON, b/c JSON5 is a superset of JSON)
  • EDN by go-edn
• DNSSEC support (PowerDNS DNSSEC-specific calls)
• Run standalone for usage as a Unix connector
  • This could be needed for big data sets, b/c the initialization from PowerDNS is done lazily on first request (which possibly could timeout on "big data"…) :-(

Optional

• "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)
• Further encodings
  • TOML by pelletier/go-toml or BurntSushi/toml
  • YAML by go-yaml
  • …
• DNS update support
• Prometheus exporter

I should open polls for the optional features.

Installation

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

NOTE: 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.

Usage

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

PowerDNS configuration

launch+=remote
remote-connection-string=pipe:command=/path/to/pdns-etcd3[,pdns-version=3|4][,<config>][,prefix=<string>][,timeout=<integer>][,log-<level>=<components>]

NOTE: Every option name must be given exactly as denoted here (no case changes allowed).

pdns-version is 4 by default, but may be set to 3 to enable PowerDNS v3 compatibility. Version 3 and 4 have incompatible protocols with the backend, so one must use the proper one.

<config> is one of

• configFile=/path/to/etcd-config-file
• endpoints=192.168.1.7:2379|192.168.1.8:2379
• MAYBE LATER (see below) discovery-srv=example.com

TLS and authentication is only possible when using the configuration file.

The configuration file is the one accepted by the official client (see etcd/clientv3/config.go, TODO find documentation).

endpoints accepts hostnames too, but be sure they are resolvable before PowerDNS has started. Same goes for discovery-srv; it is undecided yet if this config is needed.

If <config> is not given, it defaults to endpoints=[::1]:2379|127.0.0.1:2379

prefix is optional and is empty by default.

timeout is optional, given in milliseconds and defaults to 2000 (2 seconds). The value must be a positive integer.

log-<level>=<components> - <level> is one of the logging levels (see below), <components> is one or more of the components names (see below), separated by +. Component names must be all lowercase. That option can be repeated for different logging levels.
Example: log-debug=main+pdns,log-trace=etcd+data

ETCD structure

See ETCD structure. The structure lies beneath the prefix configured in PowerDNS (see above).

Compatibility

pdns-etcd3 is tested on PowerDNS versions 3 and 4, and uses an ETCD v3 cluster. It's currently only one version of each (pdns 3.x and 4.y, ETCD API 3.0), until I find a way to test it on different versions easily. 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. Most likely it will work on other "usually compatible" versions, but that cannot be guaranteed.

Testing / Debugging

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.

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, watchers, 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" (perhaps this one should be an error?)
• 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"

License

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

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

Donations

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.