DOCS: Better document nameserver scenarios (#868)

docs/_functions/domain/NAMESERVER.md

@@ -12,13 +12,23 @@ This takes exactly one argument: the name of the nameserver. It must end with
 a "." if it is a FQDN, just like all targets.
 
 This is different than the `NS()` function, which inserts NS records
-in the current zone and accepts a label. It is useful for downward
-delegations. This is for informing upstream delegations.
+in the current zone and accepts a label. `NS()` is useful for downward
+delegations. `NAMESERVER()` is for informing upstream delegations.
+
+For more information, refer to [this page]({{site.github.url}}/nameservers).
 
 {% include startExample.html %}
 {% highlight js %}
 
 D("example.com", REGISTRAR, .... ,
+  DnsProvider(route53, 0),
+  // Replace the nameservers:
+  NAMESERVER("ns1.myserver.com."),
+  NAMESERVER("ns2.myserver.com."),
+);
+
+D("example2.com", REGISTRAR, .... ,
+  // Add these two additional nameservers to the existing list of nameservers.
   NAMESERVER("ns1.myserver.com."),
   NAMESERVER("ns2.myserver.com."),
 );
@@ -33,46 +43,38 @@ 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.
+  record to the zone. This is generally used to delegate a subzone.
 
-* The `NAMESERVER()` directive adds an NS record to the parent zone.
+* The `NAMESERVER()` directive speaks to the Registrar about how the parent should delegate the 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
+use `NAMESERVER()` in the zone `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
+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
+(A better name might have been `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.
-
+Each registrar handles delegations differently.  Most use
+the `NAMESERVER()` targets to update the delegation, adding
+`NS` records to the parent zone as required.
+Some providers restrict the names to hosts they control.
+Others may require you to add the `NS` records to the parent domain
+manually.
 
 # 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.
+use the API to remove all non-default 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).
+will use the API to add those nameservers (unless, of course,
+they already exist).
 
-So how do you tell DNSControl not to make any changes?  Use the
+So how do you tell DNSControl not to make any changes at all?  Use the
 special Registrar called "NONE". It makes no changes.
 
 It looks like this:

docs/nameservers.md

@@ -5,55 +5,124 @@ title: Nameservers
 
 # Nameservers
 
-DNSControl can handle a variety of provider scenarios for you:
+DNSControl can handle a variety of provider scenarios for you.
 
-- A single provider manages everything for your domains (Ex: name.com registers and serves dns)
-- A single provider serves dns separately from the registrar (Ex: NAME.COM registers and Cloudflare hosts dns records)
-- Multiple providers "co-host" dns (Ex: Route53 and Google Cloud DNS both serve as authoritative nameservers)
-- One or more "active" dns hosts and another "backup" dns host. (Ex: route53 hosts dns, but I update a local bind server as a backup)
+- The same provider is the registrar and DNS server
+- Different providers for the registrar and DNS server
+- A registrar plus multiple DNS servers
+- Additional "shadow" DNS servers (non-authoratative DNS servers,
+  often used as backups or as a local cache)
 
-All of these scenarios differ in how they manage:
+# Examples:
 
-- The root list of authoritative nameservers stored in the TLD zone by your registrar.
-- The list of NS records for the base domain that is served by each dns host.
+{% include startExample.html %}
+{% highlight js %}
 
-DNSControl attempts to manage these records for you as much as possible, according the the following processes:
+// ========== Registrars:
 
-## 1. Specifying Nameservers
+// A normal registrar.
+var REG_NAMECOM = NewRegistrar("namedotcom_main", "NAMEDOTCOM");
+// The "NONE" registrar is a "fake" registrar that makes no changes.
+// This is useful if you don't want DNSControl to control who the
+// nameservers are for a domain, or if you use a registrar that doesn't
+// offer an API, or if the registrar's API is not implemented in
+// DNSControl.
+var REG_THIRDPARTY = NewRegistrar("ThirdParty", "NONE");
 
-There are several different ways to declare nameservers for a zone:
+// ========== DNS Providers:
 
