diff --git a/docs/_functions/global/DOMAIN_ELSEWHERE.md b/docs/_functions/global/DOMAIN_ELSEWHERE.md new file mode 100644 index 000000000..ae74601e1 --- /dev/null +++ b/docs/_functions/global/DOMAIN_ELSEWHERE.md @@ -0,0 +1,34 @@ +--- +name: DOMAIN_ELSEWHERE +parameters: + - registrar + - list of nameserver names +--- + +`DOMAIN_ELSEWHERE()` is a helper macro that lets you easily indicate that +a domain's zones are managed elsewhere. That is, it permits you easily delegate +a domain to a hard-coded list of DNS servers. + +`DOMAIN_ELSEWHERE` is useful when you control a domain's registrar but not the +DNS servers. For example, suppose you own a domain but the DNS servers are run +by someone else, perhaps a SaaS product you've subscribed to or a DNS server +that is run by your brother-in-law who doesn't trust you with the API keys that +would let you maintain the domain using DNSControl. You need an easy way to +point (delegate) the domain at a specific list of DNS servers. + +For example these two statements are equivalent: + +``` +DOMAIN_ELSEWHERE("example.com", REG_NAMEDOTCOM, ["ns1.foo.com", "ns2.foo.com"]); + +# ...is equivalent to... + +D("example.com", REG_NAMEDOTCOM, + NO_PURGE, + NAMESERVER("ns1.foo.com"), + NAMESERVER("ns2.foo.com") +); +``` + +NOTE: The `NO_PURGE` is used out of abundance of caution but since no +`DnsProvider()` statements exist, no updates would be performed. diff --git a/docs/_functions/global/DOMAIN_ELSEWHERE_AUTO.md b/docs/_functions/global/DOMAIN_ELSEWHERE_AUTO.md new file mode 100644 index 000000000..535631a5f --- /dev/null +++ b/docs/_functions/global/DOMAIN_ELSEWHERE_AUTO.md @@ -0,0 +1,35 @@ +--- +name: DOMAIN_ELSEWHERE_AUTO +parameters: + - registrar + - list of Dns Providers +--- + +`DOMAIN_ELSEWHERE_AUTO()` is similar to `DOMAIN_ELSEWHERE()` but instead of +a hardcoded list of nameservers, a DnsProvider() is queried. + +`DOMAIN_ELSEWHERE_AUTO` is useful when you control a domain's registrar but the +DNS zones are managed by another system. Luckily you have enough access to that +other system that you can query it to determine the zone's nameservers. + +For example, suppose you own a domain but the DNS servers for it are in Azure. +Further suppose that something in Azure maintains the zones (automatic or +human). Azure picks the nameservers for the domains automatically, and that +list may change occasionally. `DOMAIN_ELSEWHERE_AUTO` allows you to easily +query Azure to determine the domain's delegations so that you do not need to +hard-code them in your dnsconfig.js file. + +For example these two statements are equivalent: + +``` +DOMAIN_ELSEWHERE_AUTO("example.com", REG_NAMEDOTCOM, DSP_AZURE); + +# ...is equivalent to... + +D("example.com", REG_NAMEDOTCOM, + NO_PURGE, + DnsProvider(DSP_AZURE) +); +``` + +NOTE: The `NO_PURGE` is used to prevent DNSControl from changing the records. diff --git a/docs/nameservers.md b/docs/nameservers.md index fd165f217..e7b583c6d 100644 --- a/docs/nameservers.md +++ b/docs/nameservers.md @@ -130,6 +130,23 @@ D("example1.com", REG_NAMECOM, A("@", "10.2.3.4") ); +// ========== Fancy macros + +// There are some built-in macros that you might find useful. + +// DOMAIN_ELSEWHERE: This macro points the domain's delegation +// (nameservers) to a list of DNS servers. +DOMAIN_ELSEWHERE("example1.com", REG_NAMECOM, [ + "dns1.example.net.", + "dns2.example.net.", + "dns3.example.net.", +]); + +// DOMAIN_ELSEWHERE_AUTO: Similar to DOMAIN_ELSEWHERE but the list +// of nameservers is queried from the API of a DNS provider. +DOMAIN_ELSEWHERE_AUTO("example1.com", REG_NAMECOM, DNS_AWS); +DOMAIN_ELSEWHERE_AUTO("example2.com", REG_NAMECOM, DNS_GOOGLE); + {%endhighlight%} {% include endExample.html %} diff --git a/pkg/js/helpers.js b/pkg/js/helpers.js index 6097abe37..8ce180dbe 100644 --- a/pkg/js/helpers.js +++ b/pkg/js/helpers.js @@ -1136,3 +1136,32 @@ function CLI_DEFAULTS(defaults) { function FETCH() { return fetch.apply(null, arguments).catch(PANIC); } + +// DOMAIN_ELSEWHERE is a helper macro that delegates a domain to a +// static list of nameservers. It updates the registrar (the parent) +// with a list of nameservers. This is used when we own the domain (we +// control the registrar) but something else controls the DNS records +// (often a third-party of Azure). +// Usage: DOMAIN_ELSEWHERE("example.com", REG_NAMEDOTCOM, ["ns1.foo.com", "ns2.foo.com"]); +function DOMAIN_ELSEWHERE(domain, registrar, nslist) { + D(domain, registrar, NO_PURGE); + // NB(tlim): NO_PURGE is added as a precaution since something else + // is maintaining the DNS records in that zone. In theory this is + // not needed since this domain won't have a DSP defined. + for (i = 0; i < nslist.length; i++) { + D_EXTEND(domain, NAMESERVER(nslist[i])); + } +} + +// DOMAIN_ELSEWHERE_AUTO is similar to DOMAIN_ELSEWHERE but the list of +// nameservers is queried from a DNS Service Provider. +// Usage: DOMAIN_ELSEWHERE_AUTO("example.com", REG_NAMEDOTCOM, DNS_FOO) +function DOMAIN_ELSEWHERE_AUTO(domain, registrar, dsplist) { + D(domain, registrar, NO_PURGE); + // NB(tlim): NO_PURGE is required since something else + // is maintaining the DNS records in that zone, and we have access + // to updating it (but we don't want to use it.) + for (i = 2; i < arguments.length; i++) { + D_EXTEND(domain, DnsProvider(arguments[i])); + } +}