DOCS: Fix formatting/rewrite docs/nameservers.md (#1391)

docs/nameservers.md

@@ -5,28 +5,29 @@ title: Nameservers
 
 # Nameservers
 
-DNSControl can handle a variety of provider scenarios for you.
+{% highlight javascript %}
+{% endhighlight %}
 
-- The same provider is the registrar and DNS server
+DNSControl can handle a variety of provider scenarios. The registrar and DNS
-- Different providers for the registrar and DNS server
+provider can be the same company, different company, they can even be unknown!
-- A registrar plus multiple DNS servers
+The document shows examples of many common and uncommon configurations.
-- Additional "shadow" DNS servers (non-authoratative DNS servers,
-  often used as backups or as a local cache)
 
-# Examples:
+* TOC
+{:toc}
 
-{% include startExample.html %}
+## Constants
-{% highlight js %}
 
+All the examples use the variables.  Substitute your own.
+
+{% highlight javascript %}
 // ========== Registrars:
 
-// A normal registrar.
+// A typical 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
+// The "NONE" registrar is a "fake" registrar.
-// nameservers are for a domain, or if you use a registrar that doesn't
+// This is useful if the registrar is not supported by DNSControl,
-// offer an API, or if the registrar's API is not implemented in
+// or if you don't want to control the domain's delegation.
-// DNSControl.
 var REG_THIRDPARTY = NewRegistrar("ThirdParty", "NONE");
 
 // ========== DNS Providers:
@@ -36,137 +37,209 @@ 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");
+{% endhighlight %}
 
-// ========== Domains:
+## Same provider for REG and DNS
 
-// ========== Same provider for REG and DNS.
+Purpose:
+Use the same provider as a registrar and DNS service.
 
-// Keep it simple: Use the same provider as a registrar and DNS service.
+Why?
-// Why? Simplicity.
+Simplicity.
+
+{% highlight javascript %}
 D("example1.com", REG_NAMECOM,
   DnsProvider(DNS_NAMECOM),
   A("@", "10.2.3.4")
 );
+{% endhighlight %}
 
-// ========== Different provider for REG and DNS.
+## Different provider for REG and DNS
 
-// "Separate DNS server": Use one provider as registrar, a different for DNS service.
+Purpose:
-// Why? Use any registrar but a preferred DNS provider.
+Use one provider as registrar, a different for DNS service.
-// This is the most common situation.
+
+Why?
+Some registrars do not provide DNS server, or their service is sub-standard and
+you want to use a high-performance DNS server.
+
+
+{% highlight javascript %}
 D("example1.com", REG_NAMECOM,
   DnsProvider(DNS_AWS),
   A("@", "10.2.3.4")
 );
+{% endhighlight %}
 
-// ========== Registrar is elsewhere.
+## Registrar is elsewhere
 
-// "DNS only": Let someone else manage the NS records for a dommain.
+Purpose:
-// Why? Because you don't have access to the registrar, or the registrar is not
+This is a "DNS only" configuration.  Use it when you don't control the
-// supported by DNSControl. However you do have API access for
+registrar but you do control the DNS records.
-// updating the zone's records (most likely at a different provider).
+
+Why?
+You don't have access to the registrar, or the registrar is not
+supported by DNSControl. However you do have API access for
+updating the zone's records (most likely at a different provider).
+
+{% highlight javascript %}
 D("example1.com", REG_THIRDPARTY,
   DnsProvider(DNS_NAMECOM),
   A("@", "10.2.3.4")
 );
+{% endhighlight %}
 
-// ========== Zone is elsewhere.
+## Zone is elsewhere
 
-// "Registrar only": Direct the registrar to point to some other DNS provider.
+Purpose:
-// Why? In this example we're pointing the domain to the nsone.net DNS
+This is a "Registar only" configuration.  Use it when you control the registar but want to delegate the zone to someone else.
-// service, which someone else is controlling.
+
+Why?
+We are delegating the domain to someone else. In this example we're
+pointing the domain to the nsone.net DNS service, which someone else is
+controlling.
+
+{% highlight javascript %}
 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."),
 );
+{% endhighlight %}
 
-// ========== Override nameservers.
+## Override nameservers
 
-// "Custom nameservers": Ignore the provider's default nameservers and substitute our own.
+Purpose:
-// Why? Rarely used unless the DNS provider's API does not support
+Ignore the provider's default nameservers and substitute our own.
-// querying what the nameservers are, or the API is returning invalid
+
-// data, or if during initial setup the API returns no information.
+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 the API returns no
+information.  Sometimes APIs return no (useful) information when the domain
+is new; this is a good temporary work-around until the API starts working.
+
+{% highlight javascript %}
 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)
