DNSControl uses javascript as its primary input language to provide power and flexibility to configure your domains. The ultimate purpose of the javascript is to construct a DNSConfig object that will be passed to the go backend and operated on.
require_glob( path, recursive )
require_glob()
can recursively load .js
files, optionally non-recursive as well.
Possible parameters are:
true
or false
. Default is true
.Example to load .js
files recursively:
require_glob("./domains/");
Example to load .js
files only in domains/
:
require_glob("./domains/", false);
One more important thing to note: require_glob()
is as smart as require()
is. It loads files always relative to the JavaScript
file where it’s being executed in. Let’s go with an example, as it describes it better:
dnscontrol.js:
require("domains/index.js");
domains/index.js:
require_glob("./user1/");
This will now load files being present underneath ./domains/user1/
and NOT at below ./domains/
, as require_glob()
is called in the subfolder domains/
.
require( path )
require(...)
loads the specified JavaScript or JSON file, allowing
to split your configuration across multiple files.
If the supplied path
string ends with .js
, the file is interpreted
as JavaScript code, almost as though its contents had been included in
the currently-executing file. If the path string ends with .json
,
require()
returns the JSON.parse()
of the file’s contents.
If the path string begins with a .
, it is interpreted relative to
the currently-loading file (which may not be the file where the
require()
statement is, if called within a function), otherwise it
is interpreted relative to the program’s working directory at the time
of the call.
Example:
// dnsconfig.js
require('kubernetes/clusters.js');
D("mydomain.net", REG, PROVIDER,
IncludeKubernetes()
);
// kubernetes/clusters.js
require('./clusters/prod.js');
require('./clusters/dev.js');
function IncludeKubernetes() {
return [includeK8Sprod(), includeK8Sdev()];
}
// kubernetes/clusters/prod.js
function includeK8Sprod() {
return [ /* ... */ ];
}
// kubernetes/clusters/dev.js
function includeK8Sdev() {
return [ /* ... */ ];
}
You can also use it to require json files and initialize variables with it: For Example:
Example:
// dnsconfig.js
var domains = require('./domain-ip-map.json')
for (var domain in domains) {
D(domain, REG, PROVIDER,
A("@", domains[domain])
);
}
// domain-ip-map.json
{
"mydomain.net": "1.1.1.1",
"myotherdomain.org": "5.5.5.5"
}
It might be better to rename the function to something like
include()
instead, (leaving require
as a deprecated alias) because
by analogy it is much closer to PHP’s include()
function than it
is to node’s require()
. After all, the reason node.js calls it
“require” is because it’s a declarative statement saying the file is
needed, and so should be loaded if it hasn’t already been loaded.
In contrast, dnscontrol’s require is actually an imperative command to
load the file and execute the code or parse the data from it. (So if
two files both require("./tools.js")
, for example, then it will be
loaded twice, whereas in node.js it would only be loaded once.)
getConfiguredDomains( name, modifiers... )
getConfiguredDomains
getConfiguredDomains is a helper function that returns the domain names
configured at the time the function is called. Calling this function early or later in
dnsconfig.js
may return different results. Typical usage is to iterate over all
domains at the end of your configuration file.
Example for adding records to all configured domains:
Example:
var domains = getConfiguredDomains();
for(i = 0; i < domains.length; i++) {
D_EXTEND(domains[i],
TXT('_important', 'BLA') // I know, not really creative.
)
}
This will end up in following modifications:
******************** Domain: domain1.tld
----- Getting nameservers from: registrar
----- DNS Provider: registrar...2 corrections
#1: CREATE TXT _important.domain1.tld "BLA" ttl=43200
#2: REFRESH zone domain1.tld
******************** Domain: domain2.tld
----- Getting nameservers from: registrar
----- DNS Provider: registrar...2 corrections
#1: CREATE TXT _important.domain2.tld "BLA" ttl=43200
#2: REFRESH zone domain2.tld
Example for adding DMARC report records:
Example:
This example might be more useful, specially for configuring the DMARC report records. According to DMARC RFC you need to specify domain2.tld._report.dmarc.domain1.tld
to allow domain2.tld
to send aggregate/forensic email reports to domain1.tld
. This can be used to do this in an easy way, without using the wildcard from the RFC.
var domains = getConfiguredDomains();
for(i = 0; i < domains.length; i++) {
D_EXTEND("domain1.tld",
TXT(domains[i] + '._report._dmarc', 'v=DMARC1')
);
}
This will end up in following modifications:
******************** Domain: domain2.tld
----- Getting nameservers from: registrar
----- DNS Provider: registrar...4 corrections
#1: CREATE TXT domain1.tld._report._dmarc.domain2.tld "v=DMARC1" ttl=43200
#2: CREATE TXT domain3.tld._report._dmarc.domain2.tld "v=DMARC1" ttl=43200
#3: CREATE TXT domain4.tld._report._dmarc.domain2.tld "v=DMARC1" ttl=43200
#4: REFRESH zone domain2.tld
REV( address )
REV
returns the reverse lookup domain for an IP network. For
example REV('1.2.3.0/24')
returns 3.2.1.in-addr.arpa.
and
REV('2001:db8:302::/48)
returns 2.0.3.0.8.b.d.0.1.0.0.2.ip6.arpa.
.
This is used in D()
functions to create reverse DNS lookup zones.
This is a convenience function. You could specify D('3.2.1.in-addr.arpa
,
…` if you like to do things manually but why would you risk making
typos?
REV
complies with RFC2317, “Classless in-addr.arpa delegation”
for netmasks of size /25 through /31.
While the RFC permits any format, we abide by the recommended format:
FIRST/MASK.C.B.A.in-addr.arpa
where FIRST
is the first IP address
of the zone, MASK
is the netmask of the zone (25-31 inclusive),
and A, B, C are the first 3 octets of the IP address. For example
172.20.18.130/27
is located in a zone named
128/27.18.20.172.in-addr.arpa
If the address does not include a “/” then REV
assumes /32 for IPv4 addresses
and /128 for IPv6 addresses.
Note that the lower bits (the ones outside the netmask) must be zeros. They are not zeroed out automatically. Thus, `REV(‘1.2.3.4/24’) is an error. This is done to catch typos.
Example:
D(REV('1.2.3.0/24'), REGISTRAR, DnsProvider(BIND),
PTR("1", 'foo.example.com.'),
PTR("2", 'bar.example.com.'),
PTR("3", 'baz.example.com.'),
// These take advantage of DNSControl's ability to generate the right name:
PTR("1.2.3.10", 'ten.example.com.'),
);
D(REV('2001:db8:302::/48'), REGISTRAR, DnsProvider(BIND),
PTR("1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0", 'foo.example.com.'), // 2001:db8:302::1
// These take advantage of DNSControl's ability to generate the right name:
PTR("2001:db8:302::2", 'two.example.com.'), // 2.0.0...
PTR("2001:db8:302::3", 'three.example.com.'), // 3.0.0...
);
In the future we plan on adding a flag to A()
which will insert
the correct PTR() record if the appropriate D(REV()
domain (i.e. .arpa
domain) has been
defined.
PANIC( message )
PANIC
terminates the script and therefore DnsControl with an exit code of 1. This should be used if your script cannot gather enough information to generate records, for example when a HTTP request failed.
Example:
PANIC("Something really bad has happened");
NewRegistrar( name, type, meta )
-> string
NewRegistrar activates a Registrar Provider specified in creds.json
.
A registrar maintains the domain’s registration and delegation (i.e. the
nameservers for the domain). DNSControl only manages the delegation.
name
must match the name of an entry in creds.json
.type
specifies a valid DNS provider type identifier listed on the provider page..
TYPE
field in creds.json
is used instead. You can leave it out. (Thanks to JavaScript magic, you can leave it out even when there are more fields).TYPE
field to creds.json
and remove this parameter from dnsconfig.js
to prepare.meta
is a way to send additional parameters to the provider. It is optional and only certain providers use it. See the individual provider docs for details.This function will return an opaque string that should be assigned to a variable name for use in D directives.
Prior to v3.16:
var REG_MYNDC = NewRegistrar("mynamedotcom", "NAMEDOTCOM");
var DNS_MYAWS = NewDnsProvider("myaws", "ROUTE53");
D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS),
A("@","1.2.3.4")
);
In v3.16 and later:
var REG_MYNDC = NewRegistrar("mynamedotcom");
var DNS_MYAWS = NewDnsProvider("myaws");
D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS),
A("@","1.2.3.4")
);
NewDnsProvider( name, type, meta )
-> string
NewDnsProvider activates a DNS Service Provider (DSP) specified in creds.json. A DSP stores a DNS zone’s records and provides DNS service for the zone (i.e. answers on port 53 to queries related to the zone).
name
must match the name of an entry in creds.json
.type
specifies a valid DNS provider type identifier listed on the provider page..
TYPE
field in creds.json
is used instead. You can leave it out. (Thanks to JavaScript magic, you can leave it out even when there are more fields).TYPE
field to creds.json
and remove this parameter from dnsconfig.js
to prepare.meta
is a way to send additional parameters to the provider. It is optional and only certain providers use it. See the individual provider docs for details.This function will return an opaque string that should be assigned to a variable name for use in D directives.
Prior to v3.16:
var REG_MYNDC = NewRegistrar("mynamedotcom", "NAMEDOTCOM");
var DNS_MYAWS = NewDnsProvider("myaws", "ROUTE53");
D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS),
A("@","1.2.3.4")
);
In v3.16 and later:
var REG_MYNDC = NewRegistrar("mynamedotcom");
var DNS_MYAWS = NewDnsProvider("myaws");
D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS),
A("@","1.2.3.4")
);
IP( ip )
Converts an IPv4 address from string to an integer. This allows performing mathematical operations with the IP address.
This does not accept IPv6 addresses. (PRs gladly accepted.)
Example:
var addrA = IP('1.2.3.4')
var addrB = addrA + 1
// addrB = 1.2.3.5
FETCH( url, args )
FETCH
is a wrapper for the Fetch API. This allows dynamically setting DNS records based on an external data source, e.g. the API of your cloud provider.
Compared to fetch
from Fetch API, FETCH
will call PANIC to terminate the execution of the script, and therefore DnsControl, if a network error occurs.
Otherwise the syntax of FETCH
is the same as fetch
.
FETCH
is not enabled by default. Please read the warnings below.
WARNING:
- Relying on external sources adds a point of failure. If the external source doesn’t work, your script won’t either. Please make sure you are aware of the consequences.
- Make sure DnsControl only uses verified configuration if you want to use
FETCH
. For example, an attacker can send Pull Requests to your config repo, and have your CI test malicious configurations and make arbitrary HTTP requests. Therefore,FETCH
must be explicitly enabled with flag--allow-fetch
on DnsControl invocation.
Example:
var REG_NONE = NewRegistrar('none');
var DNS_BIND = NewDnsProvider('bind');
D('example.com', REG_NONE, DnsProvider(DNS_BIND), [
A('@', '1.2.3.4'),
]);
FETCH('https://example.com', {
// All three options below are optional
headers: {"X-Authentication": "barfoo"},
method: "POST",
body: "Hello World",
}).then(function(r) {
return r.text();
}).then(function(t) {
// Example of generating record based on response
D_EXTEND('example.com', [
TXT('@', t.slice(0, 100)),
]);
});
D_EXTEND( name, modifiers... )
D_EXTEND
adds records (and metadata) to a domain previously defined
by D()
. It can also be used to add subdomain records (and metadata)
to a previously defined domain.
The first argument is a domain name. If it exactly matches a
previously defined domain, D_EXTEND()
behaves the same as D()
,
simply adding records as if they had been specified in the original
D()
.
If the domain name does not match an existing domain, but could be a (non-delegated) subdomain of an existing domain, the new records (and metadata) are added with the subdomain part appended to all record names (labels), and targets (as appropriate). See the examples below.
Matching the domain name to previously-defined domains is done using a
longest match
algorithm. If domain.tld
and sub.domain.tld
are
defined as separate domains via separate D()
statements, then
D_EXTEND('sub.sub.domain.tld', ...)
would match sub.domain.tld
,
not domain.tld
.
Some operators only act on an apex domain (e.g.
CF_REDIRECT
and CF_TEMP_REDIRECT
). Using them
in a D_EXTEND
subdomain may not be what you expect.
Example:
Example:
D("domain.tld", REG, DnsProvider(DNS),
A("@", "127.0.0.1"), // domain.tld
A("www", "127.0.0.2"), // www.domain.tld
CNAME("a", "b") // a.domain.tld -> b.domain.tld
);
D_EXTEND("domain.tld",
A("aaa", "127.0.0.3"), // aaa.domain.tld
CNAME("c", "d") // c.domain.tld -> d.domain.tld
);
D_EXTEND("sub.domain.tld",
A("bbb", "127.0.0.4"), // bbb.sub.domain.tld
A("ccc", "127.0.0.5"), // ccc.sub.domain.tld
CNAME("e", "f") // e.sub.domain.tld -> f.sub.domain.tld
);
D_EXTEND("sub.sub.domain.tld",
A("ddd", "127.0.0.6"), // ddd.sub.sub.domain.tld
CNAME("g", "h") // g.sub.sub.domain.tld -> h.sub.sub.domain.tld
);
D_EXTEND("sub.domain.tld",
A("@", "127.0.0.7"), // sub.domain.tld
CNAME("i", "j") // i.sub.domain.tld -> j.sub.domain.tld
);
This will end up in the following modifications:
******************** Domain: domain.tld
----- Getting nameservers from: cloudflare
----- DNS Provider: cloudflare...7 corrections
#1: CREATE A aaa.domain.tld 127.0.0.3
#2: CREATE A bbb.sub.domain.tld 127.0.0.4
#3: CREATE A ccc.sub.domain.tld 127.0.0.5
#4: CREATE A ddd.sub.sub.domain.tld 127.0.0.6
#5: CREATE A sub.domain.tld 127.0.0.7
#6: CREATE A www.domain.tld 127.0.0.2
#7: CREATE A domain.tld 127.0.0.1
#8: CREATE CNAME a.domain.tld b.domain.tld.
#9: CREATE CNAME c.domain.tld d.domain.tld.
#10: CREATE CNAME e.sub.domain.tld f.sub.domain.tld.
#11: CREATE CNAME g.sub.sub.domain.tld h.sub.sub.domain.tld.
#12: CREATE CNAME i.sub.domain.tld j.sub.domain.tld.
ProTips: D_EXTEND()
permits you to create very complex and
sophisticated configurations, but you shouldn’t. Be nice to the next
person that edits the file, who may not be as expert as yourself.
Enhance readability by putting any D_EXTEND()
statements immediately
after the original D()
, like in above example. Avoid the temptation
to obscure the addition of records to existing domains with randomly
placed D_EXTEND()
statements. Don’t build up a domain using loops of
D_EXTEND()
statements. You’ll be glad you didn’t.
DOMAIN_ELSEWHERE_AUTO( 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.
DOMAIN_ELSEWHERE( 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.
DEFAULTS( modifiers... )
DEFAULTS
allows you to declare a set of default arguments to apply to all subsequent domains. Subsequent calls to D will have these
arguments passed as if they were the first modifiers in the argument list.
Example:
var COMMON = NewDnsProvider("foo");
// we want to create backup zone files for all domains, but not actually register them.
// also create a default TTL
DEFAULTS( DnsProvider(COMMON,0), DefaultTTL(1000));
D("example.com", REGISTRAR, DnsProvider("R53"), A("@","1.2.3.4")); // this domain will have the defaults set.
// clear defaults
DEFAULTS();
D("example2.com", REGISTRAR, DnsProvider("R53"), A("@","1.2.3.4")); // this domain will not have the previous defaults.
D( name, registrar, modifiers... )
D
adds a new Domain for DNSControl to manage. The first two arguments are required: the domain name (fully qualified example.com
without a trailing dot), and the
name of the registrar (as previously declared with NewRegistrar). Any number of additional arguments may be included to add DNS Providers with DNSProvider,
add records with A, CNAME, and so forth, or add metadata.
Modifier arguments are processed according to type as follows:
Example:
var REGISTRAR = NewRegistrar("name.com");
var r53 = NewDnsProvider("R53");
// simple domain
D("example.com", REGISTRAR, DnsProvider(r53),
A("@","1.2.3.4"),
CNAME("test", "foo.example2.com.")
);
// "macro" for records that can be mixed into any zone
var GOOGLE_APPS_DOMAIN_MX = [
MX('@', 1, 'aspmx.l.google.com.'),
MX('@', 5, 'alt1.aspmx.l.google.com.'),
MX('@', 5, 'alt2.aspmx.l.google.com.'),
MX('@', 10, 'alt3.aspmx.l.google.com.'),
MX('@', 10, 'alt4.aspmx.l.google.com.'),
]
D("example.com", REGISTRAR, DnsProvider(r53),
A("@","1.2.3.4"),
CNAME("test", "foo.example2.com."),
GOOGLE_APPS_DOMAIN_MX
);
DNSControl supports Split Horizon DNS. Simply define the domain two or more times, each with their own unique parameters.
To differentiate the different domains, specify the domains as
domain.tld!tag
, such as example.com!inside
and
example.com!outside
.
Example:
var REG = NewRegistrar("Third-Party");
var DNS_INSIDE = NewDnsProvider("Cloudflare");
var DNS_OUTSIDE = NewDnsProvider("bind");
D("example.com!inside", REG, DnsProvider(DNS_INSIDE),
A("www", "10.10.10.10")
);
D("example.com!outside", REG, DnsProvider(DNS_OUTSIDE),
A("www", "20.20.20.20")
);
D_EXTEND("example.com!inside",
A("internal", "10.99.99.99")
);
A domain name without a !
is assigned a tag that is the empty
string. For example, example.com
and example.com!
are equivalent.
However, we strongly recommend against using the empty tag, as it
risks creating confusion. In other words, if you have domain.tld
and domain.tld!external
you now require humans to remember that
domain.tld
is the external one. I mean… the internal one. You
may have noticed this mistake, but will your coworkers? Will you in
six months? You get the idea.
DNSControl command line flag --domains
is an exact match. If you
define domains example.com!george
and example.com!john
then:
--domains=example.com
will not match either domain.--domains='example.com!george'
will match only match the first.--domains='example.com!george',example.com!john
will match both.NOTE: The quotes are required if your shell treats !
as a special
character, which is probably does. If you see an error that mentions
event not found
you probably forgot the quotes.
A( name, address, modifiers... )
A adds an A record To a domain. The name should be the relative label for the record. Use @
for the domain apex.
The address should be an ip address, either a string, or a numeric value obtained via IP.
Modifiers can be any number of record modifiers or json objects, which will be merged into the record’s metadata.
Example:
D("example.com", REGISTRAR, DnsProvider("R53"),
A("@", "1.2.3.4"),
A("foo", "2.3.4.5"),
A("test.foo", IP("1.2.3.4"), TTL(5000)),
A("*", "1.2.3.4", {foo: 42})
);
AAAA( name, address, modifiers... )
AAAA adds an AAAA record To a domain. The name should be the relative label for the record. Use @
for the domain apex.
The address should be an IPv6 address as a string.
Modifiers can be any number of record modifiers or json objects, which will be merged into the record’s metadata.
Example:
var addrV6 = "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
D("example.com", REGISTRAR, DnsProvider("R53"),
AAAA("@", addrV6),
AAAA("foo", addrV6),
AAAA("test.foo", addrV6, TTL(5000)),
AAAA("*", addrV6, {foo: 42})
);
AKAMAICDN( name, target, modifiers... )
AKAMAICDN is a proprietary record type that is used to configure Zone Apex Mapping. The AKAMAICDN target must be preconfigured in the Akamai network.
ALIAS( name, target, modifiers... )
ALIAS is a virtual record type that points a record at another record. It is analogous to a CNAME, but is usually resolved at request-time and served as an A record. Unlike CNAMEs, ALIAS records can be used at the zone apex (@
)
Different providers handle ALIAS records differently, and many do not support it at all. Attempting to use ALIAS records with a DNS provider type that does not support them will result in an error.
The name should be the relative label for the domain.
Target should be a string representing the 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 .
.
Example:
D("example.com", REGISTRAR, DnsProvider("CLOUDFLARE"),
ALIAS("@", "google.com."), // example.com -> google.com
);
AUTODNSSEC_OFF( )
AUTODNSSEC_OFF tells the provider to disable AutoDNSSEC. It takes no parameters.
See AUTODNSSEC_ON
for further details.
AUTODNSSEC_ON( )
AUTODNSSEC_ON tells the provider to enable AutoDNSSEC.
AUTODNSSEC_OFF tells the provider to disable AutoDNSSEC.
AutoDNSSEC is a feature where a DNS provider can automatically manage DNSSEC for a domain. Not all providers support this.
At this time, AUTODNSSEC_ON takes no parameters. There is no ability to tune what the DNS provider sets, no algorithm choice. We simply ask that they follow their defaults when enabling a no-fuss DNSSEC data model.
NOTE: No parenthesis should follow these keywords. That is, the
correct syntax is AUTODNSSEC_ON
not AUTODNSSEC_ON()
Example:
D("example.com", .... ,
AUTODNSSEC_ON, // Enable AutoDNSSEC.
A("@", "10.1.1.1")
);
D("insecure.com", .... ,
AUTODNSSEC_OFF, // Disable AutoDNSSEC.
A("@", "10.2.2.2")
);
If neither AUTODNSSEC_ON
or AUTODNSSEC_OFF
is specified for a
domain no changes will be requested.
AZURE_ALIAS( name, type, target, modifiers ... )
AZURE_ALIAS is a Azure specific virtual record type that points a record at either another record or an Azure entity.
It is analogous to a CNAME, but is usually resolved at request-time and served as an A record.
Unlike CNAMEs, ALIAS records can be used at the zone apex (@
)
Unlike the regular ALIAS directive, AZURE_ALIAS is only supported on AZURE. Attempting to use AZURE_ALIAS on another provider than Azure will result in an error.
The name should be the relative label for the domain.
The type can be any of the following:
Target should be the Azure Id representing the target. It starts /subscription/
. The resource id can be found in https://resources.azure.com/.
The Target can :
A/AAAA
record set.
You can create an A/AAAA record set and make it an alias record set to point to a public IP resource (standard or basic).
The DNS record set changes automatically if the public IP address changes or is deleted.
Dangling DNS records that point to incorrect IP addresses are avoided.
There is a current limit of 20 alias records sets per resource.A/AAAA/CNAME
record set.
You can create an A/AAAA or CNAME record set and use alias records to point it to a Traffic Manager profile.
It’s especially useful when you need to route traffic at a zone apex, as traditional CNAME records aren’t supported for a zone apex.
For example, say your Traffic Manager profile is myprofile.trafficmanager.net and your business DNS zone is contoso.com.
You can create an alias record set of type A/AAAA for contoso.com (the zone apex) and point to myprofile.trafficmanager.net.Example:
D("example.com", REGISTRAR, DnsProvider("AZURE_DNS"),
AZURE_ALIAS("foo", "A", "/subscriptions/726f8cd6-6459-4db4-8e6d-2cd2716904e2/resourceGroups/test/providers/Microsoft.Network/trafficManagerProfiles/testpp2"), // record for traffic manager
AZURE_ALIAS("foo", "CNAME", "/subscriptions/726f8cd6-6459-4db4-8e6d-2cd2716904e2/resourceGroups/test/providers/Microsoft.Network/dnszones/example.com/A/quux."), // record in the same zone
);
CAA( name, tag, value, modifiers... )
CAA adds a CAA record to a domain. The name should be the relative label for the record. Use @
for the domain apex.
Tag can be one of “issue”, “issuewild” or “iodef”.
Value is a string. The format of the contents is different depending on the tag. DNSControl will handle any escaping or quoting required, similar to TXT records. For example use CAA("@", "issue", "letsencrypt.org")
rather than CAA("@", "issue", "\"letsencrypt.org\"")
.
Flags are controlled by modifier:
CAA record is supported only by BIND, Google Cloud DNS, Amazon Route 53 and OVH. Some certificate authorities may not support this record until the mandatory date of September 2017.
Example:
D("example.com", REGISTRAR, DnsProvider("GCLOUD"),
// Allow letsencrypt to issue certificate for this domain
CAA("@", "issue", "letsencrypt.org"),
// Allow no CA to issue wildcard certificate for this domain
CAA("@", "issuewild", ";"),
// Report all violation to test@example.com. If CA does not support
// this record then refuse to issue any certificate
CAA("@", "iodef", "mailto:test@example.com", CAA_CRITICAL)
);
CF_REDIRECT( destination, modifiers... )
CF_REDIRECT
uses Cloudflare-specific features (“Forwarding URL” Page Rules) to
generate a HTTP 301 permanent redirect.
If any CF_REDIRECT
or CF_TEMP_REDIRECT
functions are used then
dnscontrol
will manage all “Forwarding URL” type Page Rules for the domain.
Page Rule types other than “Forwarding URL” will be left alone.
WARNING: Cloudflare does not currently fully document the Page Rules API and
this interface is not extensively tested. Take precautions such as making
backups and manually verifying dnscontrol preview
output before running
dnscontrol push
. This is especially true when mixing Page Rules that are
managed by DNSControl and those that aren’t.
HTTP 301 redirects are cached by browsers forever, usually ignoring any TTLs or
other cache invalidation techniques. It should be used with great care. We
suggest using a CF_TEMP_REDIRECT
initially, then changing to a CF_REDIRECT
only after sufficient time has elapsed to prove this is what you really want.
This example redirects the bare (aka apex, or naked) domain to www:
Example:
D("foo.com", .... ,
CF_REDIRECT("mydomain.com/*", "https://www.mydomain.com/$1"),
);
CF_TEMP_REDIRECT( destination, modifiers... )
CF_TEMP_REDIRECT
uses Cloudflare-specific features (“Forwarding URL” Page
Rules) to generate a HTTP 302 temporary redirect.
If any CF_REDIRECT
or CF_TEMP_REDIRECT
functions are used then
dnscontrol
will manage all “Forwarding URL” type Page Rules for the domain.
Page Rule types other than “Forwarding URL” will be left alone.
WARNING: Cloudflare does not currently fully document the Page Rules API and
this interface is not extensively tested. Take precautions such as making
backups and manually verifying dnscontrol preview
output before running
dnscontrol push
. This is especially true when mixing Page Rules that are
managed by DNSControl and those that aren’t.
Example:
D("foo.com", .... ,
CF_TEMP_REDIRECT("example.mydomain.com/*", "https://otherplace.yourdomain.com/$1"),
);
CF_WORKER_ROUTE( pattern, script )
CF_WORKER_ROUTE
uses the Cloudflare Workers
API to manage worker routes
for a given domain.
If any CF_WORKER_ROUTE
function is used then dnscontrol
will manage all
Worker Routes for the domain. To be clear: this means it will delete existing routes that
were created outside of DNSControl.
WARNING: This interface is not extensively tested. Take precautions such as making
backups and manually verifying dnscontrol preview
output before running
dnscontrol push
.
This example assigns the patterns api.foo.com/*
and foo.com/api/*
to a my-worker
script:
Example:
D("foo.com", .... ,
CF_WORKER_ROUTE("api.foo.com/*", "my-worker"),
CF_WORKER_ROUTE("foo.com/api/*", "my-worker"),
);
CNAME( name, target, modifiers... )
CNAME adds a CNAME record to the domain. The name should be the relative label for the domain.
Using @
or *
for CNAME records is not recommended, as different providers support them differently.
Target should be a string representing the CNAME 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 .
.
Example:
D("example.com", REGISTRAR, DnsProvider("R53"),
CNAME("foo", "google.com."), // foo.example.com -> google.com
CNAME("abc", "@"), // abc.example.com -> example.com
CNAME("def", "test"), // def.example.com -> test.example.com
);
DS( name, keytag, algorithm, digesttype, digest, modifiers... )
DS adds a DS record to the domain.
Key Tag should be a number.
Algorithm should be a number.
Digest Type must be a number.
Digest must be a string.
Example:
D("example.com", REGISTRAR, DnsProvider(R53),
DS("example.com", 2371, 13, 2, "ABCDEF")
);
DefaultTTL( ttl )
DefaultTTL sets the TTL for all records in a domain that do not explicitly set one with TTL. If neither DefaultTTl
or TTL
exist for a record,
it will use the DNSControl global default of 300 seconds.
Example:
D('example.com', REGISTRAR, DnsProvider('R53'),
DefaultTTL("4h"),
A('@','1.2.3.4'), // uses default
A('foo', '2.3.4.5', TTL(600)) // overrides default
);
The DefaultTTL duration is the same format as TTL, an integer number of seconds
or a string with a unit such as '4d'
.
DnsProvider( name, nsCount )
DnsProvider indicates that the specified provider should be used to manage records for this domain. The name must match the name used with NewDnsProvider.
The nsCount parameter determines how the nameservers will be managed from this provider.
Leaving the parameter out means “fetch and use all nameservers from this provider as authoritative”. ie: DnsProvider("name")
Using 0
for nsCount means “do not fetch nameservers from this domain, or give them to the registrar”.
Using a different number, ie: DnsProvider("name",2)
, means “fetch all nameservers from this provider,
but limit it to this many.
See this page for a detailed explanation of how DNSControl handles nameservers and NS records.
If a domain (D()
) does not include any DnsProvider()
functions,
the DNS records will not be modified. In fact, if you want to control
the Registrar for a domain but not the DNS records themselves, simply
do not include a DnsProvider()
function for that D()
.
FRAME( name, target, modifiers... )
Documentation needed.
IGNORE( )
IGNORE has been renamed to IGNORE_NAME
. IGNORE will continue to function, but its use is deprecated. Please update your configuration files to use IGNORE_NAME
.
IGNORE_NAME( pattern )
WARNING: The IGNORE_*
family of functions is risky to use. The code
is brittle and has subtle bugs. Use at your own risk. Do not use these
commands with D_EXTEND()
.
IGNORE_NAME
can be used to ignore some records present in zone.
All records (independently of their type) of that name will be completely ignored.
IGNORE_NAME
is like NO_PURGE
except it acts only on some specific records instead of the whole zone.
Technically IGNORE_NAME
is a promise that DNSControl will not add, change, or delete records at a given label. This permits another entity to “own” that label.
IGNORE_NAME
is generally used in very specific situations:
IGNORE_NAME
will leave those records alone.In this example, DNSControl will insert/update the “baz.example.com” record but will leave unchanged the “foo.example.com” and “bar.example.com” ones.
Example:
D("example.com",
`IGNORE_NAME`("foo"),
`IGNORE_NAME`("bar"),
A("baz", "1.2.3.4")
);
IGNORE_NAME
also supports glob patterns in the style of the gobwas/glob library. All of
the following patterns will work:
IGNORE_NAME("*.foo")
will ignore all records in the style of bar.foo
, but will not ignore records using a double
subdomain, such as foo.bar.foo
.IGNORE_NAME("**.foo")
will ignore all subdomains of foo
, including double subdomains.IGNORE_NAME("?oo")
will ignore all records of three symbols ending in oo
, for example foo
and zoo
. It will
not match .
IGNORE_NAME("[abc]oo")
will ignore records aoo
, boo
and coo
. IGNORE_NAME("[a-c]oo")
is equivalent.IGNORE_NAME("[!abc]oo")
will ignore all three symbol records ending in oo
, except for aoo
, boo
, coo
. IGNORE_NAME("[!a-c]oo")
is equivalent.IGNORE_NAME("{bar,[fz]oo}")
will ignore bar
, foo
and zoo
.IGNORE_NAME("\\*.foo")
will ignore the literal record *.foo
.It is considered as an error to try to manage an ignored record.
Ignoring a label is a promise that DNSControl won’t meddle with
anything at a particular label, therefore DNSControl prevents you from
adding records at a label that is IGNORE_NAME
‘ed.
Use IGNORE_NAME("@")
to ignore at the domain’s apex. Most providers
insert magic or unchangable records at the domain’s apex; usually NS
and SOA
records. DNSControl treats them specially.
trying to update/add IGNORE_NAME'd record: foo CNAME
This means you have both ignored foo
and included a record (in this
case, a CNAME) to update it. This is an error because IGNORE_NAME
is a promise not to modify records at a certain label so that others
may have free reign there. Therefore, DNSControl prevents you from
modifying that label.
The foo CNAME
at the end of the message indicates the label name
(foo
) and the type of record (CNAME
) that your dnsconfig.js file
is trying to insert.
You can override this error by adding the
IGNORE_NAME_DISABLE_SAFETY_CHECK
flag to the record.
TXT('vpn', "this thing", IGNORE_NAME_DISABLE_SAFETY_CHECK)
Disabling this safety check creates two risks:
IGNORE_TARGET( pattern, rType )
WARNING: The IGNORE_*
family of functions is risky to use. The code
is brittle and has subtle bugs. Use at your own risk. Do not use these
commands with D_EXTEND()
or use it at the domain apex.
IGNORE_TARGET can be used to ignore some records present in zone based on the record’s target and type. IGNORE_TARGET currently only supports CNAME record types.
IGNORE_TARGET is like NO_PURGE except it acts only on some specific records instead of the whole zone.
IGNORE_TARGET is generally used in very specific situations:
In this example, DNSControl will insert/update the “baz.example.com” record but will leave unchanged a CNAME to “foo.acm-validations.aws” record.
Example:
D("example.com",
IGNORE_TARGET('**.acm-validations.aws.', 'CNAME'),
A("baz", "1.2.3.4")
);
IGNORE_TARGET also supports glob patterns in the style of the gobwas/glob library. Some example patterns:
IGNORE_TARGET("example.com", "CNAME")
will ignore all CNAME records with targets of exactly example.com
.IGNORE_TARGET("*.foo", "CNAME")
will ignore all CNAME records with targets in the style of bar.foo
, but will not ignore records with targets using a double subdomain, such as foo.bar.foo
.IGNORE_TARGET("**.bar", "CNAME")
will ignore all CNAME records with target subdomains of bar
, including double subdomains such as www.foo.bar
.IGNORE_TARGET("dev.*.foo", "CNAME")
will ignore all CNAME records with targets in the style of dev.bar.foo
, but will not ignore records with targets using a double subdomain, such as dev.foo.bar.foo
.It is considered as an error to try to manage an ignored record.
IMPORT_TRANSFORM( transform table, domain, modifiers... )
Don’t use this feature. It was added for a very specific situation at Stack Overflow.
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.
Example:
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
Here’s how you’d implement this in DNSControl:
Example:
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),
);
Transform rules are: RANGE_START, RANGE_END, NEW_BASE. NEW_BASE may be:
newBase: ['1.2.3.100', '2.4.6.8.100']
would produce 2 records for each A record.
INCLUDE( domain )
Includes all records from a given domain
Example:
D("example.com!external", REGISTRAR, DnsProvider(R53),
A("test", "8.8.8.8")
);
D("example.com!internal", REGISTRAR, DnsProvider(R53),
INCLUDE("example.com!external"),
A("home", "127.0.0.1")
);
MX( name, priority, target, modifiers... )
MX adds an MX record to the domain.
Priority should be a number.
Target should be a string representing the MX 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 .
.
Example:
D("example.com", REGISTRAR, DnsProvider(R53),
MX("@", 5, "mail"), // mx example.com -> mail.example.com
MX("sub", 10, "mail.foo.com.")
);
NAMESERVER( name, modifiers... )
NAMESERVER()
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.
This takes exactly one argument: the name of the nameserver. It must end with a “.” if it is a FQDN, just like all targets.
This is different than the NS()
function, which inserts NS records
in the current zone and accepts a label. NS()
is useful for downward
delegations. NAMESERVER()
is for informing upstream delegations.
For more information, refer to this page.
Example:
D("example.com", REGISTRAR, .... ,
DnsProvider(route53, 0),
// Replace the nameservers:
NAMESERVER("ns1.myserver.com."),
NAMESERVER("ns2.myserver.com."),
);
D("example2.com", REGISTRAR, .... ,
// Add these two additional nameservers to the existing list of nameservers.
NAMESERVER("ns1.myserver.com."),
NAMESERVER("ns2.myserver.com."),
);
Nameservers are one of the least understood parts of DNS, so a little extra explanation is required.
NS()
lets you add an NS record to a zone, just like A() adds an A
record to the zone. This is generally used to delegate a subzone.
The NAMESERVER()
directive speaks to the Registrar about how the parent should delegate the zone.
Since the parent zone could be completely unrelated to the current
zone, changes made by NAMESERVER()
have to be done by an API call to
the registrar, who then figures out what to do. For example, if I
use NAMESERVER()
in the zone stackoverflow.com
, DNSControl talks to
the registrar who does the hard work of talking to the people that
control .com
. If the domain was gmeet.io
, the registrar does
the right thing to talk to the people that control .io
.
(A better name might have been PARENTNAMESERVER()
but we didn’t
think of that at the time.)
Each registrar handles delegations differently. Most use
the NAMESERVER()
targets to update the delegation, adding
NS
records to the parent zone as required.
Some providers restrict the names to hosts they control.
Others may require you to add the NS
records to the parent domain
manually.
If dnsconfig.js has zero NAMESERVER()
commands for a domain, it will
use the API to remove all non-default nameservers.
If dnsconfig.js has 1 or more NAMESERVER()
commands for a domain, it
will use the API to add those nameservers (unless, of course,
they already exist).
So how do you tell DNSControl not to make any changes at all? Use the special Registrar called “NONE”. It makes no changes.
It looks like this:
var REG_THIRDPARTY = NewRegistrar('ThirdParty', 'NONE')
D("mydomain.com", REG_THIRDPARTY,
...
)
NAMESERVER_TTL( ttl )
TTL sets the TTL on the domain apex NS RRs defined by NAMESERVER.
The value can be an integer or a string. See TTL for examples.
Example:
D('example.com', REGISTRAR, DnsProvider('R53'),
NAMESERVER_TTL('2d'),
NAMESERVER('ns')
);
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:
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.
Example:
D("example.com", .... , NO_PURGE,
A("foo","1.2.3.4")
);
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.
NS( name, target, modifiers... )
NS adds a NS record to the domain. The name should be the relative label for the domain.
The name may not be @
(the bare domain), as that is controlled via NAMESERVER()
.
The difference between NS()
and NAMESERVER()
is explained in the NAMESERVER()
description.
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 .
.
Example:
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
);
PTR( name, target, modifiers... )
PTR adds a PTR record to the domain.
The name is normally a the relative label for the domain, or a FQDN that ends with .
. If magic mode is enabled (see below) it can also be an IP address, which will be replaced by the proper string automatically, thus
saving the user from having to reverse the IP address manually.
Target should be a string representing the FQDN of a host. Like all FQDNs in DNSControl, it must end with a .
.
Magic Mode:
PTR records are complex and typos are common. Therefore DNSControl
enables features to save labor and
prevent typos. This magic is only
enabled when the domain ends with in-addr.arpa.
or ipv6.arpa.
.
Automatic IP-to-reverse: If the name is a valid IP address, DNSControl will replace it with
a string that is appropriate for the domain. That is, if the domain
ends with in-addr.arpa
(no .
) and name is a valid IPv4 address, the name
will be replaced with the correct string to make a reverse lookup for that address.
IPv6 is properly handled too.
Extra Validation: DNSControl considers it an error to include a name that
is inappropriate for the domain. For example
PTR('1.2.3.4', 'f.co.')
is valid for the domain D("3.2.1.in-addr.arpa',
but DNSControl will generate an error if the domain is D("9.9.9.in-addr.arpa',
.
This is because 1.2.3.4
is contained in 1.2.3.0/24
but not 9.9.9.0/24
.
This validation works for IPv6, IPv4, and
RFC2317 “Classless in-addr.arpa delegation” domains.
Automatic truncation: DNSControl will automatically truncate FQDNs
as needed.
If the name is a FQDN ending with .
, DNSControl will verify that the
name is contained within the CIDR block implied by domain. For example
if name is 4.3.2.1.in-addr.arpa.
(note the trailing .
)
and the domain is 2.1.in-addr.arpa
(no trailing .
)
then the name will be replaced with 4.3
. Note that the output
of REV('1.2.3.4')
is 4.3.2.1.in-addr.arpa.
, which means the following
are all equivalent:
PTR(REV('1.2.3.4'),
PTR('4.3.2.1.in-addr.arpa.'),
PTR('4.3',
// Assuming the domain is 2.1.in-addr.arpa
All magic is RFC2317-aware. We use the first format listed in the
RFC for both REV()
and PTR()
. The format is
FIRST/MASK.C.B.A.in-addr.arpa
where FIRST
is the first IP address
of the zone, MASK
is the netmask of the zone (25-31 inclusive),
and A, B, C are the first 3 octets of the IP address. For example
172.20.18.130/27
is located in a zone named
128/27.18.20.172.in-addr.arpa
Example:
D(REV('1.2.3.0/24'), REGISTRAR, DnsProvider(BIND),
PTR('1', 'foo.example.com.'),
PTR('2', 'bar.example.com.'),
PTR('3', 'baz.example.com.'),
// If the first parameter is a valid IP address, DNSControl will generate the correct name:
PTR('1.2.3.10', 'ten.example.com.'), // '10'
);
D(REV('9.9.9.128/25'), REGISTRAR, DnsProvider(BIND),
PTR('9.9.9.129', 'first.example.com.'),
);
D(REV('2001:db8:302::/48'), REGISTRAR, DnsProvider(BIND),
PTR('1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0', 'foo.example.com.'), // 2001:db8:302::1
// If the first parameter is a valid IP address, DNSControl will generate the correct name:
PTR('2001:db8:302::2', 'two.example.com.'), // '2.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0'
PTR('2001:db8:302::3', 'three.example.com.'), // '3.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0'
);
In the future we plan on adding a flag to A()
which will insert
the correct PTR() record if the appropriate .arpa
domain has been
defined.
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:
Example:
D("example.com", .... ,
);
Purge is the default, but we set it anyway:
Example:
D("example.com", .... ,
PURGE,
);
Since the “last command wins”, this is the same as PURGE
:
Example:
D("example.com", .... ,
PURGE,
NO_PURGE,
PURGE,
NO_PURGE,
PURGE,
);
R53_ALIAS( name, target, ZONE_ID modifier )
R53_ALIAS is a Route53 specific virtual record type that points a record at either another record or an AWS entity (like a Cloudfront distribution, an ELB, etc…). It is analogous to a CNAME, but is usually resolved at request-time and served as an A record. Unlike CNAMEs, ALIAS records can be used at the zone apex (@
)
Unlike the regular ALIAS directive, R53_ALIAS is only supported on Route53. Attempting to use R53_ALIAS on another provider than Route53 will result in an error.
The name should be the relative label for the domain.
Target should be a string representing the 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 .
.
The Target can be any of:
For all the target type, excluding ‘another record’, you have to specify the Zone ID
of the target. This is done by using the R53_ZONE
record modifier.
The zone id can be found depending on the target type:
Z2FDTNDATAQYW2
Example:
D('example.com', REGISTRAR, DnsProvider('ROUTE53'),
R53_ALIAS('foo', 'A', 'bar'), // record in same zone
R53_ALIAS('foo', 'A', 'bar', R53_ZONE('Z35SXDOTRQ7X7K')), // record in same zone, zone specified
R53_ALIAS('foo', 'A', 'blahblah.elasticloadbalancing.us-west-1.amazonaws.com.', R53_ZONE('Z368ELLRRE2KJ0')), // a classic ELB in us-west-1
R53_ALIAS('foo', 'A', 'blahblah.elasticbeanstalk.us-west-2.amazonaws.com.', R53_ZONE('Z38NKT9BP95V3O')), // an Elastic Beanstalk environment in us-west-2
R53_ALIAS('foo', 'A', 'blahblah-bucket.s3-website-us-west-1.amazonaws.com.', R53_ZONE('Z2F56UZL2M1ACD')), // a website S3 Bucket in us-west-1
);
SOA( name, ns, mbox, refresh, retry, expire, minttl, modifiers... )
SOA
adds an SOA
record to a domain. The name should be @
. ns and mbox are strings. The other fields are unsigned 32-bit ints.
Example:
D("example.com", REG_THIRDPARTY, DnsProvider("DNS_BIND"),
SOA("@", "ns3.example.org.", "hostmaster.example.org.", 3600, 600, 604800, 1440),
);
SOA()
.SOA()
statements.There is more info about SOA in the documentation for the BIND provider.
SRV( name, priority, weight, port, target, modifiers... )
SRV
adds a SRV
record to a domain. The name should be the relative label for the record.
Priority, weight, and port are ints.
Example:
D("example.com", REGISTRAR, DnsProvider("GCLOUD"),
// Create SRV records for a a SIP service:
// pr w port, target
SRV('_sip._tcp', 10, 60, 5060, 'bigbox.example.tld.'),
SRV('_sip._tcp', 10, 20, 5060, 'smallbox1.example.tld.'),
);
SSHFP( name, algorithm, type, value, modifiers... )
SSHFP contains a fingerprint of a SSH server which can be validated before SSH clients are establishing the connection.
Algorithm (type of the key) | ID | Algorithm | |—-|———–| | 0 | reserved | | 1 | RSA | | 2 | DSA | | 3 | ECDSA | | 4 | ED25519 |
Type (fingerprint format) | ID | Algorithm | |—-|———–| | 0 | reserved | | 1 | SHA-1 | | 2 | SHA-256 |
value
is the fingerprint as a string.
Example:
SSHFP('@', 1, 1, '00yourAmazingFingerprint00'),
TLSA( name, usage, selector, type, certificate, modifiers... )
TLSA adds a TLSA record to a domain. The name should be the relative label for the record.
Usage, selector, and type are ints.
Certificate is a hex string.
Example:
D("example.com", REGISTRAR, DnsProvider("GCLOUD"),
// Create TLSA record for certificate used on TCP port 443
TLSA("_443._tcp", 3, 1, 1, "abcdef0"),
);
TXT( 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 either a single or multiple strings. To specify multiple strings, specify them as an array.
Each 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.
Modifiers can be any number of record modifiers or json objects, which will be merged into the record’s metadata.
Example:
D("example.com", REGISTRAR, ....,
TXT('@', '598611146-3338560'),
TXT('listserve', 'google-site-verification=12345'),
TXT('multiple', ['one', 'two', 'three']), // Multiple strings
TXT('quoted', 'any "quotes" and escapes? ugh; no worries!'),
TXT('_domainkey', 't=y; o=-;'), // Escapes are done for you automatically.
TXT('long', 'X'.repeat(300)) // Long strings are split automatically.
);
NOTE: In the past, long strings had to be annotated with the keyword
AUTOSPLIT
. This is no longer required. The keyword is now a no-op.
Strings that are longer than 255 octets (bytes) will be quietly split into 255-octets chunks or the provider may report an error if it does not handle multiple strings.
Most providers do not support the full possibilities of what a TXT record can store. DNSControl can not handle all the edge cases and incompatibles that providers have introduced. Instead, it stores the string(s) that you provide and passes them to the provider verbatim. The provider may opt to accept the data, fix it, or reject it. This happens early in the processing, long before the DNSControl talks to the provider’s API.
The RFCs specify that a TXT record stores one or more strings, each is up to 255 octets (bytes) long. We call these individual strings chunks. Each chunk may be zero to 255 octets long. There is no limit to the number of chunks in a TXT record, other than IP packet length restrictions. The contents of each chunk may be octets of value from 0x00 to 0xff.
In reality DNS Service Providers (DSPs) place many restrictions on TXT records.
Some DSPs only support a single string of 255 octets or fewer. Multiple strings, or any one string being longer than 255 octets will result in an error. One provider limits the string to 254 octets, which makes me think they’re code has an off-by-one error.
Some DSPs only support one string, but it may be of any length. Behind the scenes the provider splits it into 255-octet chunks (except the last one, of course).
Some DSPs support multiple strings, but API requests must be 512-bytes or fewer, and with quoting, escaping, and other encoding mishegoss you can’t be sure what will be permitted until you actually try it.
Regardless of the quantity and length of strings, some providers ban double quotes, back-ticks, or other chars.
TXT()
record?Include the TXT()
record in a D()
as usual, along
with the DnsProvider()
for that provider. Run dnscontrol check
to
see if any errors are produced. The check command does not talk to
the provider’s API, thus permitting you to do this without having an
account at that provider.
Suppose I can create the TXT record using the DSP’s web portal but DNSControl rejects the string?
It is possible that the provider code in DNSControl rejects strings that the DSP accepts. This is because the test is done in code, not by querying the provider’s API. It is possible that the code was written to work around a bug (such as rejecting a string with a back-tick) but now that bug has been fixed.
All such checks are in providers/${providername}/auditrecords.go
.
You can try removing the check that you feel is in error and see if
the provider’s API accepts the record. You can do this by running the
integration tests, or by simply adding that record to an existing
dnsconfig.js
and seeing if dnscontrol push
is able to push that
record into production. (Be careful if you are testing this on a
domain used in production.)
URL( name, modifiers... )
Documentation needed.
URL301( name, modifiers... )
Documentation needed.
( )
dnscontrol contains a DMARC_BUILDER which can be used to simply create DMARC policies for your domains.
DMARC_BUILDER({
policy: 'reject',
ruf: [
'mailto:mailauth-reports@example.com',
],
})
This yield the following record:
@ IN TXT "v=DMARC1; p=reject; ruf=mailto:mailauth-reports@example.com"
DMARC_BUILDER({
policy: 'reject',
subdomainPolicy: 'quarantine',
percent: 50,
alignmentSPF: 'r',
alignmentDKIM: 'strict',
rua: [
'mailto:mailauth-reports@example.com',
'https://dmarc.example.com/submit',
],
ruf: [
'mailto:mailauth-reports@example.com',
],
failureOptions: '1',
reportInterval: '1h',
}),
DMARC_BUILDER({
label: 'insecure',
policy: 'none',
ruf: [
'mailto:mailauth-reports@example.com',
],
failureOptions: {
SPF: false,
DKIM: true,
},
})
This yields the following records:
@ IN TXT "v=DMARC1; p=reject; sp=quarantine; adkim=s; aspf=r; pct=50; rua=mailto:mailauth-reports@example.com,https://dmarc.example.com/submit; ruf=mailto:mailauth-reports@example.com; fo=1; ri=3600"
insecure IN TXT "v=DMARC1; p=none; ruf=mailto:mailauth-reports@example.com; fo=d"
label:
The DNS label for the DMARC record (_dmarc
prefix is added, default: '@'
)version:
The DMARC version to be used (default: DMARC1
)policy:
The DMARC policy (p=
), must be one of 'none'
, 'quarantine'
, 'reject'
subdomainPolicy:
The DMARC policy for subdomains (sp=
), must be one of 'none'
, 'quarantine'
, 'reject'
(optional)alignmentSPF:
'strict'
/'s'
or 'relaxed'
/'r'
alignment for SPF (aspf=
, default: 'r'
)alignmentDKIM:
'strict'
/'s'
or 'relaxed'
/'r'
alignment for DKIM (adkim=
, default: 'r'
)percent:
Number between 0
and 100
, percentage for which policies are applied (pct=
, default: 100
)rua:
Array of aggregate report targets (optional)ruf:
Array of failure report targets (optional)failureOptions:
Object or string; Object containing booleans SPF
and DKIM
, string is passed raw (fo=
, default: '0'
)failureFormat:
Format in which failure reports are requested (rf=
, default: 'afrf'
)reportInterval:
Interval in which reports are requested (ri=
)ttl:
Input for TTL
method (optional)AUTOSPLIT
.rua
and ruf
arrays are passed raw. You must percent-encode all commas and exclamation points in the URI itself.
R53_ZONE( zone_id )
R53_ZONE lets you specify the AWS Zone ID for an entire domain (D()) or a specific R53_ALIAS() record.
When used with D(), it sets the zone id of the domain. This can be used to differentiate between split horizon domains in public and private zones.
When used with R53_ALIAS() it sets the required Route53 hosted zone id in a R53_ALIAS record. See https://stackexchange.github.io/dnscontrol/js#R53_ALIAS for details.
TTL( ttl )
TTL sets the TTL for a single record only. This will take precedence over the domain’s DefaultTTL if supplied.
The value can be:
600
5m
14400
or '4h'
?Example:
D('example.com', REGISTRAR, DnsProvider('R53'),
DefaultTTL(2000),
A('@','1.2.3.4'), // uses default
A('foo', '2.3.4.5', TTL(500)), // overrides default
A('demo1', '3.4.5.11', TTL('5d')), // 5 days
A('demo2', '3.4.5.12', TTL('5w')), // 5 weeks
);