update ts types
1 file changed, 383 insertions(+), 227 deletions(-)
changed files
M types-dnscontrol.d.ts → types-dnscontrol.d.ts
@@ -1,7 +1,7 @@ // This file was automatically generated by DNSControl. Do not edit it directly. // To update it, run `dnscontrol write-types`. -// DNSControl version 4.10.0 +// DNSControl version 4.18.0 // WARNING: These type definitions are experimental and subject to change in future releases. interface Domain {@@ -53,9 +53,9 @@ * > 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. * * ```javascript - * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), [ + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * A("@", "1.2.3.4"), - * ]); + * ); * * FETCH("https://example.com", { * // All three options below are optional@@ -114,6 +114,7 @@ } declare function require(name: `${string}.json`): any; +declare function require(name: `${string}.json5`): any; declare function require(name: string): true; /**@@ -193,7 +194,7 @@ * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * 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}) + * A("*", "1.2.3.4", {foo: 42}), * ); * ``` *@@ -215,7 +216,7 @@ * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * AAAA("@", addrV6), * AAAA("foo", addrV6), * AAAA("test.foo", addrV6, TTL(5000)), - * AAAA("*", addrV6, {foo: 42}) + * AAAA("*", addrV6, {foo: 42}), * ); * ``` *@@ -224,7 +225,7 @@ */ declare function AAAA(name: string, address: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * AKAMAICDN is a proprietary record type that is used to configure [Zone Apex Mapping](https://blogs.akamai.com/2019/08/fast-dns-zone-apex-mapping-dnssec.html). + * AKAMAICDN is a proprietary record type that is used to configure [Zone Apex Mapping](https://www.akamai.com/blog/security/edge-dns--zone-apex-mapping---dnssec). * The AKAMAICDN target must be preconfigured in the Akamai network. * * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/service-provider-specific/akamai-edge-dns/akamaicdn@@ -251,24 +252,24 @@ */ declare function ALIAS(name: string, target: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * AUTODNSSEC_OFF tells the provider to disable AutoDNSSEC. It takes no + * `AUTODNSSEC_OFF` tells the provider to disable AutoDNSSEC. It takes no * parameters. * - * See `AUTODNSSEC_ON` for further details. + * See [`AUTODNSSEC_ON`](AUTODNSSEC_ON.md) for further details. * * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/autodnssec_off */ declare const AUTODNSSEC_OFF: DomainModifier; /** - * AUTODNSSEC_ON tells the provider to enable AutoDNSSEC. + * `AUTODNSSEC_ON` tells the provider to **enable** AutoDNSSEC. * - * AUTODNSSEC_OFF tells the provider to disable AutoDNSSEC. + * [`AUTODNSSEC_OFF`](AUTODNSSEC_OFF.md) 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 + * 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.@@ -279,12 +280,12 @@ * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * AUTODNSSEC_ON, // Enable AutoDNSSEC. - * A("@", "10.1.1.1") + * A("@", "10.1.1.1"), * ); * * D("insecure.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * AUTODNSSEC_OFF, // Disable AutoDNSSEC. - * A("@", "10.2.2.2") + * A("@", "10.2.2.2"), * ); * ``` *@@ -363,7 +364,7 @@ * // 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) + * CAA("@", "iodef", "mailto:test@example.com", CAA_CRITICAL), * ); * ``` *@@ -384,25 +385,29 @@ * * ### Simple example * * ```javascript - * CAA_BUILDER({ - * label: "@", - * iodef: "mailto:test@example.com", - * iodef_critical: true, - * issue: [ - * "letsencrypt.org", - * "comodoca.com", - * ], - * issuewild: "none", - * }) + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * CAA_BUILDER({ + * label: "@", + * iodef: "mailto:test@example.com", + * iodef_critical: true, + * issue: [ + * "letsencrypt.org", + * "comodoca.com", + * ], + * issuewild: "none", + * }), + * ); * ``` * * `CAA_BUILDER()` builds multiple records: * * ```javascript - * CAA("@", "iodef", "mailto:test@example.com", CAA_CRITICAL) - * CAA("@", "issue", "letsencrypt.org") - * CAA("@", "issue", "comodoca.com") - * CAA("@", "issuewild", ";") + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * CAA("@", "iodef", "mailto:test@example.com", CAA_CRITICAL), + * CAA("@", "issue", "letsencrypt.org"), + * CAA("@", "issue", "comodoca.com"), + * CAA("@", "issuewild", ";"), + * ); * ``` * * which in turns yield the following records:@@ -419,27 +424,31 @@ * * The same example can be enriched with CAA_CRITICAL on all records: * * ```javascript - * CAA_BUILDER({ - * label: "@", - * iodef: "mailto:test@example.com", - * iodef_critical: true, - * issue: [ - * "letsencrypt.org", - * "comodoca.com", - * ], - * issue_critical: true, - * issuewild: "none", - * issuewild_critical: true, - * }) + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * CAA_BUILDER({ + * label: "@", + * iodef: "mailto:test@example.com", + * iodef_critical: true, + * issue: [ + * "letsencrypt.org", + * "comodoca.com", + * ], + * issue_critical: true, + * issuewild: "none", + * issuewild_critical: true, + * }), + * ); * ``` * * `CAA_BUILDER()` then builds (the same) multiple records - all with CAA_CRITICAL flag set: * * ```javascript - * CAA("@", "iodef", "mailto:test@example.com", CAA_CRITICAL) - * CAA("@", "issue", "letsencrypt.org", CAA_CRITICAL) - * CAA("@", "issue", "comodoca.com", CAA_CRITICAL) - * CAA("@", "issuewild", ";", CAA_CRITICAL) + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * CAA("@", "iodef", "mailto:test@example.com", CAA_CRITICAL), + * CAA("@", "issue", "letsencrypt.org", CAA_CRITICAL), + * CAA("@", "issue", "comodoca.com", CAA_CRITICAL), + * CAA("@", "issuewild", ";", CAA_CRITICAL), + * ); * ``` * * which in turns yield the following records:@@ -460,18 +469,24 @@ * * `issue:` An array of CAs which are allowed to issue certificates. (Use `"none"` to refuse all CAs) * * `issue_critical:` This can be `true` or `false`. If enabled and CA does not support this record, then certificate issue will be refused. (Optional. Default: `false`) * * `issuewild:` An array of CAs which are allowed to issue wildcard certificates. (Can be simply `"none"` to refuse issuing wildcard certificates for all CAs) * * `issuewild_critical:` This can be `true` or `false`. If enabled and CA does not support this record, then certificate issue will be refused. (Optional. Default: `false`) + * * `ttl:` Input for `TTL` method (optional) * * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/caa_builder */ -declare function CAA_BUILDER(opts: { label?: string; iodef: string; iodef_critical?: boolean; issue: string[]; issue_critical?: boolean; issuewild: string[]; issuewild_critical?: boolean }): DomainModifier; +declare function CAA_BUILDER(opts: { label?: string; iodef: string; iodef_critical?: boolean; issue: string[]; issue_critical?: boolean; issuewild: string[]; issuewild_critical?: boolean; ttl?: Duration }): DomainModifier; /** + * WARNING: Cloudflare is removing this feature and replacing it with a new + * feature called "Dynamic Single Redirect". DNSControl will automatically + * generate "Dynamic Single Redirects" for a limited number of use cases. See + * [`CLOUDFLAREAPI`](../../provider/cloudflareapi.md) for details. + * * `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`](CF_TEMP_REDIRECT.md) 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. + * 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@@ -497,6 +512,41 @@ */ declare function CF_REDIRECT(source: string, destination: string, ...modifiers: RecordModifier[]): DomainModifier; /** + * `CF_SINGLE_REDIRECT` is a Cloudflare-specific feature for creating HTTP redirects. 301, 302, 303, 307, 308 are supported. + * Typically one uses 302 (temporary) or (less likely) 301 (permanent). + * + * This feature manages dynamic "Single Redirects". (Single Redirects can be + * static or dynamic but DNSControl only maintains dynamic redirects). + * + * Cloudflare documentation: <https://developers.cloudflare.com/rules/url-forwarding/single-redirects/> + * + * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * CF_SINGLE_REDIRECT("name", 302, "when", "then"), + * CF_SINGLE_REDIRECT('redirect www.example.com', 302, 'http.host eq "www.example.com"', 'concat("https://otherplace.com", http.request.uri.path)'), + * CF_SINGLE_REDIRECT('redirect yyy.example.com', 302, 'http.host eq "yyy.example.com"', 'concat("https://survey.stackoverflow.co", "")'), + * ); + * ``` + * + * The fields are: + * + * * name: The name (basically a comment, but it must be unique) + * * code: Any of 301, 302, 303, 307, 308. May be a number or string. + * * when: What Cloudflare sometimes calls the "rule expression". + * * then: The replacement expression. + * + * NOTE: The features [`CF_REDIRECT`](CF_REDIRECT.md) and [`CF_TEMP_REDIRECT`](CF_TEMP_REDIRECT.md) generate `CF_SINGLE_REDIRECT` if enabled in [`CLOUDFLAREAPI`](../../provider/cloudflareapi.md). + * + * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/service-provider-specific/cloudflare-dns/cf_single_redirect + */ +declare function CF_SINGLE_REDIRECT(name: string, code: number, when: string, then: string, ...modifiers: RecordModifier[]): DomainModifier; + +/** + * WARNING: Cloudflare is removing this feature and replacing it with a new + * feature called "Dynamic Single Redirect". DNSControl will automatically + * generate "Dynamic Single Redirects" for a limited number of use cases. See + * [`CLOUDFLAREAPI`](../../provider/cloudflareapi.md) for details. + * * `CF_TEMP_REDIRECT` uses Cloudflare-specific features ("Forwarding URL" Page * Rules) to generate a HTTP 302 temporary redirect. *@@ -578,7 +628,7 @@ * add records with [A](../domain-modifiers/A.md), [CNAME](../domain-modifiers/CNAME.md), 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](https://docs.dnscontrol.org/language-reference/domain-modifiers-modifiers) return such functions. + * - A function argument will be called with the domain object as it's only argument. Most of the [built-in modifier functions](https://docs.dnscontrol.org/language-reference/domain-modifiers) return such functions. * - An object argument will be merged into the domain's metadata collection. * - 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.@@ -587,7 +637,7 @@ * ```javascript * // simple domain * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * A("@","1.2.3.4"), - * CNAME("test", "foo.example2.com.") + * CNAME("test", "foo.example2.com."), * ); * * // "macro" for records that can be mixed into any zone@@ -602,7 +652,7 @@ * * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * A("@","1.2.3.4"), * CNAME("test", "foo.example2.com."), - * GOOGLE_APPS_DOMAIN_MX + * GOOGLE_APPS_DOMAIN_MX, * ); * ``` *@@ -622,15 +672,15 @@ * var DNS_INSIDE = NewDnsProvider("Cloudflare"); * var DNS_OUTSIDE = NewDnsProvider("bind"); * * D("example.com!inside", REG_THIRDPARTY, DnsProvider(DNS_INSIDE), - * A("www", "10.10.10.10") + * A("www", "10.10.10.10"), * ); * * D("example.com!outside", REG_THIRDPARTY, DnsProvider(DNS_OUTSIDE), - * A("www", "20.20.20.20") + * A("www", "20.20.20.20"), * ); * * D_EXTEND("example.com!inside", - * A("internal", "10.99.99.99") + * A("internal", "10.99.99.99"), * ); * ``` *@@ -644,11 +694,12 @@ * may have noticed this mistake, but will your coworkers? Will you in * six months? You get the idea. * * DNSControl command line flag `--domains` matches the full name (with the "!"). If you - * define domains `example.com!george` and `example.com!john` then: + * define domains `example.com!john`, `example.com!paul`, and `example.com!george` 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. + * * `--domains=example.com` will not match any of the three. + * * `--domains='example.com!george'` will only match george. + * * `--domains='example.com!george,example.com!john'` will match george and john. + * * `--domains='example.com!*'` will match all three. * * NOTE: The quotes are required if your shell treats `!` as a special * character, which is probably does. If you see an error that mentions@@ -671,11 +722,11 @@ * ```javascript * var COMMON = NewDnsProvider("foo"); * DEFAULTS( * DnsProvider(COMMON, 0), - * DefaultTTL("1d") + * DefaultTTL("1d"), * ); * * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), - * A("@","1.2.3.4") + * A("@","1.2.3.4"), * ); * ``` *@@ -686,7 +737,7 @@ * ```javascript * DEFAULTS(); * * D("example2.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), - * A("@","1.2.3.4") + * A("@","1.2.3.4"), * ); * ``` *@@ -701,7 +752,7 @@ * Digest should be a string. * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), - * DHCID("example.com", "ABCDEFG") + * DHCID("example.com", "ABCDEFG"), * ); * ``` *@@ -743,12 +794,14 @@ * * ### Simple example * * ```javascript - * DMARC_BUILDER({ - * policy: "reject", - * ruf: [ - * "mailto:mailauth-reports@example.com", - * ], - * }) + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * DMARC_BUILDER({ + * policy: "reject", + * ruf: [ + * "mailto:mailauth-reports@example.com", + * ], + * }), + * ); * ``` * * This yield the following record:@@ -760,36 +813,40 @@ * * ### Advanced example * * ```javascript - * 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", - * }); + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * 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", + * }), + * ); * ``` * * ```javascript - * DMARC_BUILDER({ - * label: "insecure", - * policy: "none", - * ruf: [ - * "mailto:mailauth-reports@example.com", - * ], - * failureOptions: { - * SPF: false, - * DKIM: true, - * }, - * }); + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * DMARC_BUILDER({ + * label: "insecure", + * policy: "none", + * ruf: [ + * "mailto:mailauth-reports@example.com", + * ], + * failureOptions: { + * SPF: false, + * DKIM: true, + * }, + * }), + * ); * ``` * * This yields the following records:@@ -831,7 +888,7 @@ * Target should be a string. * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), - * DNAME("sub", "example.net.") + * DNAME("sub", "example.net."), * ); * ``` *@@ -852,7 +909,7 @@ * Public key must be a string. * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), - * DNSKEY("@", 257, 3, 13, "AABBCCDD") + * DNSKEY("@", 257, 3, 13, "AABBCCDD"), * ); * ``` *@@ -882,7 +939,7 @@ * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * NO_PURGE, * NAMESERVER("ns1.foo.com"), - * NAMESERVER("ns2.foo.com") + * NAMESERVER("ns2.foo.com"), * ); * ``` *@@ -917,7 +974,7 @@ * * ```javascript * D("example.com", REG_NAMEDOTCOM, * NO_PURGE, - * DnsProvider(DSP_AZURE) + * DnsProvider(DSP_AZURE), * ); * ``` *@@ -940,7 +997,7 @@ * Digest must be a string. * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), - * DS("example.com", 2371, 13, 2, "ABCDEF") + * DS("example.com", 2371, 13, 2, "ABCDEF"), * ); * ``` *@@ -970,31 +1027,32 @@ * `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`](../domain-modifiers/CF_REDIRECT.md) and [`CF_TEMP_REDIRECT`](../domain-modifiers/CF_TEMP_REDIRECT.md)). Using them + * [`CF_SINGLE_REDIRECT`](../domain-modifiers/CF_SINGLE_REDIRECT.md), + * [`CF_REDIRECT`](../domain-modifiers/CF_REDIRECT.md), and [`CF_TEMP_REDIRECT`](../domain-modifiers/CF_TEMP_REDIRECT.md)). Using them * in a `D_EXTEND` subdomain may not be what you expect. * * ```javascript * D("domain.tld", REG_MY_PROVIDER, 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 + * 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 + * 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 + * 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 + * 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 + * CNAME("i", "j"), // i.sub.domain.tld -> j.sub.domain.tld * ); * ``` *@@ -1041,7 +1099,7 @@ * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * DefaultTTL("4h"), * A("@","1.2.3.4"), // uses default - * A("foo", "2.3.4.5", TTL(600)) // overrides default + * A("foo", "2.3.4.5", TTL(600)), // overrides default * ); * ``` *@@ -1084,6 +1142,35 @@ */ declare function FRAME(name: string, target: string, ...modifiers: RecordModifier[]): DomainModifier; /** + * `HASH` hashes `value` using the hashing algorithm given in `algorithm` + * (accepted values `SHA1`, `SHA256`, and `SHA512`) and returns the hex encoded + * hash value. + * + * example `HASH("SHA1", "abc")` returns `a9993e364706816aba3e25717850c26c9cd0d89d`. + * + * `HASH()`'s primary use case is for managing [catalog zones](https://datatracker.ietf.org/doc/html/rfc9432): + * + * > a method for automatic DNS zone provisioning among DNS primary and secondary name + * > servers by storing and transferring the catalog of zones to be provisioned as one + * > or more regular DNS zones. + * + * Here's an example of a catalog zone: + * + * ```javascript + * foo_name_suffix = HASH("SHA1", "foo.name") + ".zones" + * D("catalog.example" + * [...] + * , TXT("version", "2") + * , PTR(foo_name_suffix, "foo.name.") + * , A("primaries.ext." + foo_name_suffix, "192.168.1.1") + * ) + * ``` + * + * @see https://docs.dnscontrol.org/language-reference/top-level-functions/hash + */ +declare function HASH(algorithm: "SHA1" | "SHA256" | "SHA512", value: string): string; + +/** * HTTPS adds an HTTPS record to a domain. The name should be the relative label for the record. Use `@` for the domain apex. The HTTPS record is a special form of the SVCB resource record. * * The priority must be a positive number, the address should be an ip address, either a string, or a numeric value obtained via [IP](../top-level-functions/IP.md).@@ -1095,7 +1182,7 @@ * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * HTTPS("@", 1, ".", "ipv4hint=123.123.123.123 alpn=h3,h2 port=443"), - * HTTPS("@", 1, "test.com", "") + * HTTPS("@", 1, "test.com", ""), * ); * ``` *@@ -1131,9 +1218,11 @@ * * The `IGNORE()` function can be used with up to 3 parameters: * * ```javascript - * IGNORE(labelSpec, typeSpec, targetSpec): - * IGNORE(labelSpec, typeSpec): - * IGNORE(labelSpec): + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * IGNORE(labelSpec, typeSpec, targetSpec), + * IGNORE(labelSpec, typeSpec), + * IGNORE(labelSpec), + * ); * ``` * * * `labelSpec` is a glob that matches the DNS label. For example `"foo"` or `"foo*"`. `"*"` matches all labels, as does the empty string (`""`).@@ -1169,7 +1258,7 @@ * IGNORE("*", "CNAME", "dev-*"), // matches CNAMEs with targets prefixed `dev-*` * IGNORE("bar", "A,MX"), // ignore only A and MX records for name bar * IGNORE("*", "*", "dev-*"), // Ignore targets with a `dev-` prefix * IGNORE("*", "A", "1\.2\.3\."), // Ignore targets in the 1.2.3.0/24 CIDR block - * END); + * ); * ``` * * Ignore Let's Encrypt (ACME) validation records:@@ -1178,7 +1267,7 @@ * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * IGNORE("_acme-challenge", "TXT"), * IGNORE("_acme-challenge.**", "TXT"), - * END); + * ); * ``` * * Ignore DNS records typically inserted by Microsoft ActiveDirectory:@@ -1201,7 +1290,7 @@ * IGNORE("domaindnszones", "A"), * IGNORE("domaindnszones.**", "A"), * IGNORE("forestdnszones", "A"), * IGNORE("forestdnszones.**", "A"), - * END); + * ); * ``` * * ## Detailed examples@@ -1222,7 +1311,7 @@ * CNAME("cshort", "www"), * CNAME("cfull", "www.plts.org."), * CNAME("cfull2", "www.bar.plts.org."), * CNAME("cfull3", "bar.www.plts.org."), - * END); + * ); * * D_EXTEND("more.example.com", * A("foo", "1.1.1.1"),@@ -1231,86 +1320,133 @@ * CNAME("mshort", "www"), * CNAME("mfull", "www.plts.org."), * CNAME("mfull2", "www.bar.plts.org."), * CNAME("mfull3", "bar.www.plts.org."), - * END); + * ); * ``` * * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * IGNORE("@", "", ""), - * // Would match: - * // foo.example.com. A 1.1.1.1 - * // foo.more.example.com. A 1.1.1.1 + * ); * ``` * + * **Would match**: + * + * * `foo.example.com. A 1.1.1.1` + * * `foo.more.example.com. A 1.1.1.1` + * * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * IGNORE("example.com.", "", ""), - * // Would match: - * // nothing + * ); * ``` + * + * **Would match**: + * + * * nothing * * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * IGNORE("foo", "", ""), - * // Would match: - * // foo.example.com. A 1.1.1.1 + * ); * ``` * + * **Would match**: + * + * * `foo.example.com. A 1.1.1.1` + * * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * IGNORE("foo.**", "", ""), - * // Would match: - * // foo.more.example.com. A 1.1.1.1 + * ); * ``` * + * **Would match**: + * + * * `foo.more.example.com. A 1.1.1.1` + * * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * IGNORE("www", "", ""), - * // Would match: + * ); * // www.example.com. A 174.136.107.196 * ``` * * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * IGNORE("www.*", "", ""), - * // Would match: + * ); * // nothing * ``` * + * **Would match**: + * + * * nothing + * * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * IGNORE("www.example.com", "", ""), - * // Would match: + * ); * // nothing * ``` + * + * **Would match**: + * + * * nothing * * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * IGNORE("www.example.com.", "", ""), - * // Would match: - * // none + * ); * ``` * + * **Would match**: + * + * * none + * * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * //IGNORE("", "", "1.1.1.*"), - * // Would match: - * // foo.example.com. A 1.1.1.1 - * // foo.more.example.com. A 1.1.1.1 + * ); * ``` * + * **Would match**: + * + * * `foo.example.com. A 1.1.1.1` + * * `foo.more.example.com. A 1.1.1.1` + * * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * //IGNORE("", "", "www"), - * // Would match: - * // none + * ); * ``` * + * **Would match**: + * + * * none + * * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * IGNORE("", "", "*bar*"), - * // Would match: - * // cfull2.example.com. CNAME www.bar.plts.org. - * // cfull3.example.com. CNAME bar.www.plts.org. - * // mfull2.more.example.com. CNAME www.bar.plts.org. - * // mfull3.more.example.com. CNAME bar.www.plts.org. + * ); * ``` * + * **Would match**: + * + * * `cfull2.example.com. CNAME www.bar.plts.org.` + * * `cfull3.example.com. CNAME bar.www.plts.org.` + * * `mfull2.more.example.com. CNAME www.bar.plts.org.` + * * `mfull3.more.example.com. CNAME bar.www.plts.org.` + * * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * IGNORE("", "", "bar.**"), - * // Would match: - * // cfull3.example.com. CNAME bar.www.plts.org. - * // mfull3.more.example.com. CNAME bar.www.plts.org. + * ); * ``` + * + * **Would match**: + * + * * `cfull3.example.com. CNAME bar.www.plts.org.` + * * `mfull3.more.example.com. CNAME bar.www.plts.org.` * * ## Conflict handling *@@ -1347,8 +1483,10 @@ * world and its use will result in a validation error. Use the above example * instead. * * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * // THIS NO LONGER WORKS! Use DISABLE_IGNORE_SAFETY_CHECK instead. See above. * TXT("myhost", "mytext", IGNORE_NAME_DISABLE_SAFETY_CHECK), + * ); * ``` * * ## Caveats@@ -1357,7 +1495,7 @@ * WARNING: Two systems updating the same domain is complex. Complex things are risky. Use `IGNORE()` * as a last resort. Even then, test extensively. * * * There is no locking. If the external system and DNSControl make updates at the exact same time, the results are undefined. - * * IGNORE` works fine with records inserted into a `D()` via `D_EXTEND()`. The matching is done on the resulting FQDN of the label or target. + * * `IGNORE` works fine with records inserted into a `D()` via `D_EXTEND()`. The matching is done on the resulting FQDN of the label or target. * * `targetSpec` does not match fields other than the primary target. For example, `MX` records have a target hostname plus a priority. There is no way to match the priority. * * The BIND provider can not ignore records it doesn't know about. If it does not have access to an existing zonefile, it will create a zonefile from scratch. That new zonefile will not have any external records. It will seem like they were not ignored, but in reality BIND didn't have visibility to them so that they could be ignored. *@@ -1388,12 +1526,12 @@ * Includes all records from a given domain * * ```javascript * D("example.com!external", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), - * A("test", "8.8.8.8") + * A("test", "8.8.8.8"), * ); * * D("example.com!internal", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * INCLUDE("example.com!external"), - * A("home", "127.0.0.1") + * A("home", "127.0.0.1"), * ); * ``` *@@ -1426,7 +1564,7 @@ */ declare function IP(ip: string): number; /** - * The parameter number types are as follows: + * The parameter number types ingested are as follows: * * ``` * name: string@@ -1437,7 +1575,7 @@ * sec1: float32 * deg2: uint32 * min2: uint32 * sec2: float32 - * altitude: uint32 + * altitude: float32 * size: float32 * horizontal_precision: float32 * vertical_precision: float32@@ -1494,23 +1632,28 @@ * The coordinate format for `LOC()` is: * * `degrees,minutes,seconds,[NnSs],deg,min,sec,[EeWw],altitude,size,horizontal_precision,vertical_precision` * + * where: + * altitude: [-100000.00 .. 42849672.95] BY .01 (altitude in meters) + * size, horizontal_precision, vertical_precision: [0 .. 90000000.00] (size/precision in meters) + * + * values outside of the above ranges are gated to within the ranges. + * * ## Examples ## * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * // LOC "subdomain", d1, m1, s1, "[NnSs]", d2, m2, s2, "[EeWw]", alt, siz, hp, vp) * //42 21 54 N 71 06 18 W -24m 30m - * , LOC("@", 42, 21, 54, "N", 71, 6, 18, "W", -24, 30, 0, 0) + * LOC("@", 42, 21, 54, "N", 71, 6, 18, "W", -24.01, 30, 0, 0), * //42 21 43.952 N 71 5 6.344 W -24m 1m 200m 10m - * , LOC("a", 42, 21, 43.952, "N", 71, 5, 6.344, "W", -24, 1, 200, 10) + * LOC("a", 42, 21, 43.952, "N", 71, 5, 6.344, "W", -24.33, 1, 200, 10), * //52 14 05 N 00 08 50 E 10m - * , LOC("b", 52, 14, 5, "N", 0, 8, 50, "E", 10, 0, 0, 0) + * LOC("b", 52, 14, 5, "N", 0, 8, 50, "E", 10, 0, 0, 0), * //32 7 19 S 116 2 25 E 10m - * , LOC("c", 32, 7, 19, "S",116, 2, 25, "E", 10, 0, 0, 0) + * LOC("c", 32, 7, 19, "S",116, 2, 25, "E", 10, 0, 0, 0), * //42 21 28.764 N 71 00 51.617 W -44m 2000m - * , LOC("d", 42, 21, 28.764, "N", 71, 0, 51.617, "W", -44, 2000, 0, 0) + * LOC("d", 42, 21, 28.764, "N", 71, 0, 51.617, "W", -44, 2000, 0, 0), * ); - * * ``` * * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/loc@@ -1542,27 +1685,26 @@ * `38.89775977858357, -77.03655125982903` * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), - * LOC_BUILDER_DD({ + * LOC_BUILDER_DD({ * label: "big-ben", * x: 51.50084265331501, * y: -0.12462541415599787, * alt: 6, - * }) - * , LOC_BUILDER_DD({ + * }), + * LOC_BUILDER_DD({ * label: "white-house", * x: 38.89775977858357, * y: -77.03655125982903, * alt: 19, - * }) - * , LOC_BUILDER_DD({ + * }), + * LOC_BUILDER_DD({ * label: "white-house-ttl", * x: 38.89775977858357, * y: -77.03655125982903, * alt: 19, * ttl: "5m", - * }) + * }), * ); - * * ``` * * Part of the series:@@ -1602,9 +1744,8 @@ * LOC_BUILDER_STR({ * label: "tasmania", * str: "42°S 147°E", * alt: 3, - * }) + * }), * ); - * * ``` * * Part of the series:@@ -1645,9 +1786,8 @@ * label: "sydney-opera-house", * str: "33°51′31″S 151°12′51″E", * alt: 4, * ttl: "5m", - * }) + * }), * ); - * * ``` * * Part of the series:@@ -1679,23 +1819,22 @@ * * [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), - * , LOC_BUILDER_STR({ + * LOC_BUILDER_STR({ * label: "old-faithful", * str: "44.46046°N 110.82815°W", * alt: 2240, - * }) - * , LOC_BUILDER_STR({ + * }), + * LOC_BUILDER_STR({ * label: "ribblehead-viaduct", * str: "54.210436°N 2.370231°W", * alt: 300, - * }) - * , LOC_BUILDER_STR({ + * }), + * LOC_BUILDER_STR({ * label: "guinness-brewery", * str: "53°20′40″N 6°17′20″W", * alt: 300, - * }) + * }), * ); - * * ``` * * Part of the series:@@ -1720,9 +1859,11 @@ * * ### Simple example * * ```javascript - * M365_BUILDER({ - * initialDomain: "example.onmicrosoft.com", - * }); + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * M365_BUILDER("example.com", { + * initialDomain: "example.onmicrosoft.com", + * }), + * ); * ``` * * This sets up `MX` records, Autodiscover, and DKIM.@@ -1730,15 +1871,17 @@ * * ### Advanced example * * ```javascript - * M365_BUILDER({ - * label: "test", - * mx: false, - * autodiscover: false, - * dkim: false, - * mdm: true, - * domainGUID: "test-example-com", // Can be automatically derived in this case, if example.com is the context. - * initialDomain: "example.onmicrosoft.com", - * }); + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * M365_BUILDER("example.com", { + * label: "test", + * mx: false, + * autodiscover: false, + * dkim: false, + * mdm: true, + * domainGUID: "test-example-com", // Can be automatically derived in this case, if example.com is the context. + * initialDomain: "example.onmicrosoft.com", + * }), + * ); * ``` * * This sets up Mobile Device Management only.@@ -1768,7 +1911,7 @@ * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * MX("@", 5, "mail"), // mx example.com -> mail.example.com - * MX("sub", 10, "mail.foo.com.") + * MX("sub", 10, "mail.foo.com."), * ); * ``` *@@ -1777,20 +1920,21 @@ */ declare function MX(name: string, priority: number, target: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * `NAMESERVER()` instructs DNSControl to inform the domain"s registrar where to find this zone. + * `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()`](NS.md) function, which inserts NS records - * in the current zone and accepts a label. [`NS()`](NS.md) is useful for downward + * in the current zone and accepts a label. [`NS()`](NS.md) is for downward * delegations. `NAMESERVER()` is for informing upstream delegations. * * For more information, refer to [this page](../../nameservers.md). * * ```javascript - * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * D("example.com", REG_MY_PROVIDER, + * DnsProvider(DSP_MY_PROVIDER), * DnsProvider(route53, 0), * // Replace the nameservers: * NAMESERVER("ns1.myserver.com."),@@ -1809,7 +1953,7 @@ * * Nameservers are one of the least * understood parts of DNS, so a little extra explanation is required. * - * * [`NS()`](NS.md) lets you add an NS record to a zone, just like [`A()`](A.md) adds an A + * * [`NS()`](NS.md) adds an NS record to a zone, just like [`A()`](A.md) 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.@@ -1837,7 +1981,7 @@ * * 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 + * 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). *@@ -1850,7 +1994,7 @@ * ```javascript * var REG_THIRDPARTY = NewRegistrar("ThirdParty"); * D("example.com", REG_THIRDPARTY, * ... - * ) + * ); * ``` * * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/nameserver@@ -1865,7 +2009,7 @@ * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * NAMESERVER_TTL("2d"), - * NAMESERVER("ns") + * NAMESERVER("ns"), * ); * ``` *@@ -1878,7 +2022,7 @@ * NAMESERVER_TTL("3600"), * NAMESERVER("ns1.provider.com."), //inherits NAMESERVER_TTL * NAMESERVER("ns2.provider.com."), //inherits NAMESERVER_TTL * A("@","1.2.3.4"), // inherits DefaultTTL - * A("foo", "2.3.4.5", TTL(600)) // overrides DefaultTTL for this record only + * A("foo", "2.3.4.5", TTL(600)), // overrides DefaultTTL for this record only * ); * ``` *@@ -2030,7 +2174,7 @@ * NAPTR("6", 10, 10, "u", "E2U+SIP", "!^.*$!sip:joe@example.com!", "."), * NAPTR("7", 10, 10, "u", "E2U+SIP", "!^.*$!sip:jane@example.com!", "."), * NAPTR("8", 10, 10, "u", "E2U+SIP", "!^.*$!sip:mike@example.com!", "."), * NAPTR("9", 10, 10, "u", "E2U+SIP", "!^.*$!sip:linda@example.com!", "."), - * NAPTR("0", 10, 10, "u", "E2U+SIP", "!^.*$!sip:fax@example.com!", ".") + * NAPTR("0", 10, 10, "u", "E2U+SIP", "!^.*$!sip:fax@example.com!", "."), * ); * ``` *@@ -2039,7 +2183,7 @@ * ```javascript * D("4.3.2.1.5.5.5.0.0.8.1.e164.arpa.", REG_MY_PROVIDER, DnsProvider(R53), * NAPTR("@", 100, 50, "u", "E2U+SIP", "!^.*$!sip:customer-service@example.com!", "."), * NAPTR("@", 101, 50, "u", "E2U+email", "!^.*$!mailto:information@example.com!", "."), - * NAPTR("@", 101, 50, "u", "smtp+E2U", "!^.*$!mailto:information@example.com!", ".") + * NAPTR("@", 101, 50, "u", "smtp+E2U", "!^.*$!mailto:information@example.com!", "."), * ); * ``` *@@ -2106,13 +2250,13 @@ * in place. * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), NO_PURGE, - * A("foo","1.2.3.4") + * 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 + * "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@@ -2156,22 +2300,15 @@ */ declare function NS(name: string, target: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * Documentation needed. - * - * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/service-provider-specific/ns1/ns1_urlfwd - */ -declare function NS1_URLFWD(name: string, target: string, ...modifiers: RecordModifier[]): DomainModifier; - -/** * 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](../../providers.md). + * * `type` specifies a valid DNS provider type identifier listed on the [provider page](../../provider/index.md). * * Starting with [v3.16](../../v316.md), the type is optional. If it is absent, the `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). * * Starting with v4.0, specifying the type may be an error. Please add the `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](../../providers.md) for details. + * * `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](../../provider/index.md) for details. * * This function will return an opaque string that should be assigned to a variable name for use in [D](D.md) directives. *@@ -2182,7 +2319,7 @@ * 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") + * A("@","1.2.3.4"), * ); * ``` *@@ -2193,7 +2330,7 @@ * var REG_MYNDC = NewRegistrar("mynamedotcom"); * var DNS_MYAWS = NewDnsProvider("myaws"); * * D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS), - * A("@","1.2.3.4") + * A("@","1.2.3.4"), * ); * ``` *@@ -2207,10 +2344,10 @@ * 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](../../providers.md). + * * `type` specifies a valid DNS provider type identifier listed on the [provider page](../../provider/index.md). * * Starting with [v3.16](../../v316.md), the type is optional. If it is absent, the `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). * * Starting with v4.0, specifying the type may be an error. Please add the `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](../../providers.md) for details. + * * `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](../../provider/index.md) for details. * * This function will return an opaque string that should be assigned to a variable name for use in [D](D.md) directives. *@@ -2221,7 +2358,7 @@ * 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") + * A("@","1.2.3.4"), * ); * ``` *@@ -2232,7 +2369,7 @@ * var REG_MYNDC = NewRegistrar("mynamedotcom"); * var DNS_MYAWS = NewDnsProvider("myaws"); * * D("example.com", REG_MYNDC, DnsProvider(DNS_MYAWS), - * A("@","1.2.3.4") + * A("@","1.2.3.4"), * ); * ``` *@@ -2252,6 +2389,27 @@ */ declare function PANIC(message: string): never; /** + * `PORKBUN_URLFWD` is a Porkbun-specific feature that maps to Porkbun's URL forwarding feature, which creates HTTP 301 (permanent) or 302 (temporary) redirects. + * + * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * PORKBUN_URLFWD("urlfwd1", "http://example.com"), + * PORKBUN_URLFWD("urlfwd2", "http://example.org", {type: "permanent", includePath: "yes", wildcard: "no"}) + * ); + * ``` + * + * The fields are: + * * name: the record name + * * target: where you'd like to forward the domain to + * * type: valid types are: `temporary` (302 / 307) or `permanent` (301), default to `temporary` + * * includePath: whether to include the URI path in the redirection. Valid options are `yes` or `no`, default to `no` + * * wildcard: forward all subdomains of the domain. Valid options are `yes` or `no`, default to `yes` + * + * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/service-provider-specific//porkbun_urlfwd + */ +declare function PORKBUN_URLFWD(name: string, target: string, ...modifiers: RecordModifier[]): DomainModifier; + +/** * PTR adds a PTR record to the domain. * * The name is normally a 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@@ -2331,7 +2489,7 @@ * # Automatic forward and reverse lookups * * DNSControl does not automatically generate forward and reverse lookups. However * it is possible to write a macro that does this by using the - * [`D_EXTEND()`](../global/D_EXTEND.md) + * [`D_EXTEND()`](../top-level-functions/D_EXTEND.md) * function to insert `A` and `PTR` records into previously-defined domains. * * ```javascript@@ -2346,10 +2504,10 @@ * } * * D("example.com", REGISTRAR, DnsProvider(DSP_NONE), * ..., - * END); + * ); * D(REV("10.20.30.0/24"), REGISTRAR, DnsProvider(DSP_NONE), * ..., - * END); + * ); * * FORWARD_AND_REVERSE("10.20.30.77", "foo.example.com."); * FORWARD_AND_REVERSE("10.20.30.99", "bar.example.com.");@@ -2525,7 +2683,7 @@ * # Automatic forward and reverse record generation * * DNSControl does not automatically generate forward and reverse lookups. However * it is possible to write a macro that does this. See - * [`PTR()`](../domain/PTR.md) for an example. + * [`PTR()`](../domain-modifiers/PTR.md) for an example. * * @see https://docs.dnscontrol.org/language-reference/top-level-functions/rev */@@ -2578,14 +2736,10 @@ * `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. * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), - * SOA("@", "ns3.example.com.", "hostmaster@example.com", 3600, 600, 604800, 1440), + * SOA("@", "ns3.example.com.", "hostmaster.example.com.", 3600, 600, 604800, 1440), * ); * ``` * - * If you accidentally include an `@` in the email field DNSControl will quietly - * change it to a `.`. This way you can specify a human-readable email address - * when you are making it easier for spammers how to find you. - * * ## Notes * * The serial number is managed automatically. It isn't even a field in `SOA()`. * * Most providers automatically generate SOA records. They will ignore any `SOA()` statements.@@ -2613,8 +2767,8 @@ * Here is an example of how SPF settings are normally done: * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), - * 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") - * ) + * 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"), + * ); * ``` * * This has a few problems:@@ -2870,11 +3024,11 @@ * ] * }); * * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), - * SPF_MYSETTINGS + * SPF_MYSETTINGS, * ); * * D("example2.tld", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), - * SPF_MYSETTINGS + * SPF_MYSETTINGS, * ); * ``` *@@ -2924,7 +3078,9 @@ * * `value` is the fingerprint as a string. * * ```javascript - * SSHFP("@", 1, 1, "00yourAmazingFingerprint00"), + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * SSHFP("@", 1, 1, "00yourAmazingFingerprint00"), + * ); * ``` * * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/sshfp@@ -2942,7 +3098,7 @@ * 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. * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), - * SVCB("@", 1, ".", "ipv4hint=123.123.123.123 alpn=h3,h2 port=443") + * SVCB("@", 1, ".", "ipv4hint=123.123.123.123 alpn=h3,h2 port=443"), * ); * ``` *@@ -3021,7 +3177,7 @@ * 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. + * TXT("long", "X".repeat(300)), // Long strings are split automatically. * ); * ``` *@@ -3216,4 +3372,4 @@ * ``` * * @see https://docs.dnscontrol.org/language-reference/top-level-functions/require_glob */ -declare function require_glob(path: string, recursive: boolean): void; +declare function require_glob(path: string, recursive?: boolean): void;