Document TXT, NS, NO_PURGE, PURGE, and IMPORT_TRANSFORM (#184)

* Document TXT, NS, NO_PURGE, PURGE, and IMPORT_TRANSFORM

docs/_functions/domain/IMPORT_TRANSFORM.md

@@ -0,0 +1,72 @@
+---
+name: IMPORT_TRANSFORM
+parameters:
+  - transform table
+  - domain
+  - ttl
+  - modifiers...
+---
+
+Don't use this feature. It was added for a very specific situation. Bugs
+and feature requests from outside that situation will be rejected.
+
+IMPORT_TRANSFORM adds to the domain all the records from another
+domain, after making certain transformations and resetting the TTL.
+
+Example:
+
+Suppose foo.com is a regular domain.  bar.com is a regular domain,
+but certain records should be the same as foo.com with these
+exceptions: "bar.com" is added to the name, the TTL is changed to
+300, if the IP address is between 1.2.3.10 and 1.2.3.20 then rewrite
+the IP address to be based on 123.123.123.100 (i.e. .113 or .114).
+
+You wouldn't want to maintain bar.com manually, would you?  It would
+be very error prone. Therefore instead you maintain foo.com and
+let IMPORT_TRANSFORM automatically generate bar.com.
+
+{% include startExample.html %}
+
+foo.com:
+    one.foo.com.    IN A 1.2.3.1
+    two.foo.com.    IN A 1.2.3.2
+    three.foo.com.  IN A 1.2.3.13
+    four.foo.com.   IN A 1.2.3.14
+
+bar.com:
+    www.bar.com.    IN 123.123.123.123
+    one.foo.com.bar.com.    IN A 1.2.3.1
+    two.foo.com.bar.com.    IN A 1.2.3.2
+    three.foo.com.bar.com.  IN A 123.123.123.113
+    four.foo.com.bar.com.   IN A 123.123.123.114
+
+{% include endExample.html %}
+
+Here's how you'd implement this in DNSControl:
+
+{% include startExample.html %}
+
+var TRANSFORM_INT = [
+    // RANGE_START, RANGE_END, NEW_BASE
+    { low: "1.2.3.10", high: "1.2.3.20", newBase: "123.123.123.100" },  //   .10 to .20 rewritten as 123.123.123.100+IP
+    { low: "2.4.6.80", high: "2.4.6.90", newBase: "123.123.123.200" },  //   Another rule, just to show that you can have many.
+]
+
+D("foo.com", .... , 
+  A("one","1.2.3.1")
+  A("two","1.2.3.2")
+  A("three","1.2.3.13")
+  A("four","1.2.3.14")
+);
+
+D("bar.com", .... , 
+  A("www","123.123.123.123")
+  IMPORT_TRANSFORM(TRANSFORM_INT, 'foo.com', 300),
+);
+
+{% include endExample.html %}
+
+Transform rules are: RANGE_START, RANGE_END, NEW_BASE.  NEW_BASE may be:
+
+* An IP address.  Rebase the IP address on this IP address. Extract the host part of the /24 and add it to the "new base" address.
+* A list of IP addresses. For each A record, inject an A record for each item in the list: `newBase: ['1.2.3.100', '2.4.6.8.100']` would produce 2 records for each A record.

docs/_functions/domain/NAMESERVER.md

@@ -0,0 +1,24 @@
+---
+name: NAMESERVER
+parameters:
+  - name
+  - ip
+  - modifiers...
+---
+
+NAMESERVER NS instructs DNSControl to inform the domain's registrar where to find this zone.
+For some registrars this will also add NS records to the zone itself.
+
+`ip` is optional, and is only required if glue records need to be generated in the parent zone.
+
+{% include startExample.html %}
+{% highlight js %}
+
+D("example.com", REGISTRAR, .... ,
+  NAMESERVER("ns1.myserver.com"),
+  NAMESERVER("ns2.example.com", "100.100.100.100"), // the server plus glue
+  A("www", "10.10.10.10"),
+);
+
+{%endhighlight%}
+{% include endExample.html %}

docs/_functions/domain/NO_PURGE.md

@@ -0,0 +1,41 @@
+---
+name: NO_PURGE
+---
+
+NO_PURGE indicates that records should not be deleted from a domain.
+Records will be added and updated, but not removed.
+
+NO_PURGE is generally used in very specific situations:
+
+* A domain is managed by some other system and DNSControl is only used to insert a few specific records and/or keep them updated. For example a DNS Zone that is managed by ActiveDirectory, but DNSControl is used to update a few, specific, DNS records. In this case we want to specify the DNS records we are concerned with but not delete all the other records.  This is a risky use of NO_PURGE since, if NO_PURGE was removed (or buggy) there is a chance you could delete all the other records in the zone, which could be a disaster. That said, domains with some records updated using Dynamic DNS have no other choice.
+* To work-around a pseudo record type that is not supported by DNSControl. For example some providers have a fake DNS record type called "URL" which creates a redirect. DNSControl normally deletes these records because it doesn't understand them. NO_PURGE will leave those records alone.
+
+In this example DNSControl will insert "foo.example.com" into the
+zone, but otherwise leave the zone alone.  Changes to "foo"'s IP
+address will update the record. Removing the A("foo", ...) record
+from dnscontrol will leave the record in place.
+
+{% include startExample.html %}
+{% highlight js %}
+D("example.com", .... , NO_PURGE,
+  A("foo","1.2.3.4")
+);
+{%endhighlight%}
+{% include endExample.html %}
+
+The main caveat of NO_PURGE is that intentionally deleting records
+becomes more difficult. Suppose a NO_PURGE zone has an record such
+as A("ken", "1.2.3.4"). Removing the record from dnsconfig.js will
+not delete "ken" from the domain. DNSControl has no way of knowing
+the record was deleted from the file  The DNS record must be removed
+manually.  Users of NO_PURGE are prone to finding themselves with
+an accumulation of orphaned DNS records. That's easy to fix for a
+small zone but can be a big mess for large zones.
+
+Not all providers support NO_PURGE. For example the BIND provider
+rewrites zone files from scratch each time, which precludes supporting
+NO_PURGE.  DNSControl will exit with an error if NO_PURGE is used
+on a driver that does not support it.
+
+There is also `PURGE` command for completeness. `PURGE` is the
+default, thus this command is a no-op.

docs/_functions/domain/NS.md

@@ -0,0 +1,25 @@
+---
+name: NS
+parameters:
+  - name
+  - target
+  - modifiers...
+---
+
+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.
+
+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 `.`.
+
+{% include startExample.html %}
+{% highlight js %}
+
+D("example.com", REGISTRAR, DnsProvider("R53"),
+  NS("foo", "ns1.example2.com"), // Delegate ".foo.example.com" zone to another server.
+  NS("foo", "ns2.example2.com"), // Delegate ".foo.example.com" zone to another server.
+  A("ns1.example2.com", "10.10.10.10"), // Glue records
+  A("ns2.example2.com", "10.10.10.20"), // Glue records
+);
+
+{%endhighlight%}
+{% include endExample.html %}

docs/_functions/domain/PURGE.md

@@ -0,0 +1,44 @@
+---
+name: PURGE
+---
+
+PURGE is the default setting for all domains.  Therefore PURGE is
+a no-op. It is included for completeness only.
+
+A domain with a mixture of NO_PURGE and PURGE parameters will abide
+by the last one.
+
+These three examples all are equivalent.
+
+PURGE is the default:
+
+{% include startExample.html %}
+{% highlight js %}
+D("example.com", .... ,
+);
+{%endhighlight%}
+{% include endExample.html %}
+
+Purge is the default, but we set it anyway:
+
+{% include startExample.html %}
+{% highlight js %}
+D("example.com", .... ,
+  PURGE,
+);
+{%endhighlight%}
+{% include endExample.html %}
+
+Since the "last command wins", this is the same as `PURGE`:
+
+{% include startExample.html %}
+{% highlight js %}
+D("example.com", .... ,
+  PURGE,
+  NO_PURGE,
+  PURGE,
+  NO_PURGE,
+  PURGE,
+);
+{%endhighlight%}
+{% include endExample.html %}

docs/_functions/domain/TXT.md

@@ -0,0 +1,30 @@
+---
+name: TXT
+parameters:
+  - name
+  - contents
+  - modifiers...
+---
+
+TXT adds an TXT record To a domain. The name should be the relative
+label for the record. Use `@` for the domain apex.
+
+The contents is a single string.  While DNS permits multiple
+strings in TXT records, that is not supported at this time.
+
+The string is a JavaScript string (quoted using single or double
+quotes).  The (somewhat complex) quoting rules of the DNS protocol
+will be done for you.
+
+Modifers can be any number of [record modifiers](#record-modifiers) or json objects, which will be merged into the record's metadata.
+
+{% include startExample.html %}
+{% highlight js %}
+
+D("example.com", REGISTRAR, ....,
+  TXT('@', '598611146-3338560'),
+  TXT('listserve', 'google-site-verification=12345'),
+);
+
+{%endhighlight%}
+{% include endExample.html %}