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 b85762cbaa4ae20a706981c77d61c8a41147b250..48c74bd65c46e2084997de0e79293a9862d580ce 100644 (file)
--- 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