-1. Explicit [`NAMESERVER`](/js#NAMESERVER) records in a domain:
+var DNS_NAMECOM = NewDnsProvider("namedotcom_main", "NAMEDOTCOM");
+var DNS_AWS = NewDnsProvider("aws_main", "ROUTE53");
+var DNS_GOOGLE = NewDnsProvider("gcp_main", "GCLOUD");
+var DNS_CLOUDFLARE = NewDnsProvider("cloudflare_main", "CLOUDFLAREAPI");
+var DNS_BIND = NewDnsProvider("bind", "BIND");
 
-    `NAMESERVER("ns1.myhost.tld")`
-2. Request all nameservers to use from a provider (usually via api):
+// ========== Domains:
 
-    `DnsProvider(route53)`
-3. Request a limited number of nameservers from a provider:
+// "Keep it simple": Use the same provider as a registrar and DNS service.
+// Why? Simplicity.
+D("example1.com", REG_NAMECOM,
+  DnsProvider(DNS_NAMECOM),
+  A("@", "10.2.3.4")
+);
 
-    `DnsProvider(route53, 2), DnsProvider(gcloud, 2)`
+// "Separate DNS server": Use one provider as registrar, a different for DNS service.
+// Why? Use any registrar but a preferred DNS provider.
+// This is the most common situation.
+D("example1.com", REG_NAMECOM,
+  DnsProvider(DNS_AWS),
+  A("@", "10.2.3.4")
+);
 
-    This can be useful to limit the total number of NS records when using multiple providers together, for performance reasons.
+// "Registrar only": Direct the registrar to point to some other DNS provider.
+// Why? In this example we're pointing the domain to the nsone.net DNS
+// service, which someone else is controlling.
+D("example1.com", REG_NAMECOM,
+  NAMESERVER("dns1.p03.nsone.net."),
+  NAMESERVER("dns2.p03.nsone.net."),
+  NAMESERVER("dns3.p03.nsone.net."),
+  NAMESERVER("dns4.p03.nsone.net."),
+);
 
-## 2. DNSControl processes
+// "Custom nameservers": Ignore the provider's default nameservers and substitute our own.
+// Why? Rarely used unless the DNS provider's API does not support
+// querying what the nameservers are, or the API is returning invalid
+// data, or if during initial setup the API returns no information.
+D("example1.com", REG_NAMECOM,
+  DnsProvider(DNS_CLOUDFLARE, 0),  // Set the DNS provider but ignore the nameservers it suggests (0 == take zero of the names it reports)
+  NAMESERVER("kim.ns.cloudflare.com."),
+  NAMESERVER("walt.ns.cloudflare.com."),
+  A("@", "10.2.3.4")
+);
 
-The first step in running a domain is a first pass to collect all nameservers that we should use.
-DNSControl collects all explicit nameservers, and calls the method on each provider to get nameservers to use.
-After this process we have a list of "Authoritative Nameservers" for the domain.
+// "Add additional nameservers." Use the default nameservers from the registrar but add additional ones.
+// Why? Usually only to correct a bug or misconfiguration elsewhere.
+D("example1.com", REG_NAMECOM,
+  DnsProvider(DNS_NAMECOM),
+  NAMESERVER("ns1.myexample.tld"),
+  A("@", "10.2.3.4")
+);
+
+// "Shadow DNS servers."  Secretly send your DNS records to another server.
+// Why? Many possibilities:
+/  * You are preparing to move to a different DNS provider and want to test it before you cut over.
+/  * You want your DNS records stored somewhere else in case you have to switch over in an emergency.
+/  * You are sending the zone to a local caching DNS server.
+D("example1.com", REG_NAMECOM,
+  DnsProvider(DNS_NAMECOM), // Our real DNS server
+  DnsProvider(DNS_CLOUDFLARE, 0), // Quietly send a copy of the zone here.
+  DnsProvider(DNS_BIND, 0), // And here too!
+  A("@", "10.2.3.4")
+);
+
+// "Zonefile backups." Make backups of the exact DNS records in zone-file format.
+// Why? In addition to the usual configuration, write out a BIND-style
+// zonefile perhaps for debugging, historical, or auditing purposes.
+// NOTE: This won't work if you use pseudo rtypes that BIND doesn't support.
+D("example1.com", REG_NAMECOM,
+  DnsProvider(DNS_NAMECOM),
+  DnsProvider(DNS_BIND, 0), // Don't activate any nameservers related to BIND.
+  A("@", "10.2.3.4")
+);
+
+// "Dual DNS Providers": Use two different DNS services:
+// Why? Diversity. If one DNS provider goes down, the other will be used.
+// Little known fact: Most DNS recursive resolvers monitor which DNS
+// servers are performing the best and automatically start avoiding
+// the slow or down servers. This means that if you use this technique
+// and one DNS provider goes down (like the famous Dyn outage), after a
+// while your users won't be affected.  Not all software does this
+// properly.
+// More info: https://www.dns-oarc.net/files/workshop-201203/OARC-workshop-London-2012-NS-selection.pdf
+// NOTE: This is overkill unless you have millions of users and strict up-time requirements.
+D("example1.com", REG_NAMECOM,
+  DnsProvider(DNS_AWS, 2),  // Take 2 nameservers from AWS
+  DnsProvider(DNS_GOOGLE, 2),  // Take 2 nameservers from GCP
+  A("@", "10.2.3.4")
+);
+
+{%endhighlight%}
+{% include endExample.html %}
 
-As much as possible, all dns servers should agree on this nameserver list, and serve identical NS records. DNSControl will generate
-NS records for the authoritative nameserver list and automatically add them to the domain's records.
-NS records for the base domain should not be specified manually, as that will result in an error.
 
 {% include alert.html text="Note: Not all providers allow full control over the NS records of your zone. It is not recommended to use these providers in complicated scenarios such as hosting across multiple providers. See individual provider docs for more info." %}
-
-DNSControl will also register the authoritative nameserver list with the registrar, so that all nameserver are used in the TLD registry.
-
-## 3. Backup providers
-
-It is also possible to specify a DNS Provider that is not "authoritative" by using `DnsProvider("name", 0)`. This means the provider will be updated
-with all records to match the authoritative ones, but it will not be registered in the tld name servers, and will not take traffic.
-Its nameservers will not be added to the authoritative set. While this may seem an attractive option, there are a few things to note:
-
-1. Backup nameservers will still be updated with the NS records from the authoritative nameserver list. This means the records will still need to be updated to correctly "activate" the provider.
-2. Costs generally scale with utilization, so there is often no real savings associated with an active-passive setup vs an active-active one anyway.