From d8fceb517d40ef1533e80a88faa781223bf719f8 Mon Sep 17 00:00:00 2001 From: Fredrik Lindeberg Date: Thu, 29 Jan 2026 06:26:34 +0100 Subject: [PATCH 1/6] Added paragraphs on handling explicit SOAs --- documentation/provider/powerdns.md | 33 +++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/documentation/provider/powerdns.md b/documentation/provider/powerdns.md index 81d1dbc5d0..e37aa05e56 100644 --- a/documentation/provider/powerdns.md +++ b/documentation/provider/powerdns.md @@ -74,10 +74,41 @@ See [PowerDNS documentation on Views](https://doc.powerdns.com/authoritative/vie ## Caveats ### SOA Records -The SOA record is supported for use, but behavior is slightly different than expected. +SOA-support was implemented in version 4.16. Versions earlier than that (e.g., 4.15 and earlier) do not support SOA records and will raise an error if they are present in dnscontrol. However, version 4.16 _requires_ SOA-records to be present in dnscontrol, since dnscontrol will synchronize SOA records as any normal records to PowerDNS (as PowerDNS handles SOA as any other record), and thus remove them if not present in dnscontrol. See below for tips how to handle this. + +In version later than 4.16+ the SOA record is supported for use, but behavior is slightly different than expected. If the SOA record is used, [PowerDNS will not increase the serial](https://doc.powerdns.com/authoritative/dnsupdate.html#soa-serial-updates) if the SOA record content changes. This itself comes with exceptions as well, if the `SOA-EDIT-API` is changed to a different value the logic will update the serial to a new value. See [this issue for detailed testing](https://github.com/StackExchange/dnscontrol/pull/3404#issuecomment-2628989200) of behavior. The recommended procedure when changing the SOA record contents is to update the SOA record alone. Updates to other records will be done if changes are present, but the serial **will not change**. The serial will update once a new push is done that does not include an SOA record change. + +### Tips for upgrading past version 4.16 +Since dnscontrol v4.16 SOA-records have to be present in dnscontrol for PowerDNS. This is a breaking change from version 4.15 and requires changes on the user side. + +If you have a large number of zones it might be useful to handle this via built-in functions of dnscontrol. + +```javascript +// Add to bottom of dnsconfig.js or similar + +// Default SOA +var SOA_DEFAULT = [ + SOA( + "@", + "ns.example.org.", // <-- Change to your nameserver + "noc.example.org.", // <-- Change to your contact adress / administrators address + 7200, // <--refresh + 900, // <--retry + 604800, // <--expire + 1800, // <-- ttl for _ZONE_ + TTL("1h")) // <-- ttl for _RECORD_ +]; + +// Add default SOA to all configured domains +var domains = getConfiguredDomains(); +for (i = 0; i < domains.length; i++) { + // Possibly introduce an if-statment to set different SOAs to reverses, k8s-zones, etc + D_EXTEND(domains[i], SOA_DEFAULT); +} +``` \ No newline at end of file From b096dbc75f38b0c4fd9c0d4621898e4a073a54c8 Mon Sep 17 00:00:00 2001 From: Fredrik Lindeberg Date: Thu, 29 Jan 2026 06:28:56 +0100 Subject: [PATCH 2/6] Added paragraphs on handling explicit SOAs --- documentation/provider/powerdns.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/documentation/provider/powerdns.md b/documentation/provider/powerdns.md index e37aa05e56..a351801e02 100644 --- a/documentation/provider/powerdns.md +++ b/documentation/provider/powerdns.md @@ -111,4 +111,9 @@ for (i = 0; i < domains.length; i++) { // Possibly introduce an if-statment to set different SOAs to reverses, k8s-zones, etc D_EXTEND(domains[i], SOA_DEFAULT); } -``` \ No newline at end of file +``` + +This will set a default SOA for all zones managed by this dnscontrol +instance. Note that you might want to have different SOAs for different +zones, for example a very low `ttl` for kubernetes managed zones, this can +be handled with an `if`-statement in the for loop. \ No newline at end of file From 04faa7b276c49c2b3a5e3050660662c17ea4e62d Mon Sep 17 00:00:00 2001 From: Fredrik Lindeberg Date: Thu, 29 Jan 2026 06:31:32 +0100 Subject: [PATCH 3/6] Added paragraphs on handling explicit SOAs --- documentation/provider/powerdns.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/documentation/provider/powerdns.md b/documentation/provider/powerdns.md index a351801e02..d84f060597 100644 --- a/documentation/provider/powerdns.md +++ b/documentation/provider/powerdns.md @@ -89,6 +89,7 @@ Since dnscontrol v4.16 SOA-records have to be present in dnscontrol for PowerDNS If you have a large number of zones it might be useful to handle this via built-in functions of dnscontrol. +{% code title="dnsconfig.js" %} ```javascript // Add to bottom of dnsconfig.js or similar @@ -112,6 +113,7 @@ for (i = 0; i < domains.length; i++) { D_EXTEND(domains[i], SOA_DEFAULT); } ``` +{% endcode %} This will set a default SOA for all zones managed by this dnscontrol instance. Note that you might want to have different SOAs for different From f1eaf8ed790bfdde1217f466ca7088612759b30e Mon Sep 17 00:00:00 2001 From: Tom Limoncelli <6293917+tlimoncelli@users.noreply.github.com> Date: Fri, 20 Feb 2026 15:42:48 -0500 Subject: [PATCH 4/6] Update documentation/provider/powerdns.md Co-authored-by: Jeffrey Cafferata --- documentation/provider/powerdns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/provider/powerdns.md b/documentation/provider/powerdns.md index d84f060597..454318edf9 100644 --- a/documentation/provider/powerdns.md +++ b/documentation/provider/powerdns.md @@ -117,5 +117,5 @@ for (i = 0; i < domains.length; i++) { This will set a default SOA for all zones managed by this dnscontrol instance. Note that you might want to have different SOAs for different -zones, for example a very low `ttl` for kubernetes managed zones, this can +zones, for example a very low `ttl` for Kubernetes (K8s) managed zones, this can be handled with an `if`-statement in the for loop. \ No newline at end of file From 20e252c0f4f258a1defbb90701c46e709b84710f Mon Sep 17 00:00:00 2001 From: Tom Limoncelli <6293917+tlimoncelli@users.noreply.github.com> Date: Fri, 20 Feb 2026 15:42:55 -0500 Subject: [PATCH 5/6] Update documentation/provider/powerdns.md Co-authored-by: Jeffrey Cafferata --- documentation/provider/powerdns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/provider/powerdns.md b/documentation/provider/powerdns.md index 454318edf9..9072bd2eba 100644 --- a/documentation/provider/powerdns.md +++ b/documentation/provider/powerdns.md @@ -74,7 +74,7 @@ See [PowerDNS documentation on Views](https://doc.powerdns.com/authoritative/vie ## Caveats ### SOA Records -SOA-support was implemented in version 4.16. Versions earlier than that (e.g., 4.15 and earlier) do not support SOA records and will raise an error if they are present in dnscontrol. However, version 4.16 _requires_ SOA-records to be present in dnscontrol, since dnscontrol will synchronize SOA records as any normal records to PowerDNS (as PowerDNS handles SOA as any other record), and thus remove them if not present in dnscontrol. See below for tips how to handle this. +SOA-support was implemented in version 4.16. Versions earlier than that (e.g., 4.15 and earlier) do not support SOA records and will raise an error if they are present in DNSControl. However, version 4.16 _requires_ SOA-records to be present in DNSControl, since DNSControl will synchronize SOA records as any normal records to PowerDNS (as PowerDNS handles SOA as any other record), and thus remove them if not present in DNSControl. See below for tips how to handle this. In version later than 4.16+ the SOA record is supported for use, but behavior is slightly different than expected. If the SOA record is used, [PowerDNS will not increase the serial](https://doc.powerdns.com/authoritative/dnsupdate.html#soa-serial-updates) if the SOA record content changes. From 4cdff23deefa7a8017299556588596bcb07a409c Mon Sep 17 00:00:00 2001 From: Tom Limoncelli <6293917+tlimoncelli@users.noreply.github.com> Date: Fri, 20 Feb 2026 15:43:11 -0500 Subject: [PATCH 6/6] Update documentation/provider/powerdns.md Co-authored-by: Jeffrey Cafferata --- documentation/provider/powerdns.md | 1 - 1 file changed, 1 deletion(-) diff --git a/documentation/provider/powerdns.md b/documentation/provider/powerdns.md index 9072bd2eba..b620b4a7bb 100644 --- a/documentation/provider/powerdns.md +++ b/documentation/provider/powerdns.md @@ -91,7 +91,6 @@ If you have a large number of zones it might be useful to handle this via built- {% code title="dnsconfig.js" %} ```javascript -// Add to bottom of dnsconfig.js or similar // Default SOA var SOA_DEFAULT = [