Update types
1 file changed, 708 insertions(+), 82 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.18.0 +// 4.34.0 // WARNING: These type definitions are experimental and subject to change in future releases. interface Domain {@@ -142,6 +142,10 @@ /** Proxy enabled. */ declare const CF_PROXY_ON: RecordModifier; /** Proxy+Railgun enabled. */ declare const CF_PROXY_FULL: RecordModifier; +/** Per-record CNAME flattening disabled (default) */ +declare const CF_CNAME_FLATTEN_OFF: RecordModifier; +/** Per-record CNAME flattening enabled (requires Cloudflare paid plan) */ +declare const CF_CNAME_FLATTEN_ON: RecordModifier; /** Proxy default off for entire domain (the default) */ declare const CF_PROXY_DEFAULT_OFF: DomainModifier;@@ -151,6 +155,14 @@ /** UniversalSSL off for entire domain */ declare const CF_UNIVERSALSSL_OFF: DomainModifier; /** UniversalSSL on for entire domain */ declare const CF_UNIVERSALSSL_ON: DomainModifier; +/** Set a comment on a DNS record (works on all Cloudflare plans) */ +declare function CF_COMMENT(comment: string): RecordModifier; +/** Set tags on a DNS record (requires Cloudflare paid plan) */ +declare function CF_TAGS(...tags: string[]): RecordModifier; +/** Enable comment management for this domain (opt-in to sync comments) */ +declare const CF_MANAGE_COMMENTS: DomainModifier; +/** Enable tag management for this domain (opt-in to sync tags, requires paid plan) */ +declare const CF_MANAGE_TAGS: DomainModifier; /** * Set default values for CLI variables. See: https://dnscontrol.org/cli-variables@@ -183,9 +195,9 @@ declare const DISABLE_REPEATED_DOMAIN_CHECK: RecordModifier; /** - * A adds an A record To a domain. The name should be the relative label for the record. Use `@` for the domain apex. + * `A` adds an [IPv4 Address record](https://www.rfc-editor.org/rfc/rfc1035) 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](../top-level-functions/IP.md). + * The address should be an IP address, either a string, or a numeric value obtained via [IP](../top-level-functions/IP.md). * * 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. *@@ -203,7 +215,7 @@ */ declare function A(name: string, address: string | number, ...modifiers: RecordModifier[]): DomainModifier; /** - * AAAA adds an AAAA record To a domain. The name should be the relative label for the record. Use `@` for the domain apex. + * `AAAA` adds an [IPv6 Address record](https://www.rfc-editor.org/rfc/rfc3596) 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. *@@ -225,12 +237,82 @@ */ declare function AAAA(name: string, address: string, ...modifiers: RecordModifier[]): DomainModifier; /** + * `ADGUARDHOME_AAAA_PASSTHROUGH` represents the literal 'A'. AdGuardHome uses this to passthrough + * the original values of a record type. + * + * The second argument to this record type must be empty. + * + * See [this](https://github.com/AdguardTeam/Adguardhome/wiki/Configuration) page for + * more information. + * + * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * ADGUARDHOME_AAAA_PASSTHROUGH("foo", ""), + * ); + * ``` + * + * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/service-provider-specific//adguardhome_aaaa_passthrough + */ +declare function ADGUARDHOME_AAAA_PASSTHROUGH(source: string, destination: string): DomainModifier; + +/** + * `ADGUARDHOME_A_PASSTHROUGH` represents the literal 'A'. AdGuardHome uses this to passthrough + * the original values of a record type. + * + * The second argument to this record type must be empty. + * + * See [this](https://github.com/AdguardTeam/Adguardhome/wiki/Configuration) page for + * more information. + * + * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * ADGUARDHOME_A_PASSTHROUGH("foo", ""), + * ); + * ``` + * + * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/service-provider-specific//adguardhome_a_passthrough + */ +declare function ADGUARDHOME_A_PASSTHROUGH(source: string, destination: string): DomainModifier; + +/** * 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 */ declare function AKAMAICDN(name: string, target: string, ...modifiers: RecordModifier[]): DomainModifier; + +/** + * `AKAMAITLC` is a proprietary Top-Level CNAME (TLC) record type specific to Akamai Edge DNS. + * It allows CNAME-like functionality at the zone apex (`@`) of a domain where regular CNAME records + * are not permitted. + * + * The difference between `AKAMAITLC` and `CNAME` is that `AKAMAITLC` records are resolved by Akamai Edge DNS + * servers instead of the client's resolver. This is similar to how `AKAMAICDN` records work, except that `AKAMAITLC` + * records can be pointed to any domain, not just Akamai properties. If you are pointing to an Akamai property, + * you should use `AKAMAICDN` instead. + * + * Important restrictions: + * - Can only be used at the zone apex (`@`) + * - Limited to one `AKAMAITLC` record per zone + * - Cannot coexist with an `AKAMAICDN` record at the apex + * + * The `answer_type` parameter controls which record types are returned when clients resolve the target: + * - `DUAL`: Returns both IPv4 (`A`) and IPv6 (`AAAA`) records + * - `A`: Returns only IPv4 records + * - `AAAA`: Returns only IPv6 records + * + * ## Example + * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * // Redirect example.com to google.com, returning both A and AAAA records + * AKAMAITLC("@", "DUAL", "google.com."), + * ); + * ``` + * + * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/service-provider-specific/akamai-edge-dns/akamaitlc + */ +declare function AKAMAITLC(name: string, answer_type: "DUAL" | "A" | "AAAA", target: string, ...modifiers: RecordModifier[]): DomainModifier; /** * ALIAS is a virtual record type that points a record at another record. It is analogous to a CNAME, but is usually resolved at request-time and served as an A record. Unlike CNAMEs, ALIAS records can be used at the zone apex (`@`)@@ -344,12 +426,16 @@ */ declare function AZURE_ALIAS(name: string, type: "A" | "AAAA" | "CNAME", target: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * `CAA()` adds a CAA record to a domain. The name should be the relative label for the record. Use `@` for the domain apex. + * `CAA` adds a [Certification Authority Authorization record](https://www.rfc-editor.org/rfc/rfc8659) to a domain. The name should be the relative label for the record. Use `@` for the domain apex. * * Tag can be one of * 1. `"issue"` * 2. `"issuewild"` * 3. `"iodef"` + * 4. `"contactemail"` + * 5. `"contactphone"` + * 6. `"issuemail"` + * 7. `"issuevmc"` * * Value is a string. The format of the contents is different depending on the tag. DNSControl will handle any escaping or quoting required, similar to TXT records. For example use `CAA("@", "issue", "letsencrypt.org")` rather than `CAA("@", "issue", "\"letsencrypt.org\"")`. *@@ -372,11 +458,12 @@ * DNSControl contains a [`CAA_BUILDER`](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. * * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/caa */ -declare function CAA(name: string, tag: "issue" | "issuewild" | "iodef", value: string, ...modifiers: RecordModifier[]): DomainModifier; +declare function CAA(name: string, tag: "issue" | "issuewild" | "iodef" | "contactemail" | "contactphone" | "issuemail" | "issuevmc", value: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * DNSControl contains a `CAA_BUILDER` which can be used to simply create - * [`CAA()`](../domain-modifiers/CAA.md) records for your domains. Instead of creating each [`CAA()`](../domain-modifiers/CAA.md) record + * `CAA_BUILDER` adds a [Certification Authority Authorization record](https://www.rfc-editor.org/rfc/rfc8659) to a domain. + * + * `CAA_BUILDER` eases the creation of [`CAA`](CAA.md) records. Instead of creating each [`CAA`](CAA.md) record * individually, you can simply configure your report mail address, the * authorized certificate authorities and the builder cares about the rest. *@@ -399,7 +486,7 @@ * }), * ); * ``` * - * `CAA_BUILDER()` builds multiple records: + * `CAA_BUILDER` builds multiple records: * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),@@ -440,7 +527,7 @@ * }), * ); * ``` * - * `CAA_BUILDER()` then builds (the same) multiple records - all with CAA_CRITICAL flag set: + * `CAA_BUILDER` then builds (the same) multiple records - all with CAA_CRITICAL flag set: * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),@@ -469,20 +556,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`) + * * `issuevmc:` An array of CAs which are allowed to issue VMC certificates. (Use `"none"` to refuse all CAs) + * * `issuevmc_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`) + * * `issuemail:` An array of CAs which are allowed to issue email certificates. (Use `"none"` to refuse all CAs) + * * `issuemail_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; ttl?: Duration }): DomainModifier; +declare function CAA_BUILDER(opts: { label?: string; iodef: string; iodef_critical?: boolean; issue: string[]|string; issue_critical?: boolean; issuewild: string[]|string; issuewild_critical?: boolean; issuevmc: string[]|string; issuevmc_critical?: boolean; issuemail: string[]|string; issuemail_critical?: boolean; ttl?: Duration }): DomainModifier; /** - * WARNING: Cloudflare is removing this feature and replacing it with a new + * **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. + * `CF_REDIRECT` uses [Cloudflare](../../provider/cloudflareapi.md)-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.@@ -512,47 +603,61 @@ */ 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). + * `CF_SINGLE_REDIRECT` is a [Cloudflare](../../provider/cloudflareapi.md)-specific feature for creating HTTP redirects. 301, 302, 303, 307, 308 are supported. + * Typically one uses 302 (temporary) or 301 (permanent). * * This feature manages dynamic "Single Redirects". (Single Redirects can be * static or dynamic but DNSControl only maintains dynamic redirects). * + * DNSControl will delete any "single redirects" it doesn't recognize (i.e. ones created via the web UI) so please be careful. + * * 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", "")'), + * CF_TEMP_REDIRECT("*example.com/*", "https://contests.otherexample.com/$2"), * ); * ``` * * The fields are: * - * * name: The name (basically a comment, but it must be unique) + * * name: The name (basically a comment) * * 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). + * DNSControl does not currently choose the order of the rules. New rules are + * added to the end of the list. Use Cloudflare's dashboard to re-order the rule, + * DNSControl should not change them. (In the future we hope to add a feature + * where the order the rules appear in dnsconfig.js is maintained in the + * dashboard.) + * + * ## `CF_REDIRECT` and `CF_TEMP_REDIRECT` + * + * `CF_REDIRECT` and `CF_TEMP_REDIRECT` used to manage Cloudflare Page Rules. + * However that feature is going away. To help with the migration, DNSControl now + * translates those commands into CF_SINGLE_REDIRECT equivalents. The conversion + * process is a transpiler that only understands certain formats. Please submit + * a Github issue if you find something it can't handle. * * @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 + * **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 + * `CF_TEMP_REDIRECT` uses [Cloudflare](../../provider/cloudflareapi.md)-specific features ("Forwarding URL" Page * Rules) to generate a HTTP 302 temporary redirect. * - * If _any_ [`CF_REDIRECT`](CF_REDIRECT.md) or `CF_TEMP_REDIRECT` functions are used then + * If _any_ [`CF_REDIRECT`](CF_REDIRECT.md) or `CF_TEMP_REDIRECT functions are used then * `dnscontrol` will manage _all_ "Forwarding URL" type Page Rules for the domain. - * Page Rule types other than "Forwarding URL” will be left alone. + * 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@@ -560,9 +665,12 @@ * backups and manually verifying `dnscontrol preview` output before running * `dnscontrol push`. This is especially true when mixing Page Rules that are * managed by DNSControl and those that aren't. * + * This example redirects the bare (aka apex, or naked) domain to www: + * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), - * CF_TEMP_REDIRECT("example.example.com/*", "https://otherplace.yourdomain.com/$1"), + * CF_TEMP_REDIRECT("example.com/*", "https://www.example.com/$1"), + * * ); * ``` *@@ -604,7 +712,7 @@ */ declare function CLOUDNS_WR(name: string, target: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * CNAME adds a CNAME record to the domain. The name should be the relative label for the domain. + * `CNAME` adds a [Canonical name record](https://www.rfc-editor.org/rfc/rfc1035) 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 `.`.@@ -635,8 +743,9 @@ * be used like a macro in multiple domains. * * ```javascript * // simple domain - * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), - * A("@","1.2.3.4"), + * D("example.com", REG_MY_PROVIDER, + * DnsProvider(DSP_MY_PROVIDER), + * A("@","1.2.3.4"), // "@" means the apex domain. In this case, "example.com" itself. * CNAME("test", "foo.example2.com."), * ); *@@ -649,13 +758,47 @@ * MX("@", 10, "alt3.aspmx.l.google.com."), * MX("@", 10, "alt4.aspmx.l.google.com."), * ] * - * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * D("other-example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * A("@","1.2.3.4"), * CNAME("test", "foo.example2.com."), * GOOGLE_APPS_DOMAIN_MX, * ); * ``` * + * **What is "@"?** The label `@` is a special name that means the domain itself, + * otherwise known as the domain's apex, the bare domain, or the naked domain. + * In other words, if you want to put a DNS record at the apex of a domain, use an `"@"` for the label, not an empty string (`""`). + * In the above example, `example.com` has an `A` record with the value `"1.2.3.4"` at the apex of the domain. + * + * # `no_ns` + * + * To prevent DNSControl from accidentally deleting your nameservers (at the + * parent domain), registrar updates are disabled if the list of nameservers for a + * zone (as computed from `dnsconfig.js`) is empty. + * + * This can happen when a provider doesn't give any control over the apex NS + * records, there are no default nameservers, there are no `NAMESERVER()` + * statements, and the provider returns an empty list of nameservers (such as + * Gandi and Vercel). + * + * In this situation, you will see an error message such as: + * + * ``` + * Skipping registrar REGISTRAR: No nameservers declared for domain "example.com". Add {no_ns:'true'} to force + * ``` + * + * To add this, add the meta data to the zone immediately following the registrar. + * + * ```javascript + * D("example.com", REG_MY_PROVIDER, {no_ns:'true'}, + * ... + * ... + * ... + * ); + * ``` + * + * NOTE: The value `true` of `no_ns` is a string. + * * # Split Horizon DNS * * DNSControl supports Split Horizon DNS. Simply@@ -667,15 +810,15 @@ * `domain.tld!tag`, such as `example.com!inside` and * `example.com!outside`. * * ```javascript - * var REG_THIRDPARTY = NewRegistrar("ThirdParty"); + * var REG_NONE = NewRegistrar("none"); * var DNS_INSIDE = NewDnsProvider("Cloudflare"); * var DNS_OUTSIDE = NewDnsProvider("bind"); * - * D("example.com!inside", REG_THIRDPARTY, DnsProvider(DNS_INSIDE), + * D("example.com!inside", REG_NONE, DnsProvider(DNS_INSIDE), * A("www", "10.10.10.10"), * ); * - * D("example.com!outside", REG_THIRDPARTY, DnsProvider(DNS_OUTSIDE), + * D("example.com!outside", REG_NONE, DnsProvider(DNS_OUTSIDE), * A("www", "20.20.20.20"), * ); *@@ -746,7 +889,7 @@ */ declare function DEFAULTS(...modifiers: DomainModifier[]): void; /** - * DHCID adds a DHCID record to the domain. + * `DHCID` adds a [DHCP identifier record](https://www.rfc-editor.org/rfc/rfc4701) to the domain. * * Digest should be a string. *@@ -761,14 +904,14 @@ */ declare function DHCID(name: string, digest: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * `DISABLE_IGNORE_SAFETY_CHECK()` disables the safety check. Normally it is an - * error to insert records that match an `IGNORE()` pattern. This disables that + * `DISABLE_IGNORE_SAFETY_CHECK` disables the safety check. Normally it is an + * error to insert records that match an `IGNORE` pattern. This disables that * safety check for the entire domain. * - * It replaces the per-record `IGNORE_NAME_DISABLE_SAFETY_CHECK()` which is + * It replaces the per-record `IGNORE_NAME_DISABLE_SAFETY_CHECK` which is * deprecated as of DNSControl v4.0.0.0. * - * See [`IGNORE()`](../domain-modifiers/IGNORE.md) for more information. + * See [`IGNORE`](../domain-modifiers/IGNORE.md) for more information. * * ## Syntax *@@ -786,6 +929,87 @@ */ declare const DISABLE_IGNORE_SAFETY_CHECK: DomainModifier; /** + * DNSControl contains a `DKIM_BUILDER` helper function that generates DKIM DNS TXT records according to RFC 6376 (DomainKeys Identified Mail) and its updates. + * + * ## Examples + * + * ### Simple example + * + * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * DKIM_BUILDER({ + * selector: "s1", + * pubkey: "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDC5/z4L" + * }), + * ); + * ``` + * + * This yield the following record: + * + * ```text + * s1._domainkey IN TXT "v=DKIM1; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDC5/z4L" + * ``` + * + * ### Advanced example + * + * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * DKIM_BUILDER({ + * selector: "k2", + * pubkey: "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDC5/z4L", + * label: "subdomain", + * version: "DKIM1", + * hashtypes: ['sha1', 'sha256'], + * keytype: "rsa", + * note: "some human-readable notes", + * servicetypes: ['email'], + * flags: ['y', 's'], + * ttl: 150 + * }), + * ); + * ``` + * + * This yields the following record: + * + * ```text + * k2._domainkey.subdomain IN TXT "v=DKIM1; h=sha1:sha256; k=rsa; n=some=20human-readable=20notes; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDC5/z4L; s=email; t=y:s" ttl=150 + * ``` + * + * ## Parameters + * + * * `selector` (string, required): The selector subdividing the namespace for the domain. + * * `pubkey` (string, optional): The base64-encoded public key (RSA or Ed25519). Default: empty (key revocation or non-sending domain). + * * `label` (string, optional): The DNS label for the DKIM record. Default: `@`. + * * `version` (string, optional): DKIM version. Maps to the `v=` tag. Default: `DKIM1` (currently the only supported value). + * * `hashtypes` (array, optional): Acceptable hash algorithms for signing. Maps to the `h=` tag. + * * Supported values for RSA key: + * * `sha1` + * * `sha256` + * * Supported values for Ed25519 key: + * * `sha256` + * * `keytype` (string, optional): Key algorithm type. Maps to the `k=` tag. Default: `rsa`. Supported values: + * * `rsa` + * * `ed25519` + * * `note` (string, optional): Human-readable notes intended for administrators. Pass normal text here; DKIM-Quoted-Printable encoding will be applied automatically. Maps to the `n=` tag. + * * `servicetypes` (array, optional): Service types using this key. Maps to the `s=` tag. Supported values: + * * `*`: explicitly allows all service types + * * `email`: restricts key to email service only + * * `flags` (array, optional): Flags to modify the interpretation of the selector. Maps to the `t=` tag. Supported values: + * * `y`: Testing mode. + * * `s`: Subdomain restriction. + * * `ttl` (number, optional): DNS TTL value in seconds + * + * ## Related RFCs + * + * * RFC 6376: DomainKeys Identified Mail (DKIM) Signatures + * * RFC 8301: Cryptographic Algorithm and Key Usage Update to DKIM + * * RFC 8463: A New Cryptographic Signature Method for DKIM (Ed25519) + * + * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/dkim_builder + */ +declare function DKIM_BUILDER(opts: { selector: string; pubkey?: string; label?: string; version?: string; hashtypes?: string|string[]; keytype?: string; note?: string; servicetypes?: string|string[]; flags?: string|string[]; ttl?: Duration }): DomainModifier; + +/** * DNSControl contains a `DMARC_BUILDER` which can be used to simply create * DMARC policies for your domains. *@@ -882,7 +1106,7 @@ */ declare function DMARC_BUILDER(opts: { label?: string; version?: string; policy: 'none' | 'quarantine' | 'reject'; subdomainPolicy?: 'none' | 'quarantine' | 'reject'; alignmentSPF?: 'strict' | 's' | 'relaxed' | 'r'; alignmentDKIM?: 'strict' | 's' | 'relaxed' | 'r'; percent?: number; rua?: string[]; ruf?: string[]; failureOptions?: { SPF: boolean, DKIM: boolean } | string; failureFormat?: string; reportInterval?: Duration; ttl?: Duration }): DomainModifier; /** - * DNAME adds a DNAME record to the domain. + * `DNAME` adds a [Delegation name record](https://www.rfc-editor.org/rfc/rfc6672) to the domain. * * Target should be a string. *@@ -985,7 +1209,7 @@ */ declare function DOMAIN_ELSEWHERE_AUTO(name: string, domain: string, registrar: string, dnsProvider: string): void; /** - * DS adds a DS record to the domain. + * `DS` adds a [Delegation signer record](https://www.rfc-editor.org/rfc/rfc4034) to the domain. * * Key Tag should be a number. *@@ -1090,7 +1314,7 @@ */ declare function D_EXTEND(name: string, ...modifiers: DomainModifier[]): void; /** - * DefaultTTL sets the TTL for all subsequent records following it in a domain that do not explicitly set one with [`TTL`](../record-modifiers/TTL.md). If neither `DefaultTTL` or `TTL` exist for a record, + * DefaultTTL sets the Time To Live (TTL) for all subsequent records following it in a domain that do not explicitly set one with [`TTL`](../record-modifiers/TTL.md). If neither `DefaultTTL` or `TTL` exist for a record, * the record will inherit the DNSControl global internal default of 300 seconds. See also [`DEFAULTS`](../top-level-functions/DEFAULTS.md) to override the internal defaults. * * NS records are currently a special case, and do not inherit from `DefaultTTL`. See [`NAMESERVER_TTL`](../domain-modifiers/NAMESERVER_TTL.md) to set a default TTL for all NS records.@@ -1123,7 +1347,7 @@ * * Using a different number, ie: `DnsProvider("name",2)`, means "fetch all nameservers from this provider, * but limit it to this many. * - * See [this page](../../nameservers.md) for a detailed explanation of how DNSControl handles nameservers and NS records. + * See [this page](../../advanced-features/nameservers.md) for a detailed explanation of how DNSControl handles nameservers and NS records. * * If a domain (`D()`) does not include any `DnsProvider()` functions, * the DNS records will not be modified. In fact, if you want to control@@ -1135,7 +1359,13 @@ */ declare function DnsProvider(name: string, nsCount?: number): DomainModifier; /** - * Documentation needed. + * This is provider specific type of record and not a DNS standard. It may behave differently for each provider that handles it. + * + * ### Namecheap + * + * This is a URL Redirect record with a type of "Masked", it creates a framed HTML page to the target. + * + * You can read more at the [Namecheap documentation](https://www.namecheap.com/support/knowledgebase/article.aspx/385/2237/how-to-set-up-a-url-redirect-for-a-domain/). * * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/frame */@@ -1178,6 +1408,8 @@ * * The params may be configured to specify the `alpn`, `ipv4hint`, `ipv6hint`, `ech` or `port` setting. Several params may be joined by a space. Not existing params may be specified as an empty 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. + * + * If you set the parameter `ech` to the special value `IGNORE`, DNSControl will ignore the contents of that parameter when updating a zone. * * ```javascript * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),@@ -1504,6 +1736,196 @@ */ declare function IGNORE(labelSpec: string, typeSpec?: string, targetSpec?: string): DomainModifier; /** + * `IGNORE_EXTERNAL_DNS` makes DNSControl automatically detect and ignore DNS records + * managed by Kubernetes external-dns. + * + * ## Background + * + * [External-dns](https://github.com/kubernetes-sigs/external-dns) is a popular + * Kubernetes controller that synchronizes exposed Kubernetes Services and Ingresses + * with DNS providers. It creates DNS records automatically based on annotations on + * your Kubernetes resources. + * + * External-dns uses TXT records to track ownership of the DNS records it manages. + * These TXT records contain metadata in this format: + * + * ``` + * "heritage=external-dns,external-dns/owner=<owner-id>,external-dns/resource=<resource>" + * ``` + * + * When you have both DNSControl and external-dns managing the same DNS zone, conflicts + * can occur. DNSControl will try to delete records created by external-dns, and + * external-dns will recreate them, leading to an endless update cycle. + * + * ## How it works + * + * When `IGNORE_EXTERNAL_DNS` is enabled, DNSControl will: + * + * 1. Scan existing TXT records for the external-dns heritage marker (`heritage=external-dns`) + * 2. Parse the TXT record name to determine which DNS record it manages + * 3. Automatically ignore both the TXT ownership record and the corresponding DNS record + * + * External-dns creates TXT records with prefixes based on record type: + * - `a-<name>` for A records + * - `aaaa-<name>` for AAAA records + * - `cname-<name>` for CNAME records + * - `ns-<name>` for NS records + * - `mx-<name>` for MX records + * - `srv-<name>` for SRV records + * - `txt-<name>` for TXT records (when external-dns manages TXT records) + * + * For example, if external-dns creates an A record at `myapp.example.com`, it will + * also create a TXT record at `a-myapp.example.com` containing the heritage information. + * + * ## Usage + * + * ```javascript + * // Default: detect standard external-dns prefixes (a-, cname-, etc.) + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * IGNORE_EXTERNAL_DNS(), + * // Your static DNS records managed by DNSControl + * A("www", "1.2.3.4"), + * A("mail", "1.2.3.5"), + * MX("@", 10, "mail"), + * // Records created by external-dns (from Kubernetes Ingresses/Services) + * // will be automatically detected and ignored + * ); + * ``` + * + * ## Custom Prefix Support + * + * If your external-dns is configured with a custom `--txt-prefix` (as documented in the + * [external-dns TXT registry docs](https://github.com/kubernetes-sigs/external-dns/blob/master/docs/registry/txt.md#prefixes-and-suffixes)), + * pass that prefix to `IGNORE_EXTERNAL_DNS()`: + * + * ```javascript + * // If external-dns is configured with --txt-prefix="extdns-" + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * IGNORE_EXTERNAL_DNS("extdns-"), + * A("www", "1.2.3.4"), + * ); + * ``` + * + * This will match TXT records like `extdns-www`, `extdns-api`, etc. + * + * Without a prefix argument, it detects: + * - The default `%{record_type}-` format (prefixes like `a-`, `cname-`, etc.) + * - Legacy format (TXT record with same name as managed record) + * + * ## Example scenario + * + * Suppose you have: + * - A Kubernetes cluster running external-dns with `--txt-owner-id=my-cluster` + * - An Ingress resource that creates an A record for `myapp.example.com` pointing to `10.0.0.1` + * + * External-dns will create: + * 1. An A record: `myapp.example.com` → `10.0.0.1` + * 2. A TXT record: `a-myapp.example.com` → `"heritage=external-dns,external-dns/owner=my-cluster,external-dns/resource=ingress/default/myapp"` + * + * With `IGNORE_EXTERNAL_DNS` enabled, DNSControl will: + * - Detect the TXT record at `a-myapp.example.com` as an external-dns ownership record + * - Ignore both the TXT record and the A record at `myapp.example.com` + * - Only manage the records you explicitly define in your `dnsconfig.js` + * + * ## Comparison with other options + * + * | Feature | Use case | + * |---------|----------| + * | `IGNORE_EXTERNAL_DNS` | Automatically ignore all external-dns managed records | + * | `IGNORE("*.k8s", "A,AAAA,CNAME,TXT")` | Ignore records under a specific subdomain pattern | + * | `NO_PURGE` | Don't delete any records (less precise, records may accumulate) | + * + * ## Caveats + * + * ### One per domain + * + * Only one `IGNORE_EXTERNAL_DNS()` should be used per domain. If you call it multiple + * times, the last prefix wins. If you have multiple external-dns instances with + * different prefixes managing the same zone, use `IGNORE()` patterns for additional + * prefixes. + * + * ### TXT Registry Format + * + * This feature relies on external-dns's [TXT registry](https://github.com/kubernetes-sigs/external-dns/blob/master/docs/registry/txt.md), + * which is the default registry type. The TXT record content format is well-documented: + * + * ``` + * "heritage=external-dns,external-dns/owner=<owner-id>,external-dns/resource=<resource>" + * ``` + * + * This feature detects the `heritage=external-dns` marker in TXT records to identify + * external-dns managed records. + * + * ### Custom Prefix Support + * + * This feature supports custom prefixes configured via external-dns's `--txt-prefix` flag. + * If you're using a custom prefix, pass it to `IGNORE_EXTERNAL_DNS()`: + * + * ```javascript + * // If external-dns uses --txt-prefix="extdns-" + * IGNORE_EXTERNAL_DNS("extdns-") + * + * // If external-dns uses --txt-prefix="myprefix-%{record_type}-" + * IGNORE_EXTERNAL_DNS("myprefix-") // The record type part is handled automatically + * + * // If external-dns uses --txt-prefix="extdns-%{record_type}." (period format) + * // This is recommended for apex domain support per external-dns docs + * IGNORE_EXTERNAL_DNS("extdns-") // Works with both hyphen and period format + * ``` + * + * Without a prefix argument, it detects: + * - Default format: `%{record_type}-` prefix (e.g., `a-`, `cname-`) + * - Legacy format: Same name as managed record (no prefix) + * + * #### Period Format for Apex Domains + * + * If you need external-dns to manage apex (root) domain records, the external-dns + * documentation recommends using a prefix with `%{record_type}` followed by a period: + * + * ```yaml + * # external-dns deployment args + * args: + * - --txt-prefix=extdns-%{record_type}. + * ``` + * + * This creates TXT records like `extdns-a.www` for the `www` A record, and `extdns-a` + * for the apex A record. DNSControl's `IGNORE_EXTERNAL_DNS` supports both formats: + * + * - Hyphen format: `extdns-a-www` (from `--txt-prefix=extdns-` with default `%{record_type}-`) + * - Period format: `extdns-a.www` (from `--txt-prefix=extdns-%{record_type}.`) + * + * **Note:** Suffix-based naming (`--txt-suffix`) is not currently supported. + * + * ### Unsupported Registries + * + * External-dns supports multiple registry types. This feature **only** supports: + * + * - ✅ **TXT registry** (default) - Stores metadata in TXT records + * + * The following registries are **not supported**: + * + * - ❌ **DynamoDB registry** - Stores metadata in AWS DynamoDB + * - ❌ **AWS-SD registry** - Stores metadata in AWS Service Discovery + * - ❌ **noop registry** - No metadata persistence + * + * ### Legacy TXT Format + * + * External-dns versions prior to v0.16 created TXT records without the record type + * prefix (e.g., `myapp.example.com` instead of `a-myapp.example.com`). This legacy + * format is supported but may match more records than intended since the record type + * cannot be determined. + * + * ## See also + * + * * [`IGNORE`](IGNORE.md) for manually ignoring specific records with glob patterns + * * [`NO_PURGE`](NO_PURGE.md) for preventing deletion of all unmanaged records + * * [External-dns documentation](https://github.com/kubernetes-sigs/external-dns) + * + * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/ignore_external_dns + */ +declare function IGNORE_EXTERNAL_DNS(prefix?: string): DomainModifier; + +/** * `IGNORE_NAME(a)` is the same as `IGNORE(a, "*", "*")`. * * `IGNORE_NAME(a, b)` is the same as `IGNORE(a, b, "*")`.@@ -1564,6 +1986,8 @@ */ declare function IP(ip: string): number; /** + * `LOC` add a [Location record](https://www.rfc-editor.org/rfc/rfc1876) to the domain. + * * The parameter number types ingested are as follows: * * ```@@ -1849,6 +2273,106 @@ */ declare function LOC_BUILDER_STR(opts: { label?: string; str: string; alt?: number; ttl?: Duration }): DomainModifier; /** + * # LUA + * + * `LUA()` adds a **PowerDNS Lua record** to a domain. Use this when you want answers computed at **query time** (traffic steering, geo/ASN steering, weighted pools, health-based failover, time-based values, etc.) using the PowerDNS Authoritative Server’s built-in Lua engine. + * + * > **Provider support:** `LUA()` is supported **only** by the **PowerDNS** DNS provider in DNSControl. Ensure your zones are served by PowerDNS and that Lua records are enabled. + * > See: PowerDNS provider page and Supported providers matrix. + * > (References at the end.) + * + * ## Signature + * + * ```typescript + * LUA( + * name: string, + * rtype: string, // e.g. "A", "AAAA", "CNAME", "TXT", "PTR", "LOC", ... + * contents: string | string[], // the Lua snippet + * ...modifiers: RecordModifier[] + * ): DomainModifier + * ``` + * + * - **`name`** — label for the record (`"@"` for the zone apex). + * - **`rtype`** — the RR type the Lua snippet **emits** (e.g., `"A"`, `"AAAA"`, `"CNAME"`, `"TXT"`, `"PTR"`, `"LOC"`). + * - **`contents`** — the Lua snippet (string or array). See **Syntax** below. + * - **`modifiers`** — standard record modifiers like `TTL(60)`. + * + * ## Prerequisites (PowerDNS) + * + * PowerDNS Authoritative Server **4.2+** supports Lua records. You must enable Lua records either **globally** (in `pdns.conf`) or **per-zone** via domain metadata. + * + * - **Global:** set `enable-lua-records=yes` (or `shared`) and reload PowerDNS. + * - **Per-zone:** set metadata `ENABLE-LUA-RECORDS = 1` for the zone. + * + * See PowerDNS’s **Lua Records** overview and **Lua Reference** for details and helpers. + * + * ## Syntax + * + * PowerDNS evaluates the `contents` with two modes: + * + * - **Single expression (most common):** write **just the expression** — **no `return`**. PowerDNS implicitly treats the snippet as if it were the argument to `return`. + * - **Multi-statement script:** start the snippet with a **leading semicolon (`;`)**. In this mode you can write multiple statements and must include your own `return`. + * + * The value produced must be valid **RDATA** for the chosen `rtype` (IPv4 for `A`, IPv6 for `AAAA`, a single FQDN with trailing dot for `CNAME`, proper text for `TXT`, etc.). Helper functions and preset variables (e.g., `pickrandom`, `pickclosest`, `country`, `continent`, `qname`, `ifportup`) are defined in the PowerDNS Lua reference. + * + * ## Examples + * + * ### Single expression (implicit `return`) + * + * ```javascript + * // Weighted/random selection + * LUA("app", "A", "pickrandom({'192.0.2.11',3}, {'192.0.2.22',1})", TTL(60)); + * + * // Health-aware pool: only addresses with TCP/443 up are served + * LUA("www", "A", "ifportup(443, {'192.0.2.1','192.0.2.2'})", TTL(60)); + * + * // Geo proximity + * LUA("edge", "A", "pickclosest({'192.0.2.1','192.0.2.2','198.51.100.1'})", TTL(60)); + * ``` + * + * ### Multi-statement (leading `;`) + * + * ```javascript + * LUA("api", "A", [ + * "; if continent('EU') then ", + * " return {'198.51.100.1'} ", + * " else ", + * " return {'192.0.2.10','192.0.2.20'} ", + * " end" + * ], TTL(60)); + * + * // Dynamic TXT, showing the queried name (string building example) + * LUA("_diag", "TXT", "; return 'Got a TXT query for ' .. qname:toString()", TTL(30)); + * ``` + * + * ### Other RR types + * + * Lua can emit data for many RR types as long as the RDATA is valid for that type: + * + * ```javascript + * LUA("edge", "CNAME", "('edgesvc.example.net.')", TTL(60)); + * LUA("pop.asu", "LOC", "latlonloc(-25.286, -57.645, 100)", TTL(300)); // ~Asunción, 100m + * ``` + * + * ## Tips & gotchas + * + * - **Use low TTLs** (e.g., 30–120s) for dynamic behavior to update promptly. + * - **Don’t mix address families:** `A` answers must be IPv4; `AAAA` answers must be IPv6. + * - **Serials & transfers:** Lua answers are computed at query time; changing only the Lua behavior does **not** change the zone’s SOA serial. Zone transfer and serial behavior follow normal PowerDNS rules. + * - **Provider limitation:** Only the **PowerDNS** provider in DNSControl accepts `LUA()`; other providers will ignore or reject it. + * + * ## References + * + * - PowerDNS **Lua Records** overview (syntax, examples). + * - PowerDNS **Lua Reference** (functions, preset variables, objects). + * - DNSControl **PowerDNS provider** page. + * - DNSControl **Supported providers** table. + * + * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/service-provider-specific//lua + */ +declare function LUA(name: string, rtype: string, contents: string | string[], ...modifiers: RecordModifier[]): DomainModifier; + +/** * DNSControl offers a `M365_BUILDER` which can be used to simply set up Microsoft 365 for a domain in an opinionated way. * * It defaults to a setup without support for legacy Skype for Business applications.@@ -1902,7 +2426,7 @@ */ declare function M365_BUILDER(opts: { label?: string; mx?: boolean; autodiscover?: boolean; dkim?: boolean; skypeForBusiness?: boolean; mdm?: boolean; domainGUID?: string; initialDomain?: string }): DomainModifier; /** - * MX adds an MX record to the domain. + * `MX` adds a [Mail exchange record](https://www.rfc-editor.org/rfc/rfc1035) to the domain. * * Priority should be a number. *@@ -1930,7 +2454,7 @@ * 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 for downward * delegations. `NAMESERVER()` is for informing upstream delegations. * - * For more information, refer to [this page](../../nameservers.md). + * For more information, refer to [this page](../../advanced-features/nameservers.md). * * ```javascript * D("example.com", REG_MY_PROVIDER,@@ -1966,7 +2490,7 @@ * the registrar who does the hard work of talking to the people that * control `.com`. If the domain was `gmeet.io`, the registrar does * the right thing to talk to the people that control `.io`. * - * (A better name might have been `PARENTNAMESERVER()` but we didn"t + * (A better name might have been `PARENTNAMESERVER()` but we didn't * think of that at the time.) * * Each registrar handles delegations differently. Most use@@ -1991,8 +2515,8 @@ * * It looks like this: * * ```javascript - * var REG_THIRDPARTY = NewRegistrar("ThirdParty"); - * D("example.com", REG_THIRDPARTY, + * var REG_NONE = NewRegistrar("none"); + * D("example.com", REG_NONE, * ... * ); * ```@@ -2279,7 +2803,7 @@ */ declare const NO_PURGE: DomainModifier; /** - * NS adds a NS record to the domain. The name should be the relative label for the domain. + * `NS` adds a [Name server record](https://www.rfc-editor.org/rfc/rfc1035) to the domain. The name should be the relative label for the domain. * * The name may not be `@` (the bare domain), as that is controlled via [`NAMESERVER()`](NAMESERVER.md). * The difference between `NS()` and [`NAMESERVER()`](NAMESERVER.md) is explained in the [`NAMESERVER()` description](NAMESERVER.md).@@ -2306,13 +2830,13 @@ * 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](../../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 [v3.16](../../release/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](../../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. * - * Prior to [v3.16](../../v316.md): + * Prior to [v3.16](../../release/v316.md): * * ```javascript * var REG_MYNDC = NewRegistrar("mynamedotcom", "NAMEDOTCOM");@@ -2323,7 +2847,7 @@ * A("@","1.2.3.4"), * ); * ``` * - * In [v3.16](../../v316.md) and later: + * In [v3.16](../../release/v316.md) and later: * * ```javascript * var REG_MYNDC = NewRegistrar("mynamedotcom");@@ -2336,7 +2860,7 @@ * ``` * * @see https://docs.dnscontrol.org/language-reference/top-level-functions/newdnsprovider */ -declare function NewDnsProvider(name: string, type?: string, meta?: object): string; +declare function NewDnsProvider(name: string, meta?: object): string; /** * NewRegistrar activates a Registrar Provider specified in `creds.json`.@@ -2345,13 +2869,13 @@ * 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](../../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 [v3.16](../../release/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](../../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. * - * Prior to [v3.16](../../v316.md): + * Prior to [v3.16](../../release/v316.md): * * ```javascript * var REG_MYNDC = NewRegistrar("mynamedotcom", "NAMEDOTCOM");@@ -2362,7 +2886,7 @@ * A("@","1.2.3.4"), * ); * ``` * - * In [v3.16](../../v316.md) and later: + * In [v3.16](../../release/v316.md) and later: * * ```javascript * var REG_MYNDC = NewRegistrar("mynamedotcom");@@ -2378,6 +2902,22 @@ */ declare function NewRegistrar(name: string, type?: string, meta?: object): string; /** + * `OPENPGPKEY` adds an [OpenPGP public key record](https://www.rfc-editor.org/rfc/rfc7929) to the domain. + * + * So far, no transformation is applied to the parameters. The data will be passed to the DNS server as-is. + * Reference RFC 7929 for details. + * + * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * OPENPGPKEY("9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15._openpgpkey", "9901a204447450b7110400d9bef554b145128ccc90d9f52df14bb878626e3db32112d47fbc5ee9cc5ffcbbd06bee487a580481674d9d31e368a85ccf4d4ef3bfa3e23fdde238bc32d8c40d39204b912f8cb1c47a7f34ba64bf3598dafe0f080e17facb678b6e700b0163d677960471d265a197e5ee9d53d71e1911f47f518a0e303abaf3c01b188e37d7bf00a0b90d4f43af944202fc49356a35a367955633cd4503ff7dfa21fb70a201ffb4aa7a755fc560ffd5a4b1d7b7015e7b4bdc0a1e45c1c28fd2f628f4d21f07a091da0d29c98b070566e178c5974554e509a5153a16b271df835e8c8a97715cc4beb5383d05fdf7a0d9412a1fb9f572c195d8c0c696a5ec179bab29d3d8701446e7aca79565ecdd6ec3ceef4937cb248564a75ddb4115adc10400a8f820174b32c99c5ac6ee483c0184fed24fa44d2fd4c9dc00af9ed048b51cfdb95747ab1e35df933382b08f8223da934bfcba59cb356b0d2f4158d647ab76d09c444fadf5e92b95d65f4aae667f33835226170c6625db872a6b72cb13638cf4754941730f5117a4f7c262044bea453839f95b806a0bd98a668073ba2d0fce1ab4326f70656e53555345204275696c642053657276696365203c6275696c6473657276696365406f70656e737573652e6f72673e8864041311020024021b03060b09080703020315020303160201021e01021780050253674e3b050921bf0084000a09103b3011b76b9d65234a5b00a095c38bcfaa29f80adefc0cf9ba2abf3a3e9b516b009e367296e1a96af211f8cded2493f7f6ac09de41"), + * ); + * ``` + * + * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/openpgpkey + */ +declare function OPENPGPKEY(name: string, target: string, ...modifiers: RecordModifier[]): DomainModifier; + +/** * `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. * * ```javascript@@ -2389,7 +2929,9 @@ */ 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. + * **DEPRECATED**: This record type is deprecated. Please use `URL` (for temporary redirects) or `URL301` (for permanent redirects) instead. PORKBUN_URLFWD will continue to work but is no longer recommended for new configurations. + * + * `PORKBUN_URLFWD` is a [Porkbun](../../provider/porkbun.md)-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),@@ -2410,7 +2952,7 @@ */ declare function PORKBUN_URLFWD(name: string, target: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * PTR adds a PTR record to the domain. + * `PTR` adds a [PTR Resource record](https://www.rfc-editor.org/rfc/rfc1035) 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 * saving the user from having to reverse the IP address manually.@@ -2714,7 +3256,7 @@ * * v4 defaults to RFC 2317. In v5.0 the default will change to RFC 4183. * `REVCOMPAT()` is provided for those that wish to retain the old behavior. * - * For more information, see [Opinion #9](../../opinions.md#opinion-9-rfc-4183-is-better-than-rfc-2317). + * For more information, see [Opinion #9](../../advanced-features/opinions.md#opinion-9-rfc-4183-is-better-than-rfc-2317). * * # Transition plan *@@ -2732,7 +3274,56 @@ */ declare function REVCOMPAT(rfc: string): string; /** - * `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. + * `RP` adds an [Responsible Person record](https://www.rfc-editor.org/rfc/rfc1183) to a domain. + * + * An RP record contains contact details for the domain. Usually an email address with the `@` replaced by a `.`. + * + * The RP implementation in DNSControl is still experimental and may change. + * + * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * RP("@", "user.example.com.", "example.com."), + * ); + * ``` + * + * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/rp + */ +declare function RP(name: string, mbox: string, txt: string, ...modifiers: RecordModifier[]): DomainModifier; + +/** + * `SMIMEA` adds an [S/MIME cert association record](https://www.rfc-editor.org/rfc/rfc8162) to a domain. The name should be the hashed and stripped local part of the e-mail. + * + * To create the name, you can the following command: + * + * ```bash + * # For the e-mail bosun@bosun.org run: + * echo -n "bosun" | sha256sum | awk '{print $1}' | cut -c1-56 + * # f10e7de079689f55c0cdd6782e4dd1448c84006962a4bd832e8eff73 + * ``` + * + * Usage, selector, and type are ints. + * + * Certificate is a hex string. + * + * To create the string for the type 0, you can run this command with your S/MIME certificate: + * + * ```bash + * openssl x509 -in smime-cert.pem -outform DER | xxd -p -c 10000 + * ``` + * + * ```javascript + * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), + * // Create SMIMEA record for certificate for the name bosun + * SMIMEA("f10e7de079689f55c0cdd6782e4dd1448c84006962a4bd832e8eff73", 3, 0, 0, "30820353308202f8a003020102..."), + * ); + * ``` + * + * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/smimea + */ +declare function SMIMEA(name: string, usage: number, selector: number, type: number, certificate: string, ...modifiers: RecordModifier[]): DomainModifier; + +/** + * `SOA` adds a [Start of Authority record](https://www.rfc-editor.org/rfc/rfc1035) 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),@@ -2741,8 +3332,8 @@ * ); * ``` * * ## 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. + * * 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. * * The mbox field should not be set to a real email address unless you love spam and hate your privacy. * * There is more info about `SOA` in the documentation for the [BIND provider](../../provider/bind.md).@@ -2919,14 +3510,17 @@ * to get the entire record. (Sadly it caches heavily.) * * ## Notes about the `spfcache.json` * - * DNSControl keeps a cache of the DNS lookups performed during - * optimization. The cache is maintained so that the optimizer does - * not produce different results depending on the ups and downs of - * other people's DNS servers. This makes it possible to do `dnscontrol + * DNSControl will optionally keep a cache of the DNS lookups performed during + * optimization. In the event that a DNS server is down, the cache will be used. + * This makes it possible to do `dnscontrol * push` even if your or third-party DNS servers are down. * - * The DNS cache is kept in a file called `spfcache.json`. If it needs - * to be updated, the proper data will be written to a file called + * To enable this feature, create an (empty) file called `spfcache.json` in the + * current directory. To disable this feature, delete the file. There are no + * command-line flags related to this feature. + * + * The `spfcache.json` stored the cached DNS lookups. If it needs + * to be updated, the new file contents will be written to a file called * `spfcache.updated.json` and instructions such as the ones below * will be output telling you exactly what to do: *@@ -2942,13 +3536,9 @@ * * In this case, you are being asked to replace `spfcache.json` with * the newly generated data in `spfcache.updated.json`. * - * Needing to do this kind of update is considered a validation error - * and will block `dnscontrol push` from running. - * - * Note: The instructions are hardcoded strings. The filenames will + * The instructions are hardcoded strings. The filenames will * not change. - * - * Note: The instructions assume you use git. If you use something + * The instructions assume you use git. If you use something * else, please do the appropriate equivalent command. * * ## Caveats@@ -3005,7 +3595,7 @@ * record an include is added. * * ## Advanced Technique: Define once, use many * - * In some situations we define an SPF setting once and want to re-use + * In some situations we define an SPF setting once and want to reuse * it on many domains. Here's how to do this: * * ```javascript@@ -3037,7 +3627,7 @@ */ declare function SPF_BUILDER(opts: { label?: string; overflow?: string; overhead1?: string; raw?: string; ttl?: Duration; txtMaxSize?: number; parts: string[]; flatten?: string[] }): DomainModifier; /** - * `SRV` adds a `SRV` record to a domain. The name should be the relative label for the record. + * `SRV` adds a [Service locator record](https://www.rfc-editor.org/rfc/rfc2782) to a domain. The name should be the relative label for the record. * * Priority, weight, and port are ints. *@@ -3055,7 +3645,7 @@ */ declare function SRV(name: string, priority: number, weight: number, port: number, target: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * `SSHFP` contains a fingerprint of a SSH server which can be validated before SSH clients are establishing the connection. + * `SSHFP` adds a [SSH Public Key Fingerprint record](https://www.rfc-editor.org/rfc/rfc4255) to the domain. The record contains a fingerprint of a SSH server which can be validated before SSH clients are establishing the connection. * * **Algorithm** (type of the key) *@@ -3088,7 +3678,7 @@ */ declare function SSHFP(name: string, algorithm: 0 | 1 | 2 | 3 | 4, type: 0 | 1 | 2, value: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * SVCB adds an SVCB record to a domain. The name should be the relative label for the record. Use `@` for the domain apex. + * `SVCB` adds a [Service Binding record](https://www.rfc-editor.org/rfc/rfc9460) to a domain. The name should be the relative label for the record. Use `@` for the domain apex. * * 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). *@@ -3107,7 +3697,7 @@ */ declare function SVCB(name: string, priority: number, target: string, params: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * `TLSA` adds a `TLSA` record to a domain. The name should be the relative label for the record. + * `TLSA` adds a [TLSA certificate association record](https://www.rfc-editor.org/rfc/rfc6698) to a domain. The name should be the relative label for the record. * * Usage, selector, and type are ints. *@@ -3158,7 +3748,7 @@ */ declare function TTL(ttl: Duration): RecordModifier; /** - * `TXT` adds an `TXT` record To a domain. The name should be the relative + * `TXT` adds a [Text record](https://www.rfc-editor.org/rfc/rfc1035) 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@@ -3175,7 +3765,7 @@ * D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER), * 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("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. * );@@ -3260,18 +3850,54 @@ */ declare function TXT(name: string, contents: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * Documentation needed. + * This is provider specific type of record and not a DNS standard. It may behave differently for each provider that handles it. + * + * ### Namecheap + * + * This is a URL Redirect record with a type of "Unmasked", it creates a 302 redirect to the target. + * + * You can read more at the [Namecheap documentation](https://www.namecheap.com/support/knowledgebase/article.aspx/385/2237/how-to-set-up-a-url-redirect-for-a-domain/) + * + * ### Porkbun + * + * This creates a temporary (HTTP 302) redirect to the target URL. By default, it includes wildcard subdomains but does not include the URI path in redirection. + * + * Example: + * + * ```javascript + * D("example.com", REG_PORKBUN, DnsProvider(DSP_PORKBUN), + * URL("redirect", "https://example.org"), + * ); + * ``` * * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/url */ declare function URL(name: string, target: string, ...modifiers: RecordModifier[]): DomainModifier; /** - * Documentation needed. + * This is provider specific type of record and not a DNS standard. It may behave differently for each provider that handles it. + * + * ### Namecheap + * + * This is a URL Redirect record with a type of "Permanent", it creates a 301 redirect to the target. + * + * You can read more at the [Namecheap documentation](https://www.namecheap.com/support/knowledgebase/article.aspx/385/2237/how-to-set-up-a-url-redirect-for-a-domain/). + * + * ### Porkbun + * + * This creates a permanent (HTTP 301) redirect to the target URL. By default, it includes wildcard subdomains but does not include the URI path in redirection. + * + * Example: + * + * ```javascript + * D("example.com", REG_PORKBUN, DnsProvider(DSP_PORKBUN), + * URL301("redirect", "https://example.org"), + * ); + * ``` * * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/url301 */ -declare function URL301(name: string, ...modifiers: RecordModifier[]): DomainModifier; +declare function URL301(name: string, target: string, ...modifiers: RecordModifier[]): DomainModifier; /** * `getConfiguredDomains` getConfiguredDomains is a helper function that returns the domain names