From: Chris Hofstaedtler Date: Mon, 5 Jun 2023 20:51:59 +0000 (+0200) Subject: auth: docs: warn more clearly about setting-outgoing-axfr-expand-alias=ignore-errors X-Git-Tag: rec-5.0.0-alpha1~163^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=43bbbf845c5d1fd8c6133a0e2638fbc017b75c80;p=thirdparty%2Fpdns.git auth: docs: warn more clearly about setting-outgoing-axfr-expand-alias=ignore-errors --- diff --git a/docs/guides/alias.rst b/docs/guides/alias.rst index b85762cbaa..48c74bd65c 100644 --- a/docs/guides/alias.rst +++ b/docs/guides/alias.rst @@ -34,26 +34,29 @@ When the authoritative server receives a query for the A-record for ``example.net``, it will resolve the A record for ``mywebapp.paas-provider.net`` and serve an answer for ``example.net`` with that A record. -If the ALIAS target can not be resolved (SERVFAIL) or does not exist -(NXDOMAIN) the authoritative server will answer SERVFAIL. - -When a zone containing ALIAS records is transferred over AXFR, the -:ref:`setting-outgoing-axfr-expand-alias` -setting controls the behaviour of ALIAS records. When set to 'no' (the -default), ALIAS records are sent as-is (RRType 65401 and a DNSName in -the RDATA) in the AXFR. When set to 'yes', PowerDNS will lookup the A -and AAAA records of the name in the ALIAS-record and send the results in -the AXFR. -If the ALIAS target can not be resolved during AXFR the AXFR will fail. -To allow outgoing AXFR also if the ALIAS targets are broken you can set -:ref:`setting-outgoing-axfr-expand-alias` to 'ignore-errors', but -be warned, this will lead to inconsistent zones between the Primary and -Secondary name servers. - -Set ``outgoing-axfr-expand-alias`` to 'yes' if your slaves don't -understand ALIAS or should not look up the addresses themselves. Note -that slaves will not automatically follow changes in those A/AAAA -records unless you AXFR regularly. +If the ALIAS target cannot be resolved (SERVFAIL) or does not exist (NXDOMAIN) the authoritative server will answer SERVFAIL. + +.. _alias_axfr: + +AXFR Zone transfers +------------------- + +When a zone containing ALIAS records is transferred over AXFR, the :ref:`setting-outgoing-axfr-expand-alias` setting controls the behaviour of ALIAS records. + +When set to 'no' (the default), ALIAS records are sent as-is (RRType 65401 and a DNSName in the RDATA) in the AXFR. + +When set to 'yes', PowerDNS will look up the A and AAAA records of the name in the ALIAS-record and send the results in the AXFR. +This is useful when your secondary servers do not understand ALIAS, or should not look up the addresses themselves. +Note that secondaries will not automatically follow changes in those A/AAAA records unless you AXFR regularly. + +If the ALIAS target cannot be resolved, the AXFR will fail. +When set to 'ignore-errors', an unresolvable ALIAS target will be omitted from the outgoing transfer. + +.. warning:: + Setting ``setting-outgoing-axfr-expand-alias`` to 'ignore-errors', will allow an outgoing AXFR with a broken ALIAS target to complete, but the secondary server will receive an incomplete zone. + There is no standard mechanism for automatic re-transfer for zones broken in this way. + You should make sure this behaviour is acceptable in your use case, provide custom integration tooling to monitor such problems, and possibly fix them automatically. + .. note:: The ``expand-alias`` setting does not exist in PowerDNS