From 36a05608e03df6d8bfab727726095b15abd4ce13 Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Wed, 29 Jan 2020 13:47:32 -0500 Subject: [PATCH] DOCS: Explain nameservers vs ns (#608) --- docs/_functions/domain/DnsProvider.md | 4 ++ docs/_functions/domain/NAMESERVER.md | 58 ++++++++++++++++++++++++ docs/_functions/domain/NS.md | 5 +- docs/_functions/global/NewDnsProvider.md | 6 +-- pkg/nameservers/nameservers.go | 2 +- 5 files changed, 70 insertions(+), 5 deletions(-) diff --git a/docs/_functions/domain/DnsProvider.md b/docs/_functions/domain/DnsProvider.md index 9c0c8bde6..0a28949ab 100644 --- a/docs/_functions/domain/DnsProvider.md +++ b/docs/_functions/domain/DnsProvider.md @@ -19,3 +19,7 @@ but limit it to this many. See [this page]({{site.github.url}}/nameservers) for a detailed explanation of how DNSControl handles nameservers and NS records. +If a domain (`D()`) does not include any `DnsProvider()` functions, +the DNS records will not be modified. In fact, if you want to control +the Registrar for a domain but not the DNS records themselves, simply +do not include a `DnsProvider()` function for that `D()`. diff --git a/docs/_functions/domain/NAMESERVER.md b/docs/_functions/domain/NAMESERVER.md index 975b7fdc7..a887faf5d 100644 --- a/docs/_functions/domain/NAMESERVER.md +++ b/docs/_functions/domain/NAMESERVER.md @@ -25,3 +25,61 @@ D("example.com", REGISTRAR, .... , {%endhighlight%} {% include endExample.html %} + + +# The difference between NS() and NAMESERVER() + +Nameservers are one of the least +understood parts of DNS, so a little extra explanation is required. + +* `NS()` lets you add an NS record to a zone, just like A() adds an A + record to the zone. + +* The `NAMESERVER()` directive adds an NS record to the parent zone. + +Since the parent zone could be completely unrelated to the current +zone, changes made by `NAMESERVER()` have to be done by an API call to +the registrar, who then figures out what to do. For example, if I +change the `NAMESERVER()` for stackoverflow.com, DNSControl talks to +the registrar who does the hard work of talking to the people that +control `.com`. If the domain was gmeet.io, the registrar does +the right thing to talk to the people that control `.io`. + +(Maybe it should have been called `PARENTNAMESERVER()` but we didn't +think of that at the time.) + +When you use `NAMESERVER()`, DNSControl takes care of adding the +appropriate `NS` records to the zone. + +Therefore, you don't have to specify `NS()` records except when +delegating a subdomain, in which case you are acting like a registrar! + +Many DNS Providers will handle all of this for you, pick the name of +the nameservers for you and updating them (upward and in your zone) +automatically. For more information, refer to +[this page]({{site.github.url}}/nameservers). + + +That's why NAMESERVER() is a separate operator. + + +# How to not change the parent NS records? + +If dnsconfig.js has zero `NAMESERVER()` commands for a domain, it will +use the API to remove all the nameservers. + +If dnsconfig.js has 1 or more `NAMESERVER()` commands for a domain, it +will use the API to set those as the nameservers (unless, of course, +they're already correct). + +So how do you tell DNSControl not to make any changes? Use the +special Registrar called "NONE". It makes no changes. + +It looks like this: + +``` +var REG_THIRDPARTY = NewRegistrar('ThirdParty', 'NONE') +D("mydomain.com", REG_THIRDPARTY, + ... +) +``` diff --git a/docs/_functions/domain/NS.md b/docs/_functions/domain/NS.md index 5187ab062..bb804ec99 100644 --- a/docs/_functions/domain/NS.md +++ b/docs/_functions/domain/NS.md @@ -7,7 +7,10 @@ parameters: --- NS adds a NS record to the domain. The name should be the relative label for the domain. -Use `@` for the domain apex, though if you are doing this consider using NAMESERVER() instead. + +The name may not be `@` (the bare domain), as that is controlled via `NAMESERVER()`. +The difference between `NS()` and `NAMESERVER()` is explained in the `NAMESERVER()` description. + Target should be a string representing the NS target. If it is a single label we will assume it is a relative name on the current domain. If it contains *any* dots, it should be a fully qualified domain name, ending with a `.`. diff --git a/docs/_functions/global/NewDnsProvider.md b/docs/_functions/global/NewDnsProvider.md index 01daad2c6..b16825fbe 100644 --- a/docs/_functions/global/NewDnsProvider.md +++ b/docs/_functions/global/NewDnsProvider.md @@ -17,8 +17,8 @@ This function will return the name as a string so that you may assign it to a va {% include startExample.html %} {% highlight js %} var REGISTRAR = NewRegistrar("name.com", "NAMEDOTCOM"); -var r53 = NewDnsProvider("R53","ROUTE53"); +var R53 = NewDnsProvider("r53", "ROUTE53"); -D("example.com", REGISTRAR, DnsProvider(r53), A("@","1.2.3.4")); +D("example.com", REGISTRAR, DnsProvider(R53), A("@","1.2.3.4")); {%endhighlight%} -{% include endExample.html %} \ No newline at end of file +{% include endExample.html %} diff --git a/pkg/nameservers/nameservers.go b/pkg/nameservers/nameservers.go index 2f82d633c..3bc26e63c 100644 --- a/pkg/nameservers/nameservers.go +++ b/pkg/nameservers/nameservers.go @@ -48,7 +48,7 @@ func AddNSRecords(dc *models.DomainConfig) { if ttls, ok := dc.Metadata["ns_ttl"]; ok { t, err := strconv.ParseUint(ttls, 10, 32) if err != nil { - fmt.Printf("WARNING: ns_ttl fpr %s (%s) is not a valid int", dc.Name, ttls) + fmt.Printf("WARNING: ns_ttl for %s (%s) is not a valid int", dc.Name, ttls) } else { ttl = uint32(t) }