mirror of
https://github.com/StackExchange/dnscontrol.git
synced 2024-05-11 05:55:12 +00:00
NEW FEATURE: IGNORE() (diff2 only) (#2388)
Co-authored-by: Jeffrey Cafferata <jeffrey@jcid.nl>
This commit is contained in:
Tom Limoncelli
GitHub
@ -0,0 +1,23 @@
|
||||
---
|
||||
name: DISABLE_IGNORE_SAFETY_CHECK
|
||||
---
|
||||
|
||||
`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
|
||||
deprecated as of DNSControl v4.0.0.0.
|
||||
|
||||
See [`IGNORE()`](../domain/IGNORE.md) for more information.
|
||||
|
||||
## Syntax
|
||||
|
||||
```
|
||||
D("example.com", ...
|
||||
DISABLE_IGNORE_SAFETY_CHECK,
|
||||
...
|
||||
TXT("myhost", "mytext"),
|
||||
IGNORE("myhost", "*", "*"),
|
||||
...
|
||||
```
|
||||
@ -1,8 +1,304 @@
|
||||
---
|
||||
name: IGNORE
|
||||
ts_ignore: true
|
||||
---
|
||||
|
||||
{% hint style="warning" %}
|
||||
**WARNING**: IGNORE has been renamed to `IGNORE_NAME`. IGNORE will continue to function, but its use is deprecated. Please update your configuration files to use `IGNORE_NAME`.
|
||||
`IGNORE()` makes it possible for DNSControl to share management of a domain
|
||||
with an external system. The parameters of `IGNORE()` indicate which records
|
||||
are managed elsewhere and should not be modified or deleted.
|
||||
|
||||
Use case: Suppose a domain is managed by both DNSControl and a third-party
|
||||
system. This creates a problem because DNSControl will try to delete records
|
||||
inserted by the other system. The other system may get confused and re-insert
|
||||
those records. The two systems will get into an endless update cycle where
|
||||
each will revert changes made by the other in an endless loop.
|
||||
|
||||
To solve this problem simply include `IGNORE()` statements that identify which
|
||||
records are managed elsewhere. DNSControl will not modify or delete those
|
||||
records.
|
||||
|
||||
Technically `IGNORE_NAME` is a promise that DNSControl will not modify or
|
||||
delete existing records that match particular patterns. It is like
|
||||
[`NO_PURGE`](../domain/NO_PURGE.md) that matches only specific records.
|
||||
|
||||
Including a record that is ignored is considered an error and may have
|
||||
undefined behavior. This safety check can be disabled using the
|
||||
[`DISABLE_IGNORE_SAFETY_CHECK`](../domain/DISABLE_IGNORE_SAFETY_CHECK.md) feature.
|
||||
|
||||
## Syntax
|
||||
|
||||
The `IGNORE()` function can be used with up to 3 parameters:
|
||||
|
||||
{% code %}
|
||||
```javascript
|
||||
IGNORE(labelSpec, typeSpec, targetSpec):
|
||||
IGNORE(labelSpec, typeSpec):
|
||||
IGNORE(labelSpec):
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
* `labelSpec` is a glob that matches the DNS label. For example `"foo"` or `"foo*"`. `"*"` matches all labels, as does the empty string (`""`).
|
||||
* `typeSpec` is a comma-separated list of DNS types. For example `"A"` matches DNS A records, `"A,CNAME"` matches both A and CNAME records. `"*"` matches any DNS type, as does the empty string (`""`).
|
||||
* `targetSpec` is a glob that matches the DNS target. For example `"foo"` or `"foo*"`. `"*"` matches all targets, as does the empty string (`""`).
|
||||
|
||||
`typeSpec` and `targetSpec` default to `"*"` if they are omitted.
|
||||
|
||||
## Globs
|
||||
|
||||
The `labelSpec` and `targetSpec` parameters supports glob patterns in the style
|
||||
of the [gobwas/glob](https://github.com/gobwas/glob) library. All of the
|
||||
following patterns will work:
|
||||
|
||||
* `IGNORE("*.foo")` will ignore all records in the style of `bar.foo`, but will not ignore records using a double subdomain, such as `foo.bar.foo`.
|
||||
* `IGNORE("**.foo")` will ignore all subdomains of `foo`, including double subdomains.
|
||||
* `IGNORE("?oo")` will ignore all records of three symbols ending in `oo`, for example `foo` and `zoo`. It will not match `.`
|
||||
* `IGNORE("[abc]oo")` will ignore records `aoo`, `boo` and `coo`. `IGNORE("[a-c]oo")` is equivalent.
|
||||
* `IGNORE("[!abc]oo")` will ignore all three symbol records ending in `oo`, except for `aoo`, `boo`, `coo`. `IGNORE("[!a-c]oo")` is equivalent.
|
||||
* `IGNORE("{bar,[fz]oo}")` will ignore `bar`, `foo` and `zoo`.
|
||||
* `IGNORE("\\*.foo")` will ignore the literal record `*.foo`.
|
||||
|
||||
## Typical Usage
|
||||
|
||||
General examples:
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
D("example.com", ...
|
||||
IGNORE("foo"), // matches any records on foo.example.com
|
||||
IGNORE("baz", "A"), // matches any A records on label baz.example.com
|
||||
IGNORE("*", "MX", "*"), // matches all MX records
|
||||
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);
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
Ignore Let's Encrypt (ACME) validation records:
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
D("example.com", ...
|
||||
IGNORE("_acme-challenge", "TXT"),
|
||||
IGNORE("_acme-challenge.**", "TXT"),
|
||||
END);
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
Ignore DNS records typically inserted by Microsoft ActiveDirectory:
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
D("example.com", ...
|
||||
IGNORE("_gc", "SRV"), // General Catalog
|
||||
IGNORE("_gc.**", "SRV"), // General Catalog
|
||||
IGNORE("_kerberos", "SRV"), // Kerb5 server
|
||||
IGNORE("_kerberos.**", "SRV"), // Kerb5 server
|
||||
IGNORE("_kpasswd", "SRV"), // Kpassword
|
||||
IGNORE("_kpasswd.**", "SRV"), // Kpassword
|
||||
IGNORE("_ldap", "SRV"), // LDAP
|
||||
IGNORE("_ldap.**", "SRV"), // LDAP
|
||||
IGNORE("_msdcs", "NS"), // Microsoft Domain Controller Service
|
||||
IGNORE("_msdcs.**", "NS"), // Microsoft Domain Controller Service
|
||||
IGNORE("_vlmcs", "SRV"), // FQDN of the KMS host
|
||||
IGNORE("_vlmcs.**", "SRV"), // FQDN of the KMS host
|
||||
IGNORE("domaindnszones", "A"),
|
||||
IGNORE("domaindnszones.**", "A"),
|
||||
IGNORE("forestdnszones", "A"),
|
||||
IGNORE("forestdnszones.**", "A"),
|
||||
END);
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
## Detailed examples
|
||||
|
||||
Here are some examples that illustrate how matching works.
|
||||
|
||||
All the examples assume the following DNS records are the "existing" records
|
||||
that a third-party is maintaining. (Don't be confused by the fact that we're
|
||||
using DNSControl notation for the records. Pretend some other system inserted them.)
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
D("example.com", ...
|
||||
A("@", "151.101.1.69"),
|
||||
A("www", "151.101.1.69"),
|
||||
A("foo", "1.1.1.1"),
|
||||
A("bar", "2.2.2.2"),
|
||||
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"),
|
||||
A("bar", "2.2.2.2"),
|
||||
CNAME("mshort", "www"),
|
||||
CNAME("mfull", "www.plts.org."),
|
||||
CNAME("mfull2", "www.bar.plts.org."),
|
||||
CNAME("mfull3", "bar.www.plts.org."),
|
||||
END);
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
{% code %}
|
||||
```javascript
|
||||
IGNORE("@", "", ""),
|
||||
// Would match:
|
||||
// foo.example.com. A 1.1.1.1
|
||||
// foo.more.example.com. A 1.1.1.1
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
{% code %}
|
||||
```javascript
|
||||
IGNORE("example.com.", "", ""),
|
||||
// Would match:
|
||||
// nothing
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
{% code %}
|
||||
```javascript
|
||||
IGNORE("foo", "", ""),
|
||||
// Would match:
|
||||
// foo.example.com. A 1.1.1.1
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
{% code %}
|
||||
```javascript
|
||||
IGNORE("foo.**", "", ""),
|
||||
// Would match:
|
||||
// foo.more.example.com. A 1.1.1.1
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
{% code %}
|
||||
```javascript
|
||||
IGNORE("www", "", ""),
|
||||
// Would match:
|
||||
// www.example.com. A 174.136.107.196
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
{% code %}
|
||||
```javascript
|
||||
IGNORE("www.*", "", ""),
|
||||
// Would match:
|
||||
// nothing
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
{% code %}
|
||||
```javascript
|
||||
IGNORE("www.example.com", "", ""),
|
||||
// Would match:
|
||||
// nothing
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
{% code %}
|
||||
```javascript
|
||||
IGNORE("www.example.com.", "", ""),
|
||||
// Would match:
|
||||
// none
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
{% code %}
|
||||
```javascript
|
||||
//IGNORE("", "", "1.1.1.*"),
|
||||
// Would match:
|
||||
// foo.example.com. A 1.1.1.1
|
||||
// foo.more.example.com. A 1.1.1.1
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
{% code %}
|
||||
```javascript
|
||||
//IGNORE("", "", "www"),
|
||||
// Would match:
|
||||
// none
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
{% code %}
|
||||
```javascript
|
||||
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.
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
{% code %}
|
||||
```javascript
|
||||
IGNORE("", "", "bar.**"),
|
||||
// Would match:
|
||||
// cfull3.example.com. CNAME bar.www.plts.org.
|
||||
// mfull3.more.example.com. CNAME bar.www.plts.org.
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
## Conflict handling
|
||||
|
||||
It is considered as an error for a `dnsconfig.js` to both ignore and insert the
|
||||
same record in a domain. This is done as a safety mechanism.
|
||||
|
||||
This will generate an error:
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
D("example.com", ...
|
||||
...
|
||||
TXT("myhost", "mytext"),
|
||||
IGNORE("myhost", "*", "*"), // Error! Ignoring an item we inserted
|
||||
...
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
To disable this safety check, add the `DISABLE_IGNORE_SAFETY_CHECK` statement
|
||||
to the `D()`.
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
D("example.com", ...
|
||||
DISABLE_IGNORE_SAFETY_CHECK,
|
||||
...
|
||||
TXT("myhost", "mytext"),
|
||||
IGNORE("myhost", "*", "*"),
|
||||
...
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
{% hint style="info" %}
|
||||
FYI: Previously DNSControl permitted disabling this check on
|
||||
a per-record basis using `IGNORE_NAME_DISABLE_SAFETY_CHECK`:
|
||||
{% endhint %}
|
||||
|
||||
The `IGNORE_NAME_DISABLE_SAFETY_CHECK` feature does not exist in the diff2
|
||||
world and its use will result in a validation error. Use the above example
|
||||
instead.
|
||||
|
||||
{% code %}
|
||||
```javascript
|
||||
// THIS NO LONGER WORKS! Use DISABLE_IGNORE_SAFETY_CHECK instead. See above.
|
||||
TXT("myhost", "mytext", IGNORE_NAME_DISABLE_SAFETY_CHECK),
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
## Caveats
|
||||
|
||||
{% hint style="warning" %}
|
||||
**WARNING**: Two systems updating the same domain is complex. Complex things are risky. Use `IGNORE()`
|
||||
as a last resort. Even then, test extensively.
|
||||
{% endhint %}
|
||||
|
||||
* 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.
|
||||
* `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.
|
||||
|
||||
@ -8,6 +8,12 @@ parameter_types:
|
||||
rTypes: string?
|
||||
---
|
||||
|
||||
`IGNORE_NAME(a)` is the same as `IGNORE(a, "*", "*")`.
|
||||
|
||||
## Legacy mode ("diff1")
|
||||
|
||||
When `--diff2=false` is used to revert to the old "diff1" algorithm, `IGNORE_NAME()` behaves as follows:
|
||||
|
||||
{% hint style="warning" %}
|
||||
**WARNING**: The `IGNORE_*` family of functions is risky to use. The code
|
||||
is brittle and has subtle bugs. Use at your own risk. Do not use these
|
||||
|
||||
@ -8,6 +8,14 @@ parameter_types:
|
||||
rType: string
|
||||
---
|
||||
|
||||
`IGNORE_TARGET_NAME(target)` is the same as `IGNORE("*", "*", target)`.
|
||||
|
||||
`IGNORE_TARGET_NAME(target, rtype)` is the same as `IGNORE("*", rtype, target)`.
|
||||
|
||||
## Legacy mode ("diff1")
|
||||
|
||||
When `--diff2=false` is used to revert to the old "diff1" algorithm, `IGNORE_NAME()` behaves as follows:
|
||||
|
||||
{% hint style="warning" %}
|
||||
**WARNING**: The `IGNORE_*` family of functions is risky to use. The code
|
||||
is brittle and has subtle bugs. Use at your own risk. Do not use these
|
||||
|
||||
@ -2,18 +2,28 @@
|
||||
name: NO_PURGE
|
||||
---
|
||||
|
||||
`NO_PURGE` indicates that records should not be deleted from a domain.
|
||||
`NO_PURGE` indicates that existing records should not be deleted from a domain.
|
||||
Records will be added and updated, but not removed.
|
||||
|
||||
`NO_PURGE` is generally used in very specific situations:
|
||||
Suppose a domain is managed by both DNSControl and a third-party system. This
|
||||
creates a problem because DNSControl will try to delete records inserted by the
|
||||
other system.
|
||||
|
||||
* A domain is managed by some other system and DNSControl is only used to insert a few specific records and/or keep them updated. For example a DNS Zone that is managed by Active Directory, but DNSControl is used to update a few, specific, DNS records. In this case we want to specify the DNS records we are concerned with but not delete all the other records. This is a risky use of `NO_PURGE` since, if `NO_PURGE` was removed (or buggy) there is a chance you could delete all the other records in the zone, which could be a disaster. That said, domains with some records updated using Dynamic DNS have no other choice.
|
||||
* To work-around a pseudo record type that is not supported by DNSControl. For example some providers have a fake DNS record type called "URL" which creates a redirect. DNSControl normally deletes these records because it doesn't understand them. `NO_PURGE` will leave those records alone.
|
||||
By setting `NO_PURGE` on a domain, this tells DNSControl not to delete the
|
||||
records found in the domain.
|
||||
|
||||
In this example DNSControl will insert "foo.example.com" into the
|
||||
zone, but otherwise leave the zone alone. Changes to "foo"'s IP
|
||||
address will update the record. Removing the A("foo", ...) record
|
||||
from DNSControl will leave the record in place.
|
||||
It is similar to [`IGNORE`](domain/IGNORE.md) but more general.
|
||||
|
||||
The original reason for `NO_PURGE` was that a legacy system was adopting
|
||||
DNSControl. Previously the domain was managed via Microsoft DNS Server's GUI.
|
||||
ActiveDirectory was in use, so various records were being inserted behind the
|
||||
scenes. It was decided to use DNSControl to simply insert a few records. The
|
||||
`NO_PURGE` setting instructed DNSControl not to delete the existing records.
|
||||
|
||||
In this example DNSControl will insert "foo.example.com" into the zone, but
|
||||
otherwise leave the zone alone. Changes to "foo"'s IP address will update the
|
||||
record. Removing the A("foo", ...) record from DNSControl will leave the record
|
||||
in place.
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
@ -23,19 +33,22 @@ D("example.com", .... , NO_PURGE,
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
The main caveat of `NO_PURGE` is that intentionally deleting records
|
||||
becomes more difficult. Suppose a `NO_PURGE` zone has an record such
|
||||
as A("ken", "1.2.3.4"). Removing the record from dnsconfig.js will
|
||||
not delete "ken" from the domain. DNSControl has no way of knowing
|
||||
the record was deleted from the file The DNS record must be removed
|
||||
manually. Users of `NO_PURGE` are prone to finding themselves with
|
||||
an accumulation of orphaned DNS records. That's easy to fix for a
|
||||
small zone but can be a big mess for large zones.
|
||||
The main caveat of `NO_PURGE` is that intentionally deleting records becomes
|
||||
more difficult. Suppose a `NO_PURGE` zone has an record such as A("ken",
|
||||
"1.2.3.4"). Removing the record from dnsconfig.js will not delete "ken" from
|
||||
the domain. DNSControl has no way of knowing the record was deleted from the
|
||||
file The DNS record must be removed manually. Users of `NO_PURGE` are prone
|
||||
to finding themselves with an accumulation of orphaned DNS records. That's easy
|
||||
to fix for a small zone but can be a big mess for large zones.
|
||||
|
||||
Not all providers support `NO_PURGE`. For example the BIND provider
|
||||
rewrites zone files from scratch each time, which precludes supporting
|
||||
`NO_PURGE`. DNSControl will exit with an error if `NO_PURGE` is used
|
||||
on a driver that does not support it.
|
||||
## Support
|
||||
|
||||
There is also [`PURGE`](PURGE.md) command for completeness. [`PURGE`](PURGE.md) is the
|
||||
default, thus this command is a no-op.
|
||||
Prior to DNSControl v4.0.0, not all providers supported `NO_PURGE`.
|
||||
|
||||
With introduction of `diff2` algorithm (enabled by default in v4.0.0),
|
||||
`NO_PURGE` works with all providers.
|
||||
|
||||
## See also
|
||||
|
||||
* [`PURGE`](domain/PURGE.md) is the default, thus this command is a no-op
|
||||
* [`IGNORE`](domain/IGNORE.md) is similar to `NO_PURGE` but is more selective
|
||||
|
||||
Reference in New Issue
Block a user