Upgrade Guide

Before upgrading, it is advised to read the Changelogs. When upgrading several versions, please read all notes applying to the upgrade.

4.5.x to 4.6.0 or master

Offensive language

Using the settings mentioned in Offensive language now generates a warning. Please start using the new names.

New settings

Deprecated and changed settings

  • The api-key and webserver-password settings now accept a hashed and salted version (if the support is available in the openssl library used).

4.5.1 to 4.5.2

Deprecated and changed settings

4.4.x to 4.5.1

Offensive language

Synonyms for various settings names containing master, slave, whitelist and blacklist have been introduced.

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.

Special domains

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.

rec_control command writing to a file

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. Additionally, 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.

New settings

Deprecated and changed settings

Removed settings

4.3.x to 4.4.0

Response Policy Zones (RPZ)

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().

Parsing of unknown record types

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.

Deprecated and changed settings

New settings

  • The dns64-prefix setting has been added, enabling common cases of DNS64 handling without having to write Lua code.
  • The proxy-protocol-from and proxy-protocol-maximum-size settings have been added to allow for passing of Proxy Protocol Version 2 headers between a client and the recursor.
  • The record-cache-shards setting has been added, enabling the administrator to change the number of shards in the records cache. The value of the metric 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.

4.2.x to 4.3.0

Lua Netmask class methods changed

  • Netmask class methods 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.

Systemd service and permissions

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.

New settings

  • The allow-trust-anchor-query setting has been added. This setting controls if negative trust anchors can be queried. The default is no.
  • The max-concurrent-requests-per-tcp-connection has been added. This setting controls how many requests are handled concurrently per incoming TCP connection. The default is 10.
  • The max-generate-steps setting has been added. This sets the maximum number of steps that will be performed when loading a BIND zone with the $GENERATE directive. The default is 0, which is unlimited.
  • The nothing-below-nxdomain setting has been added. This setting controls the way cached NXDOMAIN replies imply non-existence of a whole subtree. The default is dnssec which means that only DNSSEC validated NXDOMAINS results are used.
  • The qname-minimization setting has been added. This options controls if QName Minimization is used. The default is yes.

4.1.x to 4.2.0

Two new settings have been added:

4.0.x to 4.1.0

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.

4.0.3 to 4.0.4

One setting has been added to limit the risk of overflowing the stack:

4.0.0 to 4.0.1

Two settings have changed defaults, these new defaults decrease CPU usage: