From dc1bc468214e56da0dc99bb013e7a686f33a5ba2 Mon Sep 17 00:00:00 2001 From: ecraven Date: Tue, 16 Dec 2025 20:57:32 +0100 Subject: [PATCH 1/2] DOCS: POWERDNS: Improve powerdns provider metadata documentation (#3925) Closes #3921 Co-authored-by: Peter Co-authored-by: Tom Limoncelli <6293917+tlimoncelli@users.noreply.github.com> --- documentation/provider/powerdns.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/documentation/provider/powerdns.md b/documentation/provider/powerdns.md index 568d6378b..81d1dbc5d 100644 --- a/documentation/provider/powerdns.md +++ b/documentation/provider/powerdns.md @@ -2,7 +2,7 @@ To use this provider, add an entry to `creds.json` with `TYPE` set to `POWERDNS` along with your [API URL, API Key and Server ID](https://doc.powerdns.com/authoritative/http-api/index.html). -In most cases the Server id is `localhost`. +In most cases the Server id (`serverName`) is `localhost`. Example: @@ -20,23 +20,24 @@ Example: {% endcode %} ## Metadata -Following metadata are available: +Following provider metadata are available: {% code title="dnsconfig.js" %} ```javascript -{ +var DSP_POWERDNS = NewDnsProvider("pdns", { 'default_ns': [ 'a.example.com.', 'b.example.com.' ], 'dnssec_on_create': false, 'zone_kind': 'Native', -} + 'use_views': true +}); ``` {% endcode %} -- `default_ns` sets the nameserver which are used -- `dnssec_on_create` specifies if DNSSEC should be enabled when creating zones +- `default_ns` sets the nameservers which are used. +- `dnssec_on_create` specifies if DNSSEC should be enabled when creating zones. - `zone_kind` is the type that will be used when creating the zone.
Can be one of `Native`, `Master` or `Slave`, when not specified it defaults to `Native`.
Please see [PowerDNS documentation](https://doc.powerdns.com/authoritative/modes-of-operation.html) for explanation of the kinds. From 1431526a5dfdb900569b38932665d8cc781b702e Mon Sep 17 00:00:00 2001 From: Tom Limoncelli <6293917+tlimoncelli@users.noreply.github.com> Date: Tue, 16 Dec 2025 15:31:36 -0500 Subject: [PATCH 2/2] DOCS: Document no_ns (#3926) Fixes https://github.com/StackExchange/dnscontrol/issues/3890 # Issue `no_ns` is undocumented. # Resolution Add it to the nameserver examples page and the `D()` page. --------- Co-authored-by: Jeffrey Cafferata Co-authored-by: ecraven Co-authored-by: Peter --- commands/types/dnscontrol.d.ts | 32 ++++++++++++++++- .../advanced-features/nameservers.md | 25 +++++++++++++- .../top-level-functions/D.md | 34 ++++++++++++++++++- 3 files changed, 88 insertions(+), 3 deletions(-) diff --git a/commands/types/dnscontrol.d.ts b/commands/types/dnscontrol.d.ts index 9c858a497..ddc0e07c7 100644 --- a/commands/types/dnscontrol.d.ts +++ b/commands/types/dnscontrol.d.ts @@ -726,7 +726,8 @@ declare function CNAME(name: string, target: string, ...modifiers: RecordModifie * * ```javascript * // simple domain - * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * D("example.com", REG_MY_PROVIDER, + * DnsProvider(DSP_MY_PROVIDER), * A("@","1.2.3.4"), // "@" means the apex domain. In this case, "example.com" itself. * CNAME("test", "foo.example2.com."), * ); @@ -752,6 +753,35 @@ declare function CNAME(name: string, target: string, ...modifiers: RecordModifie * In other words, if you want to put a DNS record at the apex of a domain, use an `"@"` for the label, not an empty string (`""`). * In the above example, `example.com` has an `A` record with the value `"1.2.3.4"` at the apex of the domain. * + * # `no_ns` + * + * To prevent DNSControl from accidentally deleting your nameservers (at the + * parent domain), registrar updates are disabled if the list of nameservers for a + * zone (as computed from `dnsconfig.js`) is empty. + * + * This can happen when a provider doesn't give any control over the apex NS + * records, there are no default nameservers, there are no `NAMESERVER()` + * statements, and the provider returns an empty list of nameservers (such as + * Gandi and Vercel). + * + * In this situation, you will see an error message such as: + * + * ``` + * Skipping registrar REGISTRAR: No nameservers declared for domain "example.com". Add {no_ns:'true'} to force + * ``` + * + * To add this, add the meta data to the zone immediately following the registrar. + * + * ```javascript + * D("example.com", REG_MY_PROVIDER, {no_ns:'true'}, + * ... + * ... + * ... + * ); + * ``` + * + * Note that the value `true` is a string. + * * # Split Horizon DNS * * DNSControl supports Split Horizon DNS. Simply diff --git a/documentation/advanced-features/nameservers.md b/documentation/advanced-features/nameservers.md index b5a760995..b71fa64af 100644 --- a/documentation/advanced-features/nameservers.md +++ b/documentation/advanced-features/nameservers.md @@ -69,7 +69,6 @@ D("example.com", REG_NAMECOM, ``` {% endcode %} - ## Registrar is elsewhere Purpose: @@ -91,6 +90,30 @@ D("example.com", REG_NONE, ``` {% endcode %} +## Domain is "nowhere" + +Suppose you don't want to manage a domain, but you want to list the zone in +your `dnsconfig.js` file for inventory purposes. For example, suppose there are +domains that some other part of your company maintains, but you want to list it +in your `dnsconfig.js` because it is authoratative for the company. + +```javascript +var REG_NONE = NewRegistrar("none"); + +function INVENTORY_ONLY(name) { + D(name, REG_NONE, { no_ns: "true" }); +} + +INVENTORY_ONLY('example.com"); +INVENTORY_ONLY('example2.com"); +INVENTORY_ONLY('example.net"); +``` + +Now you can produce a list of your zones like this: + +```shell +dnscontrol print-ir | jq -r '.domains[].name' +``` ## Zone is elsewhere diff --git a/documentation/language-reference/top-level-functions/D.md b/documentation/language-reference/top-level-functions/D.md index 637b0d417..02169ba38 100644 --- a/documentation/language-reference/top-level-functions/D.md +++ b/documentation/language-reference/top-level-functions/D.md @@ -24,7 +24,8 @@ Modifier arguments are processed according to type as follows: {% code title="dnsconfig.js" %} ```javascript // simple domain -D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), +D("example.com", REG_MY_PROVIDER, + DnsProvider(DSP_MY_PROVIDER), A("@","1.2.3.4"), // "@" means the apex domain. In this case, "example.com" itself. CNAME("test", "foo.example2.com."), ); @@ -53,6 +54,37 @@ In other words, if you want to put a DNS record at the apex of a domain, use an In the above example, `example.com` has an `A` record with the value `"1.2.3.4"` at the apex of the domain. {% endhint %} +# `no_ns` + +To prevent DNSControl from accidentally deleting your nameservers (at the +parent domain), registrar updates are disabled if the list of nameservers for a +zone (as computed from `dnsconfig.js`) is empty. + +This can happen when a provider doesn't give any control over the apex NS +records, there are no default nameservers, there are no `NAMESERVER()` +statements, and the provider returns an empty list of nameservers (such as +Gandi and Vercel). + +In this situation, you will see an error message such as: + +``` +Skipping registrar REGISTRAR: No nameservers declared for domain "example.com". Add {no_ns:'true'} to force +``` + +To add this, add the meta data to the zone immediately following the registrar. + +```javascript +D("example.com", REG_MY_PROVIDER, {no_ns:'true'}, + ... + ... + ... +); +``` + +{% hint style="info" %} +**NOTE**: The value `true` of `no_ns` is a string. +{% endhint %} + # Split Horizon DNS DNSControl supports Split Horizon DNS. Simply