Document ALIAS records and DNSSEC washing

Closes #3978

diff --git a/docs/markdown/authoritative/howtos.md b/docs/markdown/authoritative/howtos.md
index 5792ff56a71e26195dcef89477427bdf6094cf61..9dd164594dcaaf94e845105d43724d2209d8519a 100644 (file)
--- a/docs/markdown/authoritative/howtos.md
+++ b/docs/markdown/authoritative/howtos.md
@@ -155,12 +155,14 @@ If you have multiple IP addresses on the internet on one machine, UNIX often sen
 The ALIAS record provides a way to have CNAME-like behaviour on the zone apex.
 
 In order to correctly serve ALIAS records, set the [`recursor`](settings.md#recursor)
-setting to an existing resolver and add the ALIAS record to your zone apex. e.g.:
+setting to an existing resolver: 
 
 ```
 recursor=[::1]:5300
 ```
 
+and add the ALIAS record to your zone apex. e.g.:
+
 ```
 $ORIGIN example.net
 $TTL 1800
@@ -176,6 +178,23 @@ 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.
 
+When a zone containing ALIAS records is transferred over AXFR, the
+[`outgoing-axfr-expand-alias`](settings.md#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.
+
+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.
+
+## ALIAS and DNSSEC
+Starting with the PowerDNS Authoritative Server 4.0.0, DNSSEC 'washing' of ALIAS
+records is supported on AXFR (**not** on live-siging). Set `outgoing-axfr-expand-alias`
+to 'yes' and enable DNSSEC for the zone on the master. PowerDNS will sign the
+A/AAAA records during the AXFR.
+
 # KSK Rollover
 Before attempting a KSK rollover, please read [RFC 6581 "DNSSEC Operational
 Practices, Version 2", section 4](https://tools.ietf.org/html/rfc6781#section-4)