docs/upgrading.rst

   1 Upgrade Notes
   2 =============
   3
   4 Before proceeding, it is advised to check the release notes for your
   5 PowerDNS version, as specified in the name of the distribution file.
   6
   7 Please upgrade to the PowerDNS Authoritative Server 4.0.0 from 3.4.2+.
   8 See the `3.X <https://doc.powerdns.com/3/authoritative/upgrading/>`__
   9 upgrade notes if your version is older than 3.4.2.
  10
  11 4.2.x to 4.3.0
  12 --------------
  13
  14 Lua Netmask class methods changed
  15 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  16
  17 Netmask class methods ``isIpv4`` and ``isIpv6`` have been deprecated in Lua, use :func:`Netmask.isIPv4` and :func:`Netmask.isIPv6` instead. In the C++ API, these methods have been removed.
  18
  19 ``socket-dir`` changed
  20 ^^^^^^^^^^^^^^^^^^^^^^
  21 The default :ref:`setting-socket-dir` has changed to include ``pdns`` in the path.
  22 It is now whatever is passed to ``--with-socketdir`` during configure (``/var/run`` by default) plus ``pdns``.
  23 The systemd unit-file is updated to reflect this change and systemd will automatically create the directory with the proper permissions.
  24 The packaged sysV init-script also creates this directory.
  25 For other operating systems, update your init-scripts accordingly.
  26
  27 Systemd service and permissions
  28 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  29 The systemd service-file that is installed no longer uses the ``root`` user to start.
  30 It uses the user and group set with the ``--with-service-user`` and ``--with-service-group`` switches during configuration, "pdns" by default.
  31 This could mean that PowerDNS cannot read its configuration or zone-file data.
  32 It is recommended to recursively ``chown`` directories used by PowerDNS::
  33
  34   # For Debian-based systems
  35   chown -R root:pdns /etc/powerdns
  36   chown -R pdns:pdns /var/lib/powerdns
  37
  38   # For CentOS and RHEL based systems
  39   chown -R root:pdns /etc/pdns
  40   chown -R pdns:pdns /var/lib/pdns
  41
  42 Packages provided on `the PowerDNS Repository <https://repo.powerdns.com>`__ will ``chown`` directories created by them accordingly in the post-installation steps.
  43
  44 New settings
  45 ^^^^^^^^^^^^
  46
  47 - The :ref:`setting-axfr-fetch-timeout` setting has been added. This setting controls how long an inbound AXFR may be idle in seconds. Its default is 10
  48 - The :ref:`setting-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.
  49
  50 Removed settings
  51 ^^^^^^^^^^^^^^^^
  52
  53 - :ref:`setting-local-ipv6` has been deprecated, and will be removed in 4.4.0. IPv4 and IPv6 listen addresses can now be set with :ref:`setting-local-address`. The default for the latter has been changed to ``0.0.0.0, ::``.
  54
  55 Schema changes
  56 ^^^^^^^^^^^^^^
  57 - The new 'unpublished DNSSEC keys' feature comes with a mandatory schema change for all database backends (including BIND with a DNSSEC database). Please find files named "4.2.0_to_4.3.0_schema.X.sql" for your database backend in our Git repo, tarball, or distro-specific documentation path. For the LMDB backend, please review :ref:`setting-lmdb-schema-version`.
  58
  59 Implicit 5->7 algorithm upgrades
  60 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  61
  62 Since version 3.0 (the first version of the PowerDNS Authoritative Server that supported DNSSEC signing), we have automatically, silently, upgraded algorithm 5 (RSASHA1) keys to algorithm 7 (RSASHA1-NSEC3-SHA1) when the user enabled NSEC3. This has been a source of confusion, and because of that, we introduced warnings for users of this feature in 4.0 and 4.1. To see if you are affected, run ``pdnsutil check-all-zones`` from version 4.0 or up. In this release, the automatic upgrade is gone, and affected zones will break if no action is taken.
  63
  64 4.1.X to 4.2.0
  65 --------------
  66
  67 - Superslave operation is no longer enabled by default, use :ref:`setting-superslave` to enable. This setting was called ``supermaster`` in some 4.2.0 prereleases.
  68 - The gsqlite3 backend, and the DNSSEC database for the BIND backend, have a new journal-mode setting. This setting defaults to `WAL <https://www.sqlite.org/wal.html>`_; older versions of PowerDNS did not set the journal mode, which means they used the SQLite default of DELETE.
  69 - Autoserial support has been removed. The ``change_date`` column has been removed from the ``records`` table in all gsql backends, but leaving it in is harmless.
  70 - The :doc:`Generic PostgreSQL backend <backends/generic-postgresql>` schema has changed: the ``notified_serial`` column type in the ``domains`` table has been changed from ``INT DEFAULT NULL`` to ``BIGINT DEFAULT NULL``: ``ALTER TABLE domains ALTER notified_serial TYPE bigint USING CASE WHEN notified_serial >= 0 THEN notified_serial::bigint END;``
  71
  72 4.1.0 to 4.1.1
  73 --------------
  74
  75 - The :doc:`Generic MySQL backend <backends/generic-mysql>` schema has
  76   changed: the ``notified_serial`` column default in the ``domains``
  77   table has been changed from ``INT DEFAULT NULL`` to ``INT UNSIGNED
  78   DEFAULT NULL``:
  79
  80   - ``ALTER TABLE domains MODIFY notified_serial INT UNSIGNED DEFAULT NULL;``
  81
  82 4.0.X to 4.1.0
  83 --------------
  84
  85 - Recursion has been removed, see the :doc:`dedicated migration guide <guides/recursion>`.
  86 - ALIAS record expansion is disabled by default, use :ref:`setting-expand-alias` to enable.
  87 - *Your LDAP schema might need to be updated*, because new record types
  88   have been added (see below) and the ``dNSDomain2`` type has been
  89   changed.
  90 - The :doc:`LDAP Backend <backends/ldap>` now supports additional Record types
  91
  92   - NSEC3
  93   - NSEC3PARAM
  94   - TLSA
  95   - CDS
  96   - CDNSKEY
  97   - OPENPGPKEY
  98   - TKEY
  99   - URI
 100   - CAA
 101
 102 Changed options
 103 ^^^^^^^^^^^^^^^
 104
 105 -  ``experimental-lua-policy-script`` option and the feature itself have
 106    been completely dropped. We invite you to use `PowerDNS
 107    dnsdist <https://dnsdist.org>`_ instead.
 108
 109 - As recursion has been removed from the Authoritative Server, the
 110   ``allow-recursion``, ``recursive-cache-ttl`` and ``recursor`` options have
 111   been removed as well.
 112
 113 - ``default-ksk-algorithms`` has been renamed to :ref:`setting-default-ksk-algorithm`
 114   and only supports a single algorithm name now.
 115
 116 - ``default-zsk-algorithms`` has been renamed to :ref:`setting-default-zsk-algorithm`
 117   and only supports a single algorithm name now.
 118
 119 Changed defaults
 120 ~~~~~~~~~~~~~~~~
 121
 122 - The default value of :ref:`setting-webserver-allow-from` has been changed from ``0.0.0.0, ::/0`` to ``127.0.0.1, ::1``.
 123
 124 Other changes
 125 ^^^^^^^^^^^^^
 126
 127 The ``--with-pgsql``, ``--with-pgsql-libs``, ``--with-pgsql-includes``
 128 and ``--with-pgsql-config`` ``configure`` options have been deprecated.
 129 ``configure`` now attempts to find the Postgresql client libraries via
 130 ``pkg-config``, falling back to detecting ``pg_config``. Use
 131 ``--with-pg-config`` to specify a path to a non-default ``pg_config`` if
 132 you have Postgresql installed in a non-default location.
 133
 134 The ``--with-libsodium`` configure flag has changed from 'no' to 'auto'.
 135 This means that if libsodium and its development header are installed, it will be linked in.
 136
 137 The improved :doc:`LDAP Backend <backends/ldap>` backend now requires Kerberos headers to be installed.
 138 Specifically, it needs `krb5.h` to be installed.
 139
 140 4.0.X to 4.0.2
 141 --------------
 142
 143 Changed options
 144 ^^^^^^^^^^^^^^^
 145
 146 Changed defaults
 147 ~~~~~~~~~~~~~~~~
 148
 149 -  :ref:`setting-any-to-tcp` changed from ``no`` to ``yes``
 150
 151 3.4.X to 4.0.0
 152 --------------
 153
 154 Database changes
 155 ^^^^^^^^^^^^^^^^
 156
 157 No changes have been made to the database schema. However, several
 158 superfluous queries have been dropped from the SQL backend. Furthermore,
 159 the generic SQL backends switched to prepared statements. If you use a
 160 non-standard SQL schema, please review the new defaults.
 161
 162 -  ``insert-ent-query``, ``insert-empty-non-terminal-query``,
 163    ``insert-ent-order-query`` have been replaced by one query named
 164    ``insert-empty-non-terminal-order-query``
 165 -  ``insert-record-order-query`` has been dropped,
 166    ``insert-record-query`` now sets the ordername (or NULL)
 167 -  ``insert-slave-query`` has been dropped, ``insert-zone-query`` now
 168    sets the type of zone
 169
 170 Changed options
 171 ^^^^^^^^^^^^^^^
 172
 173 Several options have been removed or renamed, for the full overview of
 174 all options, see :doc:`settings`.
 175
 176 Renamed options
 177 ~~~~~~~~~~~~~~~
 178
 179 The following options have been renamed:
 180
 181 -  ``experimental-json-interface`` ==> :ref:`setting-api`
 182 -  ``experimental-api-readonly`` ==> :ref:`setting-api-readonly`
 183 -  ``experimental-api-key`` ==> :ref:`setting-api-key`
 184 -  ``experimental-dname-processing`` ==> :ref:`setting-dname-processing`
 185 -  ``experimental-dnsupdate`` ==> :ref:`setting-dnsupdate`
 186 -  ``allow-dns-update-from`` ==> :ref:`setting-allow-dnsupdate-from`
 187 -  ``forward-dnsupdates`` ==> :ref:`setting-forward-dnsupdate`
 188
 189 Changed defaults
 190 ~~~~~~~~~~~~~~~~
 191
 192 -  :ref:`setting-default-ksk-algorithms`
 193    changed from rsasha256 to ecdsa256
 194 -  :ref:`setting-default-zsk-algorithms`
 195    changed from rsasha256 to empty
 196
 197 Removed options
 198 ~~~~~~~~~~~~~~~
 199
 200 The following options are removed:
 201
 202 -  ``pipebackend-abi-version``, it now a setting per-pipe backend.
 203 -  ``strict-rfc-axfrs``
 204 -  ``send-root-referral``
 205
 206 API
 207 ^^^
 208
 209 The API path has changed to ``/api/v1``.
 210
 211 Incompatible change: ``SOA-EDIT-API`` now follows ``SOA-EDIT-DNSUPDATE``
 212 instead of ``SOA-EDIT`` (incl. the fact that it now has a default value
 213 of ``DEFAULT``). You must update your existing ``SOA-EDIT-API`` metadata
 214 (set ``SOA-EDIT`` to your previous ``SOA-EDIT-API`` value, and
 215 ``SOA-EDIT-API`` to ``SOA-EDIT`` to keep the old behaviour).
 216
 217 Resource Record Changes
 218 ^^^^^^^^^^^^^^^^^^^^^^^
 219
 220 Since PowerDNS 4.0.0 the CAA resource record (type 257) is supported.
 221 Before PowerDNS 4.0.0 type 257 was used for a proprietary MBOXFW
 222 resource record, which was removed from PowerDNS 4.0. Hence, if you used
 223 CAA records with 3.4.x (stored in the DB with wrong type=MBOXFW but
 224 worked fine) and upgrade to 4.0, PowerDNS will fail to parse this
 225 records and will throw an exception on all queries for a label with
 226 MBOXFW records. Thus, make sure to clean up the records in the DB.
 227
 228 In version 3.X, the PowerDNS Authoritative Server silently ignored records that
 229 have a 'priority' field (like MX or SRV), but where one was not in the database.
 230 In 4.X, :doc:`pdnsutil check-zone <manpages/pdnsutil.1>` will complain about this.