+  DnsProvider(DNS_CLOUDFLARE, 0),  // Set the DNS provider but ignore the nameservers it suggests (0 == take none of the names it reports)
   NAMESERVER("kim.ns.cloudflare.com."),
   NAMESERVER("walt.ns.cloudflare.com."),
   A("@", "10.2.3.4")
 );
+{% endhighlight %}
 
-// ========== Add nameservers.
+## Add nameservers
 
-// "Add additional nameservers." Use the default nameservers from the registrar but add additional ones.
+Purpose:
-// Why? Usually only to correct a bug or misconfiguration elsewhere.
+Use the default nameservers from the registrar but add additional ones.
+
+Why?
+Usually only to correct a bug or misconfiguration elsewhere.
+
+{% highlight javascript %}
 D("example1.com", REG_NAMECOM,
   DnsProvider(DNS_NAMECOM),
   NAMESERVER("ns1.myexample.tld"),
   A("@", "10.2.3.4")
 );
+{% endhighlight %}
 
-// ========== Shadow nameservers.
+## Shadow nameservers
 
-// "Shadow DNS servers."  Secretly send your DNS records to another server.
+Purpose:
-// Why? Many possibilities:
+Secretly publish your DNS zone records to another server.
-/  * 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.
+Why?
-/  * You are sending the zone to a local caching DNS server.
+There are many reasons to do this:
+
+* 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.
+
+{% highlight javascript %}
 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")
 );
+{% endhighlight %}
 
-// ========== Backup your zone.
+## Backup your zone
 
-// "Zonefile backups." Make backups of the exact DNS records in zone-file format.
+Purpose:
-// Why? In addition to the usual configuration, write out a BIND-style
+Make backups of DNS records in a zone.  This generates a zonefile listing all
-// zonefile perhaps for debugging, historical, or auditing purposes.
+the records in the zone.
-// NOTE: This won't work if you use pseudo rtypes that BIND doesn't support.
+
+Why?
+You want to write out a BIND-style zonefile for debugging, historical, or
+auditing purposes. Some sites do backups of these zonefiles to create a history
+of changes. This is different than keeping a history of `dnsconfig.js` because
+this is the output of DNSControl, not the input.
+
+NOTE: This won't work if you use pseudo rtypes that BIND doesn't support.
+
+{% highlight javascript %}
 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")
 );
+{% endhighlight %}
 
-// ========== Dual DNS Providers.
+## Dual DNS Providers
 
-// "Dual DNS Providers": Use two different DNS services:
+Purpose:
-// Why? Diversity. If one DNS provider goes down, the other will be used.
+Use two different DNS services:
-// Little known fact: Most DNS recursive resolvers monitor which DNS
+
-// servers are performing the best and automatically start avoiding
+Why?
-// the slow or down servers. This means that if you use this technique
+Diversity. If one DNS provider goes down, the other will be used.
-// 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
+Little known fact: Most DNS recursive resolvers monitor which DNS
-// properly.
+servers are performing the best and automatically start avoiding
-// More info: https://www.dns-oarc.net/files/workshop-201203/OARC-workshop-London-2012-NS-selection.pdf
+servers that are slow or down. This means that if you use this technique
-// NOTE: This is overkill unless you have millions of users and strict up-time requirements.
+and one DNS provider goes down, 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.
+
+{% highlight javascript %}
 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 %}
 
-// ========== Fancy macros
+# Helper macros
 
-// There are some built-in macros that you might find useful.
+DNSControl has some built-in macros that you might find useful.
 
-// DOMAIN_ELSEWHERE: This macro points the domain's delegation
+## `DOMAIN_ELSEWHERE`
-// (nameservers) to a list of DNS servers.
+
+Easily delegate a domain to a specific list of nameservers.
+
+{% highlight javascript %}
 DOMAIN_ELSEWHERE("example1.com", REG_NAMECOM, [
     "dns1.example.net.",
     "dns2.example.net.",
     "dns3.example.net.",
 ]);
+{% endhighlight %}
 
-// DOMAIN_ELSEWHERE_AUTO: Similar to DOMAIN_ELSEWHERE but the list
+## `DOMAIN_ELSEWHERE_AUTO`
-// of nameservers is queried from the API of a DNS provider.
+
+Easily delegate a domain to a nameservers via an API query.
+
+This is similar to `DOMAIN_ELSEWHERE` but the list
+of nameservers is queried from the API of a single DNS provider.
+
+{% highlight javascript %}
 DOMAIN_ELSEWHERE_AUTO("example1.com", REG_NAMECOM, DNS_AWS);
 DOMAIN_ELSEWHERE_AUTO("example2.com", REG_NAMECOM, DNS_GOOGLE);
+{% endhighlight %}
 
-{%endhighlight%}
+# Warning!
-{% include endExample.html %}
-
 
 {% 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." %}