Javascript DSL

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.

Top Level Functions

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 approprate D(REV() domain (i.e. .arpa domain) has been defined.

NewRegistrar( name, type, meta ) -> string

NewRegistrar registers a registrar provider. The name can be any string value you would like to use. The type must match a valid registar provider type identifer (see provider page.)

Metadata is an optional object, that will only be used by certain providers. See individual provider docs for specific details.

This function will return the name as a string so that you may assign it to a variable to use inside D directives.

Example:

var REGISTRAR = NewRegistrar("name.com", "NAMEDOTCOM");
var r53 = NewDnsProvider("R53","ROUTE53");

D("example.com", REGISTRAR, DnsProvider(r53), A("@","1.2.3.4"));

NewDnsProvider( name, type, meta ) -> string

NewDnsProvider registers a new DNS Service Provider. The name can be any string value you would like to use. The type must match a valid dns provider type identifer (see provider page.)

Metadata is an optional object, that will only be used by certain providers. See individual provider docs for specific details.

This function will return the name as a string so that you may assign it to a variable to use inside D directives.

Example:

var REGISTRAR = NewRegistrar("name.com", "NAMEDOTCOM");
var r53 = NewDnsProvider("R53","ROUTE53");

D("example.com", REGISTRAR, DnsProvider(r53), A("@","1.2.3.4"));

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","BIND");
// 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:

  • A function argument will be called with the domain object as it’s only argument. Most of the built-in modifier functions return such functions.
  • An object argument will be merged into the domain’s metadata collection.
  • An array arument will have all of it’s members evaluated recursively. This allows you to combine multiple common records or modifiers into a variable that can be used like a macro in multiple domains.

Example:

var REGISTRAR = NewRegistrar("name.com", "NAMEDOTCOM");
var r53 = NewDnsProvider("R53","ROUTE53");

// 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
);

Domain Modifiers

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.

Modifers 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.

Modifers 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})
);

ALIAS( name, target, modifiers... )

ALIAS is a virtual record type that points a record at another record. It is analagous 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
);

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, similer to TXT records. For example use CAA("@", "issue", "letsencrypt.org") rather than CAA("@", "issue", "\"letsencrypt.org\"").

Flags are controlled by modifier.:

  • CAA_CRITICAL: Issuer critical flag. CA that does not understand this tag will refuse to issue certificate for this domain.

CAA record is supported only by BIND, Google Cloud DNS, and Amazon Route 53. 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)
);

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.subdomain"), // def.example.com -> test.subdomain.example.com
);

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](#TTL), an integer number of seconds or a string with a unit such as `'4d'`.

DnsProvider( name, nsCount )

DnsProvider indicates that the specifid 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.

IGNORE( )

IGNORE can be used to ignore some records presents in zone. All records (independently of their type) of that name will be completely ignored.

IGNORE is like NO_PURGE except it acts only on some specific records intead of the whole zone.

IGNORE is generally used in very specific situations:

  • Some records are managed by some other system and DNSControl is only used to manage some records and/or keep them updated. For example a DNS record that is managed by Kubernetes External DNS, but DNSControl is used to manage the rest of the zone. In this case we don’t want dnscontrol to try to delete the externally managed record.
  • 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. IGNORE 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("foo"),
  IGNORE("bar"),
  A("baz", "1.2.3.4")
);

It is considered as an error to try to manage an ignored record.

IMPORT_TRANSFORM( 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.

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:

  • 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.

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, 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.

Example:

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"),
);

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.

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. 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 ..

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 approprate .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 analagous 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:

  • CloudFront distribution: in this case specify the domain name that CloudFront assigned whenyou created your distribution (note that your CloudFront distribution must include an alternante domain name that matches the record you’re adding)
  • Elastic Beanstalk environment: specify the CNAME attribute for the environment. The environment must have a regionalized domain name. To get the CNAME, you can use either the AWS Console, AWS Elastic Beanstalk API, or the AWS CLI.
  • ELB load balancer: specify the DNS name that is associated with the load balancer. To get the DNS name you can use either the AWS Console (on the EC2 page, choose Load Balancers, select the right one, choose the description tab), ELB API, the AWS ELB CLI, or the AWS ELBv2 CLI.
  • S3 bucket (configured as website): specify the domain name of the Amazon S3 website endpoint in which you configured the bucket (for instance s3-website-us-east-2.amazonaws.com). For the available values refer to the Amazon S3 Website Endpoints.
  • Another Route53 record: specify the value of the name of another record in the same hosted zone.

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:

  • CloudFront distribution: specify Z2FDTNDATAQYW2
  • Elastic Beanstalk environment: specify the hosted zone ID for the region in which the environment has been created. Refer to the List of regions and hosted Zone IDs.
  • ELB load balancer: specify the value of the hosted zone ID for the load balancer. You can find it in the List of regions and hosted Zone IDs
  • S3 bucket (configured as website): specify the hosted zone ID for the region that you created the bucket in. You can find it in the List of regions and hosted Zone IDs
  • Another Route 53 record: you can either specify the correct zone id or do not specify anything and dnscontrol will figure out the right zone id. (Note: Route53 alias can’t reference a record in a different zone).

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
);

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, include them in an array.

TXT records with multiple strings are only supported by some providers. DNSControl will produce a validation error if the provider does not support multiple strings.

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.

Modifers 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.
);

Record Modifiers

R53_ZONE( zone_id )

R53_ZONE sets the required Route53 hosted zone id in a R53_ALIAS record.

This directive has no impact when used in anything else than a R53_ALIAS.

Please refer to the R53_ALIAS directive for usage.

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:

  • An integer (number of seconds). Example: 600
  • A string: Integer with single-letter unit: Example: 5m
  • The unit denotes:
    • s (seconds)
    • m (minutes)
    • h (hours)
    • d (days)
    • w (weeks)
    • n (nonths) (30 days in a nonth)
    • y (years) (If you set a TTL to a year, we assume you also do crossword puzzles in pen. Show off!)
    • If no unit is specified, the default is seconds.
  • We highly recommend using units instead of the number of seconds. Would your coworkers understand your intention better if you wrote 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
);