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.
- 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
- 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
- useful for
- Short syntax for single-value objects
- or for the only value left when using defaults (e.g.
target
inSRV
)
- or for the only value left when using defaults (e.g.
- 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 onetcd-1.example.com
,etcd-2.example.com
, …
- e.g.
- 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"…) :-(
- "Labels" for selectively applying defaults and/or options to record entries
- sth. like
com/example/-options-+ptr
→{"auto-ptr": true}
andcom/example/www/-options-+collect
→{"collect": …}
forcom/example/www-1/A+ptr+collect
without global options - precedence betweeen QTYPE and id (id > label > QTYPE)
- sth. like
- 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.
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.
Of course you need an up and running ETCD v3 cluster and a PowerDNS installation.
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
See ETCD structure. The structure lies beneath the prefix
configured in PowerDNS (see above).
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.
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 inmain
component.)error
- Errors which don't prevent the program to continue service. Different meanings for different components.warning
(orwarn
) - 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"
Copyright © 2016-2022 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.