From 05be3b83edbd67d2ad560e998a33342ff71fdc8e Mon Sep 17 00:00:00 2001 From: Jeffrey Cafferata Date: Mon, 13 Mar 2023 21:30:21 +0100 Subject: [PATCH] DOCS: Added GitBook code blocks syntax for `dnsconfig.js`. (#2149) Co-authored-by: Tom Limoncelli --- documentation/functions/domain/A.md | 2 ++ documentation/functions/domain/AAAA.md | 2 ++ documentation/functions/domain/ALIAS.md | 2 ++ documentation/functions/domain/AUTODNSSEC_ON.md | 2 ++ documentation/functions/domain/AZURE_ALIAS.md | 2 ++ documentation/functions/domain/CAA.md | 2 ++ documentation/functions/domain/CF_REDIRECT.md | 2 ++ documentation/functions/domain/CF_TEMP_REDIRECT.md | 2 ++ documentation/functions/domain/CF_WORKER_ROUTE.md | 2 ++ documentation/functions/domain/CNAME.md | 2 ++ documentation/functions/domain/DS.md | 2 ++ documentation/functions/domain/DefaultTTL.md | 2 ++ documentation/functions/domain/IGNORE_NAME.md | 2 ++ documentation/functions/domain/IGNORE_TARGET.md | 2 ++ documentation/functions/domain/IMPORT_TRANSFORM.md | 2 ++ documentation/functions/domain/INCLUDE.md | 2 ++ documentation/functions/domain/MX.md | 2 ++ documentation/functions/domain/NAMESERVER.md | 4 ++++ documentation/functions/domain/NAMESERVER_TTL.md | 7 ++++++- documentation/functions/domain/NO_PURGE.md | 2 ++ documentation/functions/domain/NS.md | 2 ++ documentation/functions/domain/PTR.md | 10 ++++++++++ documentation/functions/domain/PURGE.md | 6 ++++++ documentation/functions/domain/R53_ALIAS.md | 2 ++ documentation/functions/domain/SOA.md | 2 ++ documentation/functions/domain/SRV.md | 2 ++ documentation/functions/domain/SSHFP.md | 2 ++ documentation/functions/domain/TLSA.md | 2 ++ documentation/functions/domain/TXT.md | 2 ++ documentation/functions/global/D.md | 4 ++++ documentation/functions/global/DEFAULTS.md | 4 ++++ documentation/functions/global/DOMAIN_ELSEWHERE.md | 4 ++++ .../functions/global/DOMAIN_ELSEWHERE_AUTO.md | 4 ++++ documentation/functions/global/D_EXTEND.md | 2 ++ documentation/functions/global/FETCH.md | 2 ++ documentation/functions/global/IP.md | 4 ++++ documentation/functions/global/NewDnsProvider.md | 4 ++++ documentation/functions/global/NewRegistrar.md | 4 ++++ documentation/functions/global/PANIC.md | 2 ++ documentation/functions/global/REV.md | 2 ++ .../functions/global/getConfiguredDomains.md | 4 ++++ documentation/functions/global/require_glob.md | 4 ++++ documentation/functions/record/CAA_BUILDER.md | 4 ++++ documentation/functions/record/DMARC_BUILDER.md | 12 ++++++++++-- documentation/functions/record/SPF_BUILDER.md | 8 ++++++++ documentation/functions/record/TTL.md | 2 ++ documentation/providers/axfrddns.md | 4 +++- documentation/providers/vultr.md | 2 +- 48 files changed, 148 insertions(+), 5 deletions(-) diff --git a/documentation/functions/domain/A.md b/documentation/functions/domain/A.md index 09948f37e..28eac0937 100644 --- a/documentation/functions/domain/A.md +++ b/documentation/functions/domain/A.md @@ -16,6 +16,7 @@ The address should be an ip address, either a string, or a numeric value obtaine Modifiers can be any number of [record modifiers](https://docs.dnscontrol.org/language-reference/record-modifiers) or JSON objects, which will be merged into the record's metadata. +{% code title="dnsconfig.js" %} ```javascript D("example.com", REGISTRAR, DnsProvider("R53"), A("@", "1.2.3.4"), @@ -24,3 +25,4 @@ D("example.com", REGISTRAR, DnsProvider("R53"), A("*", "1.2.3.4", {foo: 42}) ); ``` +{% endcode %} diff --git a/documentation/functions/domain/AAAA.md b/documentation/functions/domain/AAAA.md index 009b85432..05eeae9ae 100644 --- a/documentation/functions/domain/AAAA.md +++ b/documentation/functions/domain/AAAA.md @@ -16,6 +16,7 @@ The address should be an IPv6 address as a string. Modifiers can be any number of [record modifiers](https://docs.dnscontrol.org/language-reference/record-modifiers) or JSON objects, which will be merged into the record's metadata. +{% code title="dnsconfig.js" %} ```javascript var addrV6 = "2001:0db8:85a3:0000:0000:8a2e:0370:7334" @@ -26,3 +27,4 @@ D("example.com", REGISTRAR, DnsProvider("R53"), AAAA("*", addrV6, {foo: 42}) ); ``` +{% endcode %} diff --git a/documentation/functions/domain/ALIAS.md b/documentation/functions/domain/ALIAS.md index 707f7ffea..d7a18d18d 100644 --- a/documentation/functions/domain/ALIAS.md +++ b/documentation/functions/domain/ALIAS.md @@ -18,8 +18,10 @@ 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 `.`. +{% code title="dnsconfig.js" %} ```javascript D("example.com", REGISTRAR, DnsProvider("CLOUDFLARE"), ALIAS("@", "google.com."), // example.com -> google.com ); ``` +{% endcode %} diff --git a/documentation/functions/domain/AUTODNSSEC_ON.md b/documentation/functions/domain/AUTODNSSEC_ON.md index 99395fd65..e60ecc438 100644 --- a/documentation/functions/domain/AUTODNSSEC_ON.md +++ b/documentation/functions/domain/AUTODNSSEC_ON.md @@ -19,6 +19,7 @@ data model. correct syntax is `AUTODNSSEC_ON` not `AUTODNSSEC_ON()` {% endhint %} +{% code title="dnsconfig.js" %} ```javascript D("example.com", .... , AUTODNSSEC_ON, // Enable AutoDNSSEC. @@ -30,6 +31,7 @@ D("insecure.com", .... , A("@", "10.2.2.2") ); ``` +{% endcode %} If neither `AUTODNSSEC_ON` or `AUTODNSSEC_OFF` is specified for a domain no changes will be requested. diff --git a/documentation/functions/domain/AZURE_ALIAS.md b/documentation/functions/domain/AZURE_ALIAS.md index c0da34321..414d5124c 100644 --- a/documentation/functions/domain/AZURE_ALIAS.md +++ b/documentation/functions/domain/AZURE_ALIAS.md @@ -48,9 +48,11 @@ Alias records can reference other record sets of the same type. For example, a DNS CNAME record set can be an alias to another CNAME record set. This arrangement is useful if you want some record sets to be aliases and some non-aliases. +{% code title="dnsconfig.js" %} ```javascript 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 ); ``` +{% endcode %} diff --git a/documentation/functions/domain/CAA.md b/documentation/functions/domain/CAA.md index 382195cc0..8509a1df4 100644 --- a/documentation/functions/domain/CAA.md +++ b/documentation/functions/domain/CAA.md @@ -24,6 +24,7 @@ Value is a string. The format of the contents is different depending on the tag. 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. +{% code title="dnsconfig.js" %} ```javascript D("example.com", REGISTRAR, DnsProvider("GCLOUD"), // Allow letsencrypt to issue certificate for this domain @@ -35,5 +36,6 @@ D("example.com", REGISTRAR, DnsProvider("GCLOUD"), CAA("@", "iodef", "mailto:test@example.com", CAA_CRITICAL) ); ``` +{% endcode %} DNSControl contains a [`CAA_BUILDER`](../record/CAA_BUILDER.md) which can be used to simply create `CAA()` records for your domains. Instead of creating each CAA record individually, you can simply configure your report mail address, the authorized certificate authorities and the builder cares about the rest. diff --git a/documentation/functions/domain/CF_REDIRECT.md b/documentation/functions/domain/CF_REDIRECT.md index b98e1d09a..e9e72d19c 100644 --- a/documentation/functions/domain/CF_REDIRECT.md +++ b/documentation/functions/domain/CF_REDIRECT.md @@ -33,8 +33,10 @@ 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: +{% code title="dnsconfig.js" %} ```javascript D("foo.com", .... , CF_REDIRECT("mydomain.com/*", "https://www.mydomain.com/$1"), ); ``` +{% endcode %} diff --git a/documentation/functions/domain/CF_TEMP_REDIRECT.md b/documentation/functions/domain/CF_TEMP_REDIRECT.md index 123c7968b..361ba8995 100644 --- a/documentation/functions/domain/CF_TEMP_REDIRECT.md +++ b/documentation/functions/domain/CF_TEMP_REDIRECT.md @@ -26,8 +26,10 @@ backups and manually verifying `dnscontrol preview` output before running managed by DNSControl and those that aren't. {% endhint %} +{% code title="dnsconfig.js" %} ```javascript D("foo.com", .... , CF_TEMP_REDIRECT("example.mydomain.com/*", "https://otherplace.yourdomain.com/$1"), ); ``` +{% endcode %} diff --git a/documentation/functions/domain/CF_WORKER_ROUTE.md b/documentation/functions/domain/CF_WORKER_ROUTE.md index d3270277e..990b5b802 100644 --- a/documentation/functions/domain/CF_WORKER_ROUTE.md +++ b/documentation/functions/domain/CF_WORKER_ROUTE.md @@ -25,9 +25,11 @@ backups and manually verifying `dnscontrol preview` output before running This example assigns the patterns `api.foo.com/*` and `foo.com/api/*` to a `my-worker` script: +{% code title="dnsconfig.js" %} ```javascript D("foo.com", .... , CF_WORKER_ROUTE("api.foo.com/*", "my-worker"), CF_WORKER_ROUTE("foo.com/api/*", "my-worker"), ); ``` +{% endcode %} diff --git a/documentation/functions/domain/CNAME.md b/documentation/functions/domain/CNAME.md index 5b28f247f..0d5b6a222 100644 --- a/documentation/functions/domain/CNAME.md +++ b/documentation/functions/domain/CNAME.md @@ -15,6 +15,7 @@ Using `@` or `*` for CNAME records is not recommended, as different providers su 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 `.`. +{% code title="dnsconfig.js" %} ```javascript D("example.com", REGISTRAR, DnsProvider("R53"), CNAME("foo", "google.com."), // foo.example.com -> google.com @@ -22,3 +23,4 @@ D("example.com", REGISTRAR, DnsProvider("R53"), CNAME("def", "test"), // def.example.com -> test.example.com ); ``` +{% endcode %} diff --git a/documentation/functions/domain/DS.md b/documentation/functions/domain/DS.md index d6381ec2f..63305cde6 100644 --- a/documentation/functions/domain/DS.md +++ b/documentation/functions/domain/DS.md @@ -26,8 +26,10 @@ Digest Type must be a number. Digest must be a string. +{% code title="dnsconfig.js" %} ```javascript D("example.com", REGISTRAR, DnsProvider(R53), DS("example.com", 2371, 13, 2, "ABCDEF") ); ``` +{% endcode %} diff --git a/documentation/functions/domain/DefaultTTL.md b/documentation/functions/domain/DefaultTTL.md index 8a82fbc71..1b45326b7 100644 --- a/documentation/functions/domain/DefaultTTL.md +++ b/documentation/functions/domain/DefaultTTL.md @@ -12,6 +12,7 @@ the record will inherit the DNSControl global internal default of 300 seconds. S NS records are currently a special case, and do not inherit from `DefaultTTL`. See [`NAMESERVER_TTL`](../domain/NAMESERVER_TTL.md) to set a default TTL for all NS records. +{% code title="dnsconfig.js" %} ```javascript D('example.com', REGISTRAR, DnsProvider('R53'), DefaultTTL("4h"), @@ -19,6 +20,7 @@ D('example.com', REGISTRAR, DnsProvider('R53'), A('foo', '2.3.4.5', TTL(600)) // overrides default ); ``` +{% endcode %} The DefaultTTL duration is the same format as [`TTL`](../record/TTL.md), an integer number of seconds or a string with a unit such as `'4d'`. diff --git a/documentation/functions/domain/IGNORE_NAME.md b/documentation/functions/domain/IGNORE_NAME.md index 20367484c..7cd9ab46b 100644 --- a/documentation/functions/domain/IGNORE_NAME.md +++ b/documentation/functions/domain/IGNORE_NAME.md @@ -28,6 +28,7 @@ Technically `IGNORE_NAME` is a promise that DNSControl will not add, change, or 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. +{% code title="dnsconfig.js" %} ```javascript D("example.com", IGNORE_NAME("foo"), // ignore all record types for name foo @@ -37,6 +38,7 @@ D("example.com", A("baz", "1.2.3.4") ); ``` +{% endcode %} `IGNORE_NAME` also supports glob patterns in the style of the [gobwas/glob](https://github.com/gobwas/glob) library. All of the following patterns will work: diff --git a/documentation/functions/domain/IGNORE_TARGET.md b/documentation/functions/domain/IGNORE_TARGET.md index 0bc1ac8ea..346e8d233 100644 --- a/documentation/functions/domain/IGNORE_TARGET.md +++ b/documentation/functions/domain/IGNORE_TARGET.md @@ -24,12 +24,14 @@ 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. +{% code title="dnsconfig.js" %} ```javascript D("example.com", IGNORE_TARGET('**.acm-validations.aws.', 'CNAME'), A("baz", "1.2.3.4") ); ``` +{% endcode %} IGNORE_TARGET also supports glob patterns in the style of the [gobwas/glob](https://github.com/gobwas/glob#example) library. Some example patterns: diff --git a/documentation/functions/domain/IMPORT_TRANSFORM.md b/documentation/functions/domain/IMPORT_TRANSFORM.md index ee7f5d426..669d4d188 100644 --- a/documentation/functions/domain/IMPORT_TRANSFORM.md +++ b/documentation/functions/domain/IMPORT_TRANSFORM.md @@ -43,6 +43,7 @@ bar.com: Here's how you'd implement this in DNSControl: +{% code title="dnsconfig.js" %} ```javascript var TRANSFORM_INT = [ // RANGE_START, RANGE_END, NEW_BASE @@ -62,6 +63,7 @@ D("bar.com", .... , IMPORT_TRANSFORM(TRANSFORM_INT, 'foo.com', 300), ); ``` +{% endcode %} Transform rules are: RANGE_START, RANGE_END, NEW_BASE. NEW_BASE may be: diff --git a/documentation/functions/domain/INCLUDE.md b/documentation/functions/domain/INCLUDE.md index 0e7e205a3..27655c6b8 100644 --- a/documentation/functions/domain/INCLUDE.md +++ b/documentation/functions/domain/INCLUDE.md @@ -9,6 +9,7 @@ parameter_types: Includes all records from a given domain +{% code title="dnsconfig.js" %} ```javascript D("example.com!external", REGISTRAR, DnsProvider(R53), A("test", "8.8.8.8") @@ -19,3 +20,4 @@ D("example.com!internal", REGISTRAR, DnsProvider(R53), A("home", "127.0.0.1") ); ``` +{% endcode %} diff --git a/documentation/functions/domain/MX.md b/documentation/functions/domain/MX.md index d90b95eca..c1fa82d78 100644 --- a/documentation/functions/domain/MX.md +++ b/documentation/functions/domain/MX.md @@ -18,9 +18,11 @@ 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 `.`. +{% code title="dnsconfig.js" %} ```javascript D("example.com", REGISTRAR, DnsProvider(R53), MX("@", 5, "mail"), // mx example.com -> mail.example.com MX("sub", 10, "mail.foo.com.") ); ``` +{% endcode %} diff --git a/documentation/functions/domain/NAMESERVER.md b/documentation/functions/domain/NAMESERVER.md index fa9330a4b..e8cfd56eb 100644 --- a/documentation/functions/domain/NAMESERVER.md +++ b/documentation/functions/domain/NAMESERVER.md @@ -20,6 +20,7 @@ delegations. `NAMESERVER()` is for informing upstream delegations. For more information, refer to [this page](../../nameservers.md). +{% code title="dnsconfig.js" %} ```javascript D("example.com", REGISTRAR, .... , DnsProvider(route53, 0), @@ -34,6 +35,7 @@ D("example2.com", REGISTRAR, .... , NAMESERVER("ns2.myserver.com."), ); ``` +{% endcode %} # The difference between NS() and NAMESERVER() @@ -78,9 +80,11 @@ special Registrar called "NONE". It makes no changes. It looks like this: +{% code title="dnsconfig.js" %} ```javascript var REG_THIRDPARTY = NewRegistrar('ThirdParty', 'NONE') D("mydomain.com", REG_THIRDPARTY, ... ) ``` +{% endcode %} diff --git a/documentation/functions/domain/NAMESERVER_TTL.md b/documentation/functions/domain/NAMESERVER_TTL.md index 8a5059f4f..af336263d 100644 --- a/documentation/functions/domain/NAMESERVER_TTL.md +++ b/documentation/functions/domain/NAMESERVER_TTL.md @@ -12,14 +12,18 @@ NAMESERVER_TTL sets the TTL on the domain apex NS RRs defined by [`NAMESERVER`]( The value can be an integer or a string. See [`TTL`](../record/TTL.md) for examples. +{% code title="dnsconfig.js" %} ```javascript D('example.com', REGISTRAR, DnsProvider('R53'), NAMESERVER_TTL('2d'), NAMESERVER('ns') ); ``` +{% endcode %} Use `NAMESERVER_TTL('3600'),` or `NAMESERVER_TTL('1h'),` for a 1h default TTL for all subsequent `NS` entries: + +{% code title="dnsconfig.js" %} ```javascript D('example.com', REGISTRAR, DnsProvider('xyz'), DefaultTTL("4h"), @@ -30,5 +34,6 @@ D('example.com', REGISTRAR, DnsProvider('xyz'), A('foo', '2.3.4.5', TTL(600)) // overrides DefaultTTL for this record only ); ``` +{% endcode %} -To apply a default TTL to all other record types, see [`DefaultTTL`](../domain/DefaultTTL.md) \ No newline at end of file +To apply a default TTL to all other record types, see [`DefaultTTL`](../domain/DefaultTTL.md) diff --git a/documentation/functions/domain/NO_PURGE.md b/documentation/functions/domain/NO_PURGE.md index 596e5abf0..7706285eb 100644 --- a/documentation/functions/domain/NO_PURGE.md +++ b/documentation/functions/domain/NO_PURGE.md @@ -15,11 +15,13 @@ 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. +{% code title="dnsconfig.js" %} ```javascript D("example.com", .... , NO_PURGE, A("foo","1.2.3.4") ); ``` +{% endcode %} The main caveat of NO_PURGE is that intentionally deleting records becomes more difficult. Suppose a NO_PURGE zone has an record such diff --git a/documentation/functions/domain/NS.md b/documentation/functions/domain/NS.md index 66aea4dfa..b5332434a 100644 --- a/documentation/functions/domain/NS.md +++ b/documentation/functions/domain/NS.md @@ -18,6 +18,7 @@ The difference between `NS()` and [`NAMESERVER()`](NAMESERVER.md) is explained i 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 `.`. +{% code title="dnsconfig.js" %} ```javascript D("example.com", REGISTRAR, DnsProvider("R53"), NS("foo", "ns1.example2.com."), // Delegate ".foo.example.com" zone to another server. @@ -26,3 +27,4 @@ D("example.com", REGISTRAR, DnsProvider("R53"), A("ns2.example2.com", "10.10.10.20"), // Glue records ); ``` +{% endcode %} diff --git a/documentation/functions/domain/PTR.md b/documentation/functions/domain/PTR.md index 09c167771..e7c8b27b1 100644 --- a/documentation/functions/domain/PTR.md +++ b/documentation/functions/domain/PTR.md @@ -60,6 +60,7 @@ 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` +{% code title="dnsconfig.js" %} ```javascript D(REV('1.2.3.0/24'), REGISTRAR, DnsProvider(BIND), PTR('1', 'foo.example.com.'), @@ -68,11 +69,19 @@ D(REV('1.2.3.0/24'), REGISTRAR, DnsProvider(BIND), // If the first parameter is a valid IP address, DNSControl will generate the correct name: PTR('1.2.3.10', 'ten.example.com.'), // '10' ); +``` +{% endcode %} +{% code title="dnsconfig.js" %} +```javascript D(REV('9.9.9.128/25'), REGISTRAR, DnsProvider(BIND), PTR('9.9.9.129', 'first.example.com.'), ); +``` +{% endcode %} +{% code title="dnsconfig.js" %} +```javascript 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: @@ -80,6 +89,7 @@ D(REV('2001:db8:302::/48'), REGISTRAR, DnsProvider(BIND), 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' ); ``` +{% endcode %} 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 diff --git a/documentation/functions/domain/PURGE.md b/documentation/functions/domain/PURGE.md index 1e4baae2e..4e30d0428 100644 --- a/documentation/functions/domain/PURGE.md +++ b/documentation/functions/domain/PURGE.md @@ -12,21 +12,26 @@ These three examples all are equivalent. PURGE is the default: +{% code title="dnsconfig.js" %} ```javascript D("example.com", .... , ); ``` +{% endcode %} Purge is the default, but we set it anyway: +{% code title="dnsconfig.js" %} ```javascript D("example.com", .... , PURGE, ); ``` +{% endcode %} Since the "last command wins", this is the same as `PURGE`: +{% code title="dnsconfig.js" %} ```javascript D("example.com", .... , PURGE, @@ -36,3 +41,4 @@ D("example.com", .... , PURGE, ); ``` +{% endcode %} diff --git a/documentation/functions/domain/R53_ALIAS.md b/documentation/functions/domain/R53_ALIAS.md index a08912420..a5db2f46d 100644 --- a/documentation/functions/domain/R53_ALIAS.md +++ b/documentation/functions/domain/R53_ALIAS.md @@ -37,6 +37,7 @@ The zone id can be found depending on the target type: * _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](http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region) * _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). +{% code title="dnsconfig.js" %} ```javascript D('example.com', REGISTRAR, DnsProvider('ROUTE53'), R53_ALIAS('foo', 'A', 'bar'), // record in same zone @@ -46,3 +47,4 @@ D('example.com', REGISTRAR, DnsProvider('ROUTE53'), R53_ALIAS('foo', 'A', 'blahblah-bucket.s3-website-us-west-1.amazonaws.com.', R53_ZONE('Z2F56UZL2M1ACD')), // a website S3 Bucket in us-west-1 ); ``` +{% endcode %} diff --git a/documentation/functions/domain/SOA.md b/documentation/functions/domain/SOA.md index 1c85dae1d..89ec70ee3 100644 --- a/documentation/functions/domain/SOA.md +++ b/documentation/functions/domain/SOA.md @@ -22,11 +22,13 @@ parameter_types: `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. +{% code title="dnsconfig.js" %} ```javascript D("example.com", REG_THIRDPARTY, DnsProvider("DNS_BIND"), SOA("@", "ns3.example.org.", "hostmaster@example.org", 3600, 600, 604800, 1440), ); ``` +{% endcode %} The email address should be specified like a normal RFC822/RFC5322 address (user@hostname.com). It will be converted into the required format (e.g. BIND format: `user.hostname.com`) by the provider as required. This has the benefit of being more human-readable plus DNSControl can properly handle escaping and other issues. diff --git a/documentation/functions/domain/SRV.md b/documentation/functions/domain/SRV.md index 40fee3f54..75fd68ba3 100644 --- a/documentation/functions/domain/SRV.md +++ b/documentation/functions/domain/SRV.md @@ -20,6 +20,7 @@ parameter_types: Priority, weight, and port are ints. +{% code title="dnsconfig.js" %} ```javascript D("example.com", REGISTRAR, DnsProvider("GCLOUD"), // Create SRV records for a a SIP service: @@ -28,3 +29,4 @@ D("example.com", REGISTRAR, DnsProvider("GCLOUD"), SRV('_sip._tcp', 10, 20, 5060, 'smallbox1.example.tld.'), ); ``` +{% endcode %} diff --git a/documentation/functions/domain/SSHFP.md b/documentation/functions/domain/SSHFP.md index 0e1f28277..56f667a7c 100644 --- a/documentation/functions/domain/SSHFP.md +++ b/documentation/functions/domain/SSHFP.md @@ -36,6 +36,8 @@ SSHFP contains a fingerprint of a SSH server which can be validated before SSH c `value` is the fingerprint as a string. +{% code title="dnsconfig.js" %} ```javascript SSHFP('@', 1, 1, '00yourAmazingFingerprint00'), ``` +{% endcode %} diff --git a/documentation/functions/domain/TLSA.md b/documentation/functions/domain/TLSA.md index 2f6450d19..c3362019f 100644 --- a/documentation/functions/domain/TLSA.md +++ b/documentation/functions/domain/TLSA.md @@ -22,9 +22,11 @@ Usage, selector, and type are ints. Certificate is a hex string. +{% code title="dnsconfig.js" %} ```javascript D("example.com", REGISTRAR, DnsProvider("GCLOUD"), // Create TLSA record for certificate used on TCP port 443 TLSA("_443._tcp", 3, 1, 1, "abcdef0"), ); ``` +{% endcode %} diff --git a/documentation/functions/domain/TXT.md b/documentation/functions/domain/TXT.md index 89d25e99a..a49ddaf44 100644 --- a/documentation/functions/domain/TXT.md +++ b/documentation/functions/domain/TXT.md @@ -22,6 +22,7 @@ will be done for you. Modifiers can be any number of [record modifiers](https://docs.dnscontrol.org/language-reference/record-modifiers) or JSON objects, which will be merged into the record's metadata. +{% code title="dnsconfig.js" %} ```javascript D("example.com", REGISTRAR, ...., TXT('@', '598611146-3338560'), @@ -32,6 +33,7 @@ Modifiers can be any number of [record modifiers](https://docs.dnscontrol.org/la TXT('long', 'X'.repeat(300)) // Long strings are split automatically. ); ``` +{% endcode %} {% hint style="info" %} **NOTE**: In the past, long strings had to be annotated with the keyword diff --git a/documentation/functions/global/D.md b/documentation/functions/global/D.md index d6cb9dfdc..181ecc46a 100644 --- a/documentation/functions/global/D.md +++ b/documentation/functions/global/D.md @@ -21,6 +21,7 @@ Modifier arguments are processed according to type as follows: - An array argument 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. +{% code title="dnsconfig.js" %} ```javascript var REGISTRAR = NewRegistrar("name.com"); var r53 = NewDnsProvider("R53"); @@ -46,6 +47,7 @@ D("example.com", REGISTRAR, DnsProvider(r53), GOOGLE_APPS_DOMAIN_MX ); ``` +{% endcode %} # Split Horizon DNS @@ -58,6 +60,7 @@ To differentiate the different domains, specify the domains as `domain.tld!tag`, such as `example.com!inside` and `example.com!outside`. +{% code title="dnsconfig.js" %} ```javascript var REG = NewRegistrar("Third-Party"); var DNS_INSIDE = NewDnsProvider("Cloudflare"); @@ -75,6 +78,7 @@ D_EXTEND("example.com!inside", A("internal", "10.99.99.99") ); ``` +{% endcode %} A domain name without a `!` is assigned a tag that is the empty string. For example, `example.com` and `example.com!` are equivalent. diff --git a/documentation/functions/global/DEFAULTS.md b/documentation/functions/global/DEFAULTS.md index eb8922de8..7a81ba54e 100644 --- a/documentation/functions/global/DEFAULTS.md +++ b/documentation/functions/global/DEFAULTS.md @@ -14,6 +14,7 @@ arguments passed as if they were the first modifiers in the argument list. We want to create backup zone files for all domains, but not actually register them. Also create a [`DefaultTTL`](../domain/DefaultTTL.md). The domain `example.com` will have the defaults set. +{% code title="dnsconfig.js" %} ```javascript var COMMON = NewDnsProvider("foo"); DEFAULTS( @@ -27,10 +28,12 @@ D("example.com", A("@","1.2.3.4") ); ``` +{% endcode %} If you want to clear the defaults, you can do the following. The domain `example2.com` will **not** have the defaults set. +{% code title="dnsconfig.js" %} ```javascript DEFAULTS(); @@ -40,3 +43,4 @@ D("example2.com", A("@","1.2.3.4") ); ``` +{% endcode %} diff --git a/documentation/functions/global/DOMAIN_ELSEWHERE.md b/documentation/functions/global/DOMAIN_ELSEWHERE.md index e958d57ce..d7bff9d05 100644 --- a/documentation/functions/global/DOMAIN_ELSEWHERE.md +++ b/documentation/functions/global/DOMAIN_ELSEWHERE.md @@ -23,10 +23,13 @@ point (delegate) the domain at a specific list of DNS servers. For example these two statements are equivalent: +{% code title="dnsconfig.js" %} ```javascript DOMAIN_ELSEWHERE("example.com", REG_NAMEDOTCOM, ["ns1.foo.com", "ns2.foo.com"]); ``` +{% endcode %} +{% code title="dnsconfig.js" %} ```javascript D("example.com", REG_NAMEDOTCOM, NO_PURGE, @@ -34,6 +37,7 @@ D("example.com", REG_NAMEDOTCOM, NAMESERVER("ns2.foo.com") ); ``` +{% endcode %} {% hint style="info" %} **NOTE**: The `NO_PURGE` is used out of abundance of caution but since no diff --git a/documentation/functions/global/DOMAIN_ELSEWHERE_AUTO.md b/documentation/functions/global/DOMAIN_ELSEWHERE_AUTO.md index 5d753a2c1..110cd9062 100644 --- a/documentation/functions/global/DOMAIN_ELSEWHERE_AUTO.md +++ b/documentation/functions/global/DOMAIN_ELSEWHERE_AUTO.md @@ -28,16 +28,20 @@ hard-code them in your dnsconfig.js file. For example these two statements are equivalent: +{% code title="dnsconfig.js" %} ```javascript DOMAIN_ELSEWHERE_AUTO("example.com", REG_NAMEDOTCOM, DSP_AZURE); ``` +{% endcode %} +{% code title="dnsconfig.js" %} ```javascript D("example.com", REG_NAMEDOTCOM, NO_PURGE, DnsProvider(DSP_AZURE) ); ``` +{% endcode %} {% hint style="info" %} **NOTE**: The `NO_PURGE` is used to prevent DNSControl from changing the records. diff --git a/documentation/functions/global/D_EXTEND.md b/documentation/functions/global/D_EXTEND.md index aeb4279c2..73fb100e6 100644 --- a/documentation/functions/global/D_EXTEND.md +++ b/documentation/functions/global/D_EXTEND.md @@ -32,6 +32,7 @@ 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. +{% code title="dnsconfig.js" %} ```javascript D("domain.tld", REG, DnsProvider(DNS), A("@", "127.0.0.1"), // domain.tld @@ -56,6 +57,7 @@ D_EXTEND("sub.domain.tld", CNAME("i", "j") // i.sub.domain.tld -> j.sub.domain.tld ); ``` +{% endcode %} This will end up in the following modifications: (This output assumes the `--full` flag) diff --git a/documentation/functions/global/FETCH.md b/documentation/functions/global/FETCH.md index 905780397..7e52dcc64 100644 --- a/documentation/functions/global/FETCH.md +++ b/documentation/functions/global/FETCH.md @@ -20,6 +20,7 @@ Otherwise the syntax of `FETCH` is the same as `fetch`. > 1. 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. > 2. 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. +{% code title="dnsconfig.js" %} ```javascript var REG_NONE = NewRegistrar('none'); var DNS_BIND = NewDnsProvider('bind'); @@ -42,3 +43,4 @@ FETCH('https://example.com', { ]); }); ``` +{% endcode %} diff --git a/documentation/functions/global/IP.md b/documentation/functions/global/IP.md index 1b9c8e781..09b657367 100644 --- a/documentation/functions/global/IP.md +++ b/documentation/functions/global/IP.md @@ -9,16 +9,19 @@ return: number Converts an IPv4 address from string to an integer. This allows performing mathematical operations with the IP address. +{% code title="dnsconfig.js" %} ```javascript var addrA = IP('1.2.3.4') var addrB = addrA + 1 // addrB = 1.2.3.5 ``` +{% endcode %} {% hint style="info" %} **NOTE**: `IP()` does not accept IPv6 addresses (PRs gladly accepted!). IPv6 addresses are simply strings: {% endhint %} +{% code title="dnsconfig.js" %} ```javascript // IPv4 Var var addrA1 = IP("1.2.3.4"); @@ -27,3 +30,4 @@ var addrA2 = "1.2.3.4"; // IPv6 Var var addrAAAA = "0:0:0:0:0:0:0:0"; ``` +{% endcode %} diff --git a/documentation/functions/global/NewDnsProvider.md b/documentation/functions/global/NewDnsProvider.md index a9cc8d66f..4c9f39484 100644 --- a/documentation/functions/global/NewDnsProvider.md +++ b/documentation/functions/global/NewDnsProvider.md @@ -25,6 +25,7 @@ This function will return an opaque string that should be assigned to a variable Prior to [v3.16](../../v316.md): +{% code title="dnsconfig.js" %} ```javascript var REG_MYNDC = NewRegistrar("mynamedotcom", "NAMEDOTCOM"); var DNS_MYAWS = NewDnsProvider("myaws", "ROUTE53"); @@ -33,9 +34,11 @@ D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS), A("@","1.2.3.4") ); ``` +{% endcode %} In [v3.16](../../v316.md) and later: +{% code title="dnsconfig.js" %} ```javascript var REG_MYNDC = NewRegistrar("mynamedotcom"); var DNS_MYAWS = NewDnsProvider("myaws"); @@ -44,3 +47,4 @@ D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS), A("@","1.2.3.4") ); ``` +{% endcode %} diff --git a/documentation/functions/global/NewRegistrar.md b/documentation/functions/global/NewRegistrar.md index afbd51a81..1f0a89703 100644 --- a/documentation/functions/global/NewRegistrar.md +++ b/documentation/functions/global/NewRegistrar.md @@ -25,6 +25,7 @@ This function will return an opaque string that should be assigned to a variable Prior to [v3.16](../../v316.md): +{% code title="dnsconfig.js" %} ```javascript var REG_MYNDC = NewRegistrar("mynamedotcom", "NAMEDOTCOM"); var DNS_MYAWS = NewDnsProvider("myaws", "ROUTE53"); @@ -33,9 +34,11 @@ D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS), A("@","1.2.3.4") ); ``` +{% endcode %} In [v3.16](../../v316.md) and later: +{% code title="dnsconfig.js" %} ```javascript var REG_MYNDC = NewRegistrar("mynamedotcom"); var DNS_MYAWS = NewDnsProvider("myaws"); @@ -44,3 +47,4 @@ D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS), A("@","1.2.3.4") ); ``` +{% endcode %} diff --git a/documentation/functions/global/PANIC.md b/documentation/functions/global/PANIC.md index aaaad3f0b..181e7f163 100644 --- a/documentation/functions/global/PANIC.md +++ b/documentation/functions/global/PANIC.md @@ -9,6 +9,8 @@ ts_return: never `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. +{% code title="dnsconfig.js" %} ```javascript PANIC("Something really bad has happened"); ``` +{% endcode %} diff --git a/documentation/functions/global/REV.md b/documentation/functions/global/REV.md index cc71a0fdb..2199aebda 100644 --- a/documentation/functions/global/REV.md +++ b/documentation/functions/global/REV.md @@ -32,6 +32,7 @@ Note that the lower bits (the ones outside the netmask) must be zeros. They are zeroed out automatically. Thus, `REV('1.2.3.4/24')` is an error. This is done to catch typos. +{% code title="dnsconfig.js" %} ```javascript D(REV('1.2.3.0/24'), REGISTRAR, DnsProvider(BIND), PTR("1", 'foo.example.com.'), @@ -48,6 +49,7 @@ D(REV('2001:db8:302::/48'), REGISTRAR, DnsProvider(BIND), PTR("2001:db8:302::3", 'three.example.com.'), // 3.0.0... ); ``` +{% endcode %} 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 diff --git a/documentation/functions/global/getConfiguredDomains.md b/documentation/functions/global/getConfiguredDomains.md index 1c395e360..67cc77205 100644 --- a/documentation/functions/global/getConfiguredDomains.md +++ b/documentation/functions/global/getConfiguredDomains.md @@ -10,6 +10,7 @@ configured at the time the function is called. Calling this function early or la domains at the end of your configuration file. Example for adding records to all configured domains: +{% code title="dnsconfig.js" %} ```javascript var domains = getConfiguredDomains(); for(i = 0; i < domains.length; i++) { @@ -18,6 +19,7 @@ for(i = 0; i < domains.length; i++) { ) } ``` +{% endcode %} This will end up in following modifications: (All output assumes the `--full` flag) @@ -40,6 +42,7 @@ Example for adding DMARC report records: 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. +{% code title="dnsconfig.js" %} ```javascript var domains = getConfiguredDomains(); for(i = 0; i < domains.length; i++) { @@ -48,6 +51,7 @@ for(i = 0; i < domains.length; i++) { ); } ``` +{% endcode %} This will end up in following modifications: diff --git a/documentation/functions/global/require_glob.md b/documentation/functions/global/require_glob.md index bc83373e1..da7b4cd77 100644 --- a/documentation/functions/global/require_glob.md +++ b/documentation/functions/global/require_glob.md @@ -17,15 +17,19 @@ Possible parameters are: Example to load `.js` files recursively: +{% code title="dnsconfig.js" %} ```javascript require_glob("./domains/"); ``` +{% endcode %} Example to load `.js` files only in `domains/`: +{% code title="dnsconfig.js" %} ```javascript require_glob("./domains/", false); ``` +{% endcode %} 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: diff --git a/documentation/functions/record/CAA_BUILDER.md b/documentation/functions/record/CAA_BUILDER.md index 7ea60a3fd..04bc365c3 100644 --- a/documentation/functions/record/CAA_BUILDER.md +++ b/documentation/functions/record/CAA_BUILDER.md @@ -24,6 +24,7 @@ authorized certificate authorities and the builder cares about the rest. For example you can use: +{% code title="dnsconfig.js" %} ```javascript CAA_BUILDER({ label: "@", @@ -36,6 +37,7 @@ CAA_BUILDER({ issuewild: "none", }) ``` +{% endcode %} The parameters are: @@ -47,9 +49,11 @@ The parameters are: `CAA_BUILDER()` returns multiple records (when configured as example above): +{% code title="dnsconfig.js" %} ```javascript CAA("@", "iodef", "mailto:test@domain.tld", CAA_CRITICAL) CAA("@", "issue", "letsencrypt.org") CAA("@", "issue", "comodoca.com") CAA("@", "issuewild", ";") ``` +{% endcode %} diff --git a/documentation/functions/record/DMARC_BUILDER.md b/documentation/functions/record/DMARC_BUILDER.md index 66e8b1ef4..fde4a94a7 100644 --- a/documentation/functions/record/DMARC_BUILDER.md +++ b/documentation/functions/record/DMARC_BUILDER.md @@ -39,6 +39,7 @@ DMARC policies for your domains. ### Simple example +{% code title="dnsconfig.js" %} ```javascript DMARC_BUILDER({ policy: 'reject', @@ -47,6 +48,7 @@ DMARC_BUILDER({ ], }) ``` +{% endcode %} This yield the following record: @@ -56,6 +58,7 @@ This yield the following record: ### Advanced example +{% code title="dnsconfig.js" %} ```javascript DMARC_BUILDER({ policy: 'reject', @@ -72,8 +75,12 @@ DMARC_BUILDER({ ], failureOptions: '1', reportInterval: '1h', -}), +}); +``` +{% endcode %} +{% code title="dnsconfig.js" %} +```javascript DMARC_BUILDER({ label: 'insecure', policy: 'none', @@ -84,8 +91,9 @@ DMARC_BUILDER({ SPF: false, DKIM: true, }, -}) +}); ``` +{% endcode %} This yields the following records: diff --git a/documentation/functions/record/SPF_BUILDER.md b/documentation/functions/record/SPF_BUILDER.md index e452c109e..1a568e19b 100644 --- a/documentation/functions/record/SPF_BUILDER.md +++ b/documentation/functions/record/SPF_BUILDER.md @@ -37,11 +37,13 @@ enforce the "10 lookup rule". Here is an example of how SPF settings are normally done: +{% code title="dnsconfig.js" %} ```javascript D("example.tld", REG, DNS, ... TXT("v=spf1 ip4:198.252.206.0/24 ip4:192.111.0.0/24 include:_spf.google.com include:mailgun.org include:spf-basic.fogcreek.com include:mail.zendesk.com include:servers.mcsv.net include:sendgrid.net include:450622.spf05.hubspotemail.net ~all") ) ``` +{% endcode %} This has a few problems: @@ -51,6 +53,7 @@ This has a few problems: ## The DNSControl way +{% code title="dnsconfig.js" %} ```javascript D("example.tld", REG, DSP, ... A("@", "10.2.2.2"), @@ -80,6 +83,7 @@ D("example.tld", REG, DSP, ... }), ); ``` +{% endcode %} By using the `SPF_BUILDER()` we gain many benefits: @@ -92,6 +96,7 @@ By using the `SPF_BUILDER()` we gain many benefits: When you want to specify SPF settings for a domain, use the `SPF_BUILDER()` function. +{% code title="dnsconfig.js" %} ```javascript D("example.tld", REG, DSP, ... ... @@ -115,6 +120,7 @@ D("example.tld", REG, DSP, ... ... ); ``` +{% endcode %} The parameters are: @@ -283,6 +289,7 @@ record an include is added. In some situations we define an SPF setting once and want to re-use it on many domains. Here's how to do this: +{% code title="dnsconfig.js" %} ```javascript var SPF_MYSETTINGS = SPF_BUILDER({ label: "@", @@ -306,3 +313,4 @@ D("example2.tld", REG, DSP, ... SPF_MYSETTINGS ); ``` +{% endcode %} diff --git a/documentation/functions/record/TTL.md b/documentation/functions/record/TTL.md index 5deb3ad86..490e9d2eb 100644 --- a/documentation/functions/record/TTL.md +++ b/documentation/functions/record/TTL.md @@ -24,6 +24,7 @@ The value can be: * 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'`? +{% code title="dnsconfig.js" %} ```javascript D('example.com', REGISTRAR, DnsProvider('R53'), DefaultTTL(2000), @@ -33,3 +34,4 @@ D('example.com', REGISTRAR, DnsProvider('R53'), A('demo2', '3.4.5.12', TTL('5w')), // 5 weeks ); ``` +{% endcode %} diff --git a/documentation/providers/axfrddns.md b/documentation/providers/axfrddns.md index 9e20ba531..d223f9745 100644 --- a/documentation/providers/axfrddns.md +++ b/documentation/providers/axfrddns.md @@ -141,7 +141,8 @@ Here is a sample `named.conf` example for an authauritative server on zone `example.tld`. It uses a simple IP-based ACL for the AXFR transfer and a conjunction of TSIG and IP-based ACL for the updates. -```javascript +{% code title="named.conf" %} +```text options { listen-on { any; }; @@ -184,6 +185,7 @@ key update-key-id { secret "AnotherSecret="; }; ``` +{% endcode %} ## FYI: get-zones diff --git a/documentation/providers/vultr.md b/documentation/providers/vultr.md index 8ff2b9c03..f076793fb 100644 --- a/documentation/providers/vultr.md +++ b/documentation/providers/vultr.md @@ -14,7 +14,7 @@ Example: } } ``` -{% endcode %}` +{% endcode %} ## Metadata