get-zones should comment out NAMESERVER() (#743)

* get-zones should comment out NAMESERVER()

* Edits

commands/getZones.go

@@ -275,8 +275,10 @@ func formatDsl(zonename string, rec *models.RecordConfig, defaultTTL uint32) str
 		// TODO(tlim): If this is an SPF record, generate a SPF_BUILDER().
 	case "NS":
 		// NS records at the apex should be NAMESERVER() records.
+		// DnsControl uses the API to get this info. NAMESERVER() is just
+		// to override that when needed.
 		if rec.Name == "@" {
-			return fmt.Sprintf("NAMESERVER('%s')", target)
+			return fmt.Sprintf("//NAMESERVER('%s')", target)
 		}
 		target = "'" + target + "'"
 	case "R53_ALIAS":

commands/test_data/example.org.zone.js

@@ -4,10 +4,10 @@ D("example.org", REG_CHANGEME,
 	DnsProvider(bind),
 	DefaultTTL(7200),
 	//SOA('@', 'ns1.example.org.', 'hostmaster.example.org.', 2020030700, 7200, 3600, 864000, 7200, TTL(43200)),
-	NAMESERVER('ns1.example.org.'),
-	NAMESERVER('ns2.example.org.'),
-	NAMESERVER('ns-a.example.net.'),
-	NAMESERVER('friend-dns.example.com.'),
+	//NAMESERVER('ns1.example.org.'),
+	//NAMESERVER('ns2.example.org.'),
+	//NAMESERVER('ns-a.example.net.'),
+	//NAMESERVER('friend-dns.example.com.'),
 	MX('@', 10, 'mx.example.org.'),
 	TXT('@', 'v=spf1 ip4:192.0.2.25 ip6:2001:db8::1:25 mx include:_spf.example.com ~all'),
 	SRV('_client._smtp', 1, 1, 1, 'example.org.'),

commands/test_data/simple.com.zone.js

@@ -3,10 +3,10 @@ var REG_CHANGEME = NewRegistrar("ThirdParty", "NONE");
 D("simple.com", REG_CHANGEME,
 	DnsProvider(bind),
 	//SOA('@', 'ns3.serverfault.com.', 'sysadmin.stackoverflow.com.', 2020022300, 3600, 600, 604800, 1440),
-	NAMESERVER('ns-1313.awsdns-36.org.'),
-	NAMESERVER('ns-736.awsdns-28.net.'),
-	NAMESERVER('ns-cloud-c1.googledomains.com.'),
-	NAMESERVER('ns-cloud-c2.googledomains.com.'),
+	//NAMESERVER('ns-1313.awsdns-36.org.'),
+	//NAMESERVER('ns-736.awsdns-28.net.'),
+	//NAMESERVER('ns-cloud-c1.googledomains.com.'),
+	//NAMESERVER('ns-cloud-c2.googledomains.com.'),
 	MX('@', 1, 'aspmx.l.google.com.'),
 	MX('@', 5, 'alt1.aspmx.l.google.com.'),
 	MX('@', 5, 'alt2.aspmx.l.google.com.'),

docs/_providers/bind.md

@@ -69,7 +69,7 @@ When DNSControl reads a BIND zonefile:
 * When generating a new zonefile, the SOA serial number is
   updated.
 
-DNSControl ties to maintain the serial number as yyyymmddvv. If the
+DNSControl tries to maintain the serial number as yyyymmddvv. If the
 existing serial number is significantly higher it will simply
 increment the value by 1.
 

docs/check-creds.md

@@ -23,13 +23,11 @@ ARGUMENTS:
    provider: The name of the provider (second parameter to NewDnsProvider() in dnsconfig.js)
 
 EXAMPLES:
-   dnscontrol get-zones myr53 ROUTE53
+   dnscontrol check-creds myr53 ROUTE53
+
+This command is the same as:
    dnscontrol get-zones --out=/dev/null myr53 ROUTE53
 
-# Example commands
-
-dnscontrol get-zone
-
 # Developer Note
 
 This command is not implemented for all providers.

docs/get-zones.md

@@ -9,12 +9,51 @@ DNSControl has a stand-alone utility that will contact a provider,
 download the records of one or more zones, and output them to a file
 in a variety of formats.
 
-The original purpose of this command is to help convert legacy domains
-to DNScontrol (bootstrapping).  Since bootstrapping can not depend on
-`dnsconfig.js`, `get-zones` relies on command line parameters and
-`creds.json` exclusively.
+`get-zones` relies on command line parameters and `creds.json`
+exclusively.  It does not use `dnsconfig.js`. This is to assist
+bootstrapping a new system.
 
-Syntax:
+## Use case 1: Bootstrapping a new system
+
+If you are moving a DNS zone from a provider to DNSControl, this
+command will do most of the work for you by downloading the records
+and writing them out in `dnsconfig.js`-format. It is intended to be
+"a decent first draft", only requiring minimal editing.
+
+Use `--format=djs` or `--format=js` (djs is recommended).
+
+Minor editing is required. Not all record formats are supported.
+SOA records are commented out, since most providers do not support it.
+BIND supports it, but requires the data to be entered as meta data.
+
+The `NAMESERVER()` command is generated commented out. This is usually
+not needed as DNSControl can get more accurate information via the
+API. Remove the comments only to override the DNS service provider.
+
+## Use case 2: Generating BIND ZONE files
+
+The `--format=zone` generates BIND-style Zonefiles. Pseudo records not
+supported by BIND are generated as comments.
+
+This format is useful when moving zonedata between providers, since
+the format is relatively universal.
+
+This format is also useful for generating backups of DNS zones. Unlike
+making a backup of the `dnsconfig.js`, this is the raw records, which
+may be useful.
+
+## Use case 3: TAB separated values
+
+The goal of `--format=tsv` is to provide a high-fidelity format that is easy
+enough to parse with `awk`.
+
+## Use case 4: List zones
+
+If a provider supports it, `--format=nameonly` lists the names of the
+zones at the provider.
+
+
+## Syntax
 
    dnscontrol get-zones [command options] credkey provider zone [...]
 
@@ -44,7 +83,8 @@ The columns in --format=tsv are:
 
 The --ttl flag only applies to zone/js/djs formats.
 
-EXAMPLES:
+## Examples
+
    dnscontrol get-zones myr53 ROUTE53 example.com
    dnscontrol get-zones gmain GANDI_V5 example.comn other.com
    dnscontrol get-zones cfmain CLOUDFLAREAPI all
@@ -54,11 +94,10 @@ EXAMPLES:
 Read a zonefile, generate a JS file, then use the JS file to see how
 different it is from the zonefile:
 
-   dnscontrol get-zone --format=js -out=foo.djs bind BIND example.org 
+   dnscontrol get-zone --format=djs -out=foo.djs bind BIND example.org 
    dnscontrol preview --config foo.js
 
-
-# Developer Note
+# Developer Notes
 
 This command is not implemented for all providers.
 
@@ -88,12 +127,12 @@ and return them as a list of RecordConfig structs.
 
 The code to do that already exists in `GetDomainCorrections`.
 You should extract it into its own function (`GetZoneRecords`), rather
-than having it be burried in the middle of `GetDomainCorrections`.
+than having it be buried in the middle of `GetDomainCorrections`.
 `GetDomainCorrections` should call `GetZoneRecords`.
 
 Once that is done the `get-zone` subcommand should work.
 
-**Step 4. Optionally implemement the `ListZones` function**
+**Step 4. Optionally implement the `ListZones` function**
 
 If the `ListZones` function is implemented, the "all" special case
 will be activated.  In this case, listing a single zone named `all`