Before upgrading, it is advised to read the Changelogs. When upgrading several versions, please read all notes applying to the upgrade.
Parsing of old-style settings is no longer enabled by default.
Convert your settings file to YAML (see Conversion of old-style settings to YAML format) or pass --enable-old-settings on the command line.
The way incoming.max_tcp_clients is enforced has changed.
If there are too many incoming TCP connections, new connections will be accepted but then closed immediately.
Previously, excess connections would linger in the OS listen queue until timeout or until processing of incoming TCP connections resumed due to the number of connections being processed dropping below the limit.
There is a new metric tcp-overflow that counts the connections closed immediately.
The outqueries-per-query value reported in the log by the periodic statistics function is now reported as outqueries-per-query-perc as it is a percentage.
A value of 1 means that on average each 100 incoming queries lead to a single query to an authoritative server.
A new rec_control reload-yaml command has been introduced as an alias for reload-lua-config.
Both commands will (if YAML settings are active), reload the runtime reloadable parts of the YAML settings.
These are the YAML settings that correspond to Lua configuration items, plus a few new settings that have no Lua equivalent.
The documentation has been updated to state more clearly which settings can be modified at runtime.
ip6.arpa domain.ip6.arpa domain.The recursor.conf configuration file may contain YAML configuration syntax and new installs using our packages from repo.powerdns.com will install a configuration file using YAML syntax. Note to third-party package maintainers: please start doing the same.
Warning
If you are using the default unmodified recursor.conf from a previous release, it will be overwritten by an equivalent recursor.conf in YAML format by most packaging tools.
If you also have local setting files in the include directory, these are now expected to be in YAML format as well, because the format of the included files must be the same as the format of the main recursor.conf.
This has the consequence that the previously included files will not be processed after the upgrade.
To work around this issue, either:
recursor.conf before upgrading so it does not get overwritten by the upgrade,recursor.conf after upgrading,.yml suffix.A modified recursor.conf file will not be overwritten by an upgrade.
sysctl vm.max_map_count is too low to support the maximum number of mthread stacks. In this case Recursor logs an error message including the suggested value of vm.max_map_count to not cause lowering of max-mthreads.String to Sequence of Subnet.The DNSSEC validation issue with the zoneToCache() function has been resolved and workarounds can be removed.
The zoneToCache() function fails to perform DNSSEC validation if the zone has more than max-rrsigs-per-record RRSIG records at its apex.
There are two workarounds: either increase the max-rrsigs-per-record to the number of RRSIGs in the zone’s apex, or tell zoneToCache() to skip DNSSEC validation. by adding dnssec="ignore", e.g.:
zoneToCache(".", "url", "https://www.internic.net/domain/root.zone", {dnssec="ignore"})
Starting with version 5.0.0-alpha1 the settings file(s) can be specified using YAML syntax.
The old-style settings files are still accepted but will be unsupported in a future release.
When a recursor.yml settings file is encountered it will be processed instead of a recursor.conf file.
Refer to PowerDNS Recursor New Style (YAML) Settings for details and the Conversion of old-style settings to YAML format guide for how to convert old-style settings to the new YAML format.
Some parts of the Recursor code are now written in Rust.
This has impact if you do local builds or are a third-party package maintainer.
According to cargo msrv the minimum version to compile the Rust code and its dependencies is 1.64.
Some distributions ship with an older Rust compiler, see Rustup for a way to install a more recent one.
For our package builds, we install a Rust compiler from the Standalone section of Other Rust Installation Methods.
Recursion Desired (RD) flag set.
This is a change in behavior compared to previous releases.ignoreDuplicates was added to the RPZ loading Lua functions rpzPrimary() and rpzFile().
If set, duplicate records in RPZs will be allowed but ignored.
The default is to fail loading an RPZ with duplicate records.The way metrics are collected has been changed to increase performance, especially when many thread are used.
This allows for solving a long-standing issue that some statistics were not updated on packet cache hits.
This is now resolved, but has the consequence that some metrics (in particular response related ones) changed behaviour as they now also reflect packet cache hits, while they did not before.
This affects the results shown by rec_control get-qtypelist and the response-by-qtype, response-sizes and response-by-rcode items returned by the /api/v1/servers/localhost/statistics API endpoint.
Additionally, most RCodes and QTypes that are marked Unassigned, Reserved or Obsolete by IANA are not accounted, to reduce the memory consumed by these metrics.
includeSOA was added to the rpzPrimary() and rpzFile() Lua functions to include the SOA of the RPZ the responses modified by the RPZ.The first two settings below have effect on the way the recursor distributes queries over threads. In some cases, this can lead to imbalance of the number of queries process per thread. See Performance Guide, in particular the Imbalance section.
no.yes.The trace_regex subcommand has been changed to take a file argument.
Refer to rec_control trace-regex and Tracing Queries for details and example use.
The cache eviction policy for the record and the negative caches has been improved to reduce imbalance between shards.
The maximum size of the negative cache is now 1/8th of the size of the record cache and its number of shards is 1/8th of the record-cache-shards setting.
Previously the size was 1/10th of the record cache size and the number of shards was equal to the
number of shards of the record cache.
The rec_control dump-cache command now prints more information about shards.
All logging (except query tracing) has been converted to structured logging.
Switch to old style logging by setting the structured-logging setting to no.
When using systemd, structured logging information will be sent to journald using formatted text strings that list the key-value pairs and are human readable.
Switch to native key-value pair logging (more suitable for automated log processing) by setting structured-logging-backend on the command line to systemd-journal.
Serve Stale feature has been introduced.journald has been introduced.THe --config command line option now implements the check, default and diff keywords.
The dump-throttle and dump-edns subcommands no longer produces a table per thread, as the corresponding tables are now shared by all threads.
Additionally, the dump-edns command now only lists IPs that have a not OK status.
The dump-nsspeeds command has changed format to make it more readable and lists the last round trip time recorded for each address.
The get-proxymapping-stats and get-remotelogger-stats subcommands have been added.
The Zone to Cache feature now validates ZONEMD records. This means that zones containing invalid ZONEMD records will
be rejected by default, while previously the ZONEMD records would be ignored. For more detail, refer to Zone to Cache.
AAAA records for nameservers¶If IPv6 is enabled for outgoing queries using query-local-address, the Recursor will schedule an asynchronous task to resolve IPv6 addresses of nameservers it did not otherwise learn.
These addresses will then be used (in addition to IPv4 addresses) for future queries to authoritative nameservers.
This has the consequence that authoritative nameservers will be contacted over IPv6 in more case than before.
addAllowedAdditionalQType() Lua configuration function was added to make the Recursor add additional records to answers for specific query types.addProxyMapping() Lua configuration function was added to map source addresses to alternative addresses.A new postresolve_ffi() Lua callback function has been introduced.
NS set contains names not in the child NS set.DoT support of authoritative servers.
This is an experimental function, use with care.The dump-nsspeeds, dump-failedservers and dump-non-resolving subcommands no longer produce a table per thread, as the corresponding tables are now shared by all threads.
They also use a better readable and sortable timestamp format.
Using the settings mentioned in Offensive language now generates a warning. Please start using the new names.
The number of file descriptors used by the Recursor has increased because the Recursor now keeps idle outgoing TCP/DoT connections open for a while. The extra file descriptors used in comparison to previous versions of the Recursor is tcp-out-max-idle-per-thread times the number of worker threads (threads).
$include directives while processing a zone file.In our Docker image, our binaries are no longer granted the net_bind_service capability, as this is unnecessary in many deployments.
For more information, see the section “Privileged ports” in Docker-README.
Synonyms for various settings names containing master, slave,
whitelist and blacklist have been introduced.
rpzMaster() use rpzPrimary().Currently, the older setting names are also accepted and used. The next release will start deprecating them. Users are advised to start using the new names to avoid future trouble.
Queries for all names in the .localhost domain will answer in accordance with RFC 6761 section 6.3 point 4.
That means that they will be answered with 127.0.0.1, ::1 or a negative response.
For the commands that write to a file, the file to be dumped to is now opened by the rec_control command itself using the credentials and the current working directory of the user running rec_control. A single minus - can be used as a filename to write the data to the standard output stream. Previously the file was opened by the recursor, possibly in its chroot environment.
process-no-validate to process.query-local-address6 setting has been removed. It already was deprecated.To conform better to the standard, RPZ processing has been modified.
This has consequences for the points in the resolving process where matches are checked and callbacks are called.
See Response Policy Zones (RPZ) for details. Additionally a new type of callback has been introduced: policyEventFilter().
The method to drop a query from a Lua callback has been changed. Previously, you could set rcode to pdns.DROP. See Callback Semantics for the new method.
The parsing (from zone files) of unknown records types (of the form
\# <length> <hex data>) has been made more strict. Previously, invalid formatted records could produce
inconsistent results.
query-local-address6 setting is now deprecated.record-cache-contended divided by record-cache-acquired indicates if the record cache locks are contended. If so, increasing the number of shards can help reducing the contention.isIpv4 and isIpv6 have been deprecated in Lua, use Netmask.isIPv4() and Netmask.isIPv6() instead. In C++ API these methods have been removed.socket-dir changed¶The default socket-dir has changed to include pdns-recursor in the path.
For non-chrooted setups, it is now whatever is passed to --with-socketdir during configure (/var/run by default) plus pdns-recursor.
The systemd unit-file is updated to reflect this change and systemd will automatically create the directory with the proper permissions.
The packaged sysV init-script also creates this directory.
For other operating systems, update your init-scripts accordingly.
The systemd service-file that is installed no longer uses the root user to start.
It uses the user and group set with the --with-service-user and --with-service-group switches during
configuration, “pdns” on Debian and “pdns-recursor” on CentOS by default.
This could mean that PowerDNS Recursor cannot read its configuration, lua scripts, auth-zones or other data.
It is recommended to recursively chown directories used by PowerDNS Recursor:
# For Debian-based systems
chown -R root:pdns /etc/powerdns
# For CentOS and RHEL based systems
chown -R root:pdns-recursor /etc/pdns-recursor
Packages provided on the PowerDNS Repository will chown directories created by them accordingly in the post-installation steps.
$GENERATE directive. The default is 0, which is unlimited.Two new settings have been added:
xpf-allow-from can contain a list of IP addresses ranges from which XPF (X-Proxied-For) records will be trusted.setting-xpf-rr-code should list the number of the XPF record to use (in lieu of an assigned code).loglevel defaulted to 4 but was always overridden to 6 during the startup. The issue has been fixed and the default value set to 6 to keep the behavior consistent.
The --with-libsodium configure flag has changed from ‘no’ to ‘auto’.
This means that if libsodium and its development header are installed, it will be linked in.
One setting has been added to limit the risk of overflowing the stack:
Two settings have changed defaults, these new defaults decrease CPU usage: