From ea3e2831a8a97db6f0882bd7b942470eafd2aad0 Mon Sep 17 00:00:00 2001 From: Tom Limoncelli Date: Tue, 15 Aug 2017 10:46:31 -0700 Subject: [PATCH] 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 | 72 ++++++++++++++++++++++ docs/_functions/domain/NAMESERVER.md | 24 ++++++++ docs/_functions/domain/NO_PURGE.md | 41 ++++++++++++ docs/_functions/domain/NS.md | 25 ++++++++ docs/_functions/domain/PURGE.md | 44 +++++++++++++ docs/_functions/domain/TXT.md | 30 +++++++++ 6 files changed, 236 insertions(+) create mode 100644 docs/_functions/domain/NO_PURGE.md diff --git a/docs/_functions/domain/IMPORT_TRANSFORM.md b/docs/_functions/domain/IMPORT_TRANSFORM.md index e69de29bb..701b9c706 100644 --- a/docs/_functions/domain/IMPORT_TRANSFORM.md +++ b/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. diff --git a/docs/_functions/domain/NAMESERVER.md b/docs/_functions/domain/NAMESERVER.md index e69de29bb..31c7698d8 100644 --- a/docs/_functions/domain/NAMESERVER.md +++ b/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 %} diff --git a/docs/_functions/domain/NO_PURGE.md b/docs/_functions/domain/NO_PURGE.md new file mode 100644 index 000000000..ad8d17b10 --- /dev/null +++ b/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. diff --git a/docs/_functions/domain/NS.md b/docs/_functions/domain/NS.md index e69de29bb..d93512738 100644 --- a/docs/_functions/domain/NS.md +++ b/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 %} diff --git a/docs/_functions/domain/PURGE.md b/docs/_functions/domain/PURGE.md index e69de29bb..329082533 100644 --- a/docs/_functions/domain/PURGE.md +++ b/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 %} diff --git a/docs/_functions/domain/TXT.md b/docs/_functions/domain/TXT.md index e69de29bb..1fcf8f2db 100644 --- a/docs/_functions/domain/TXT.md +++ b/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 %}