github.com/StackExchange/dnscontrol/v4@v4.11.0/documentation/language-reference/domain-modifiers/IGNORE.md (about)

     1  ---
     2  name: IGNORE
     3  parameters:
     4      - labelSpec
     5      - typeSpec
     6      - targetSpec
     7  parameter_types:
     8      labelSpec: string
     9      typeSpec: string?
    10      targetSpec: string?
    11  ---
    12  
    13  `IGNORE()` makes it possible for DNSControl to share management of a domain
    14  with an external system.  The parameters of `IGNORE()` indicate which records
    15  are managed elsewhere and should not be modified or deleted.
    16  
    17  Use case: Suppose a domain is managed by both DNSControl and a third-party
    18  system. This creates a problem because DNSControl will try to delete records
    19  inserted by the other system.  The other system may get confused and re-insert
    20  those records.  The two systems will get into an endless update cycle where
    21  each will revert changes made by the other in an endless loop.
    22  
    23  To solve this problem simply include `IGNORE()` statements that identify which
    24  records are managed elsewhere.  DNSControl will not modify or delete those
    25  records.
    26  
    27  Technically `IGNORE_NAME` is a promise that DNSControl will not modify or
    28  delete existing records that match particular patterns. It is like
    29  [`NO_PURGE`](../domain-modifiers/NO_PURGE.md) that matches only specific records.
    30  
    31  Including a record that is ignored is considered an error and may have
    32  undefined behavior. This safety check can be disabled using the
    33  [`DISABLE_IGNORE_SAFETY_CHECK`](../domain-modifiers/DISABLE_IGNORE_SAFETY_CHECK.md) feature.
    34  
    35  ## Syntax
    36  
    37  The `IGNORE()` function can be used with up to 3 parameters:
    38  
    39  {% code %}
    40  ```javascript
    41  IGNORE(labelSpec, typeSpec, targetSpec):
    42  IGNORE(labelSpec, typeSpec):
    43  IGNORE(labelSpec):
    44  ```
    45  {% endcode %}
    46  
    47  * `labelSpec` is a glob that matches the DNS label. For example `"foo"` or `"foo*"`.  `"*"` matches all labels, as does the empty string (`""`).
    48  * `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 (`""`).
    49  * `targetSpec` is a glob that matches the DNS target. For example `"foo"` or `"foo*"`.  `"*"` matches all targets, as does the empty string (`""`).
    50  
    51  `typeSpec` and `targetSpec` default to `"*"` if they are omitted.
    52  
    53  ## Globs
    54  
    55  The `labelSpec` and `targetSpec` parameters supports glob patterns in the style
    56  of the [gobwas/glob](https://github.com/gobwas/glob) library.  All of the
    57  following patterns will work:
    58  
    59  * `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`.
    60  * `IGNORE("**.foo")` will ignore all subdomains of `foo`, including double subdomains.
    61  * `IGNORE("?oo")` will ignore all records of three symbols ending in `oo`, for example `foo` and `zoo`. It will not match `.`
    62  * `IGNORE("[abc]oo")` will ignore records `aoo`, `boo` and `coo`. `IGNORE("[a-c]oo")` is equivalent.
    63  * `IGNORE("[!abc]oo")` will ignore all three symbol records ending in `oo`, except for `aoo`, `boo`, `coo`.        `IGNORE("[!a-c]oo")` is equivalent.
    64  * `IGNORE("{bar,[fz]oo}")` will ignore `bar`, `foo` and `zoo`.
    65  * `IGNORE("\\*.foo")` will ignore the literal record `*.foo`.
    66  
    67  ## Typical Usage
    68  
    69  General examples:
    70  
    71  {% code title="dnsconfig.js" %}
    72  ```javascript
    73  D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
    74    IGNORE("foo"), // matches any records on foo.example.com
    75    IGNORE("baz", "A"), // matches any A records on label baz.example.com
    76    IGNORE("*", "MX", "*"), // matches all MX records
    77    IGNORE("*", "CNAME", "dev-*"), // matches CNAMEs with targets prefixed `dev-*`
    78    IGNORE("bar", "A,MX"), // ignore only A and MX records for name bar
    79    IGNORE("*", "*", "dev-*"), // Ignore targets with a `dev-` prefix
    80    IGNORE("*", "A", "1\.2\.3\."), // Ignore targets in the 1.2.3.0/24 CIDR block
    81  END);
    82  ```
    83  {% endcode %}
    84  
    85  Ignore Let's Encrypt (ACME) validation records:
    86  
    87  {% code title="dnsconfig.js" %}
    88  ```javascript
    89  D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
    90    IGNORE("_acme-challenge", "TXT"),
    91    IGNORE("_acme-challenge.**", "TXT"),
    92  END);
    93  ```
    94  {% endcode %}
    95  
    96  Ignore DNS records typically inserted by Microsoft ActiveDirectory:
    97  
    98  {% code title="dnsconfig.js" %}
    99  ```javascript
   100  D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
   101    IGNORE("_gc", "SRV"), // General Catalog
   102    IGNORE("_gc.**", "SRV"), // General Catalog
   103    IGNORE("_kerberos", "SRV"), // Kerb5 server
   104    IGNORE("_kerberos.**", "SRV"), // Kerb5 server
   105    IGNORE("_kpasswd", "SRV"), // Kpassword
   106    IGNORE("_kpasswd.**", "SRV"), // Kpassword
   107    IGNORE("_ldap", "SRV"), // LDAP
   108    IGNORE("_ldap.**", "SRV"), // LDAP
   109    IGNORE("_msdcs", "NS"), // Microsoft Domain Controller Service
   110    IGNORE("_msdcs.**", "NS"), // Microsoft Domain Controller Service
   111    IGNORE("_vlmcs", "SRV"), // FQDN of the KMS host
   112    IGNORE("_vlmcs.**", "SRV"), // FQDN of the KMS host
   113    IGNORE("domaindnszones", "A"),
   114    IGNORE("domaindnszones.**", "A"),
   115    IGNORE("forestdnszones", "A"),
   116    IGNORE("forestdnszones.**", "A"),
   117  END);
   118  ```
   119  {% endcode %}
   120  
   121  ## Detailed examples
   122  
   123  Here are some examples that illustrate how matching works.
   124  
   125  All the examples assume the following DNS records are the "existing" records
   126  that a third-party is maintaining. (Don't be confused by the fact that we're
   127  using DNSControl notation for the records. Pretend some other system inserted them.)
   128  
   129  {% code title="dnsconfig.js" %}
   130  ```javascript
   131  D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
   132      A("@", "151.101.1.69"),
   133      A("www", "151.101.1.69"),
   134      A("foo", "1.1.1.1"),
   135      A("bar", "2.2.2.2"),
   136      CNAME("cshort", "www"),
   137      CNAME("cfull", "www.plts.org."),
   138      CNAME("cfull2", "www.bar.plts.org."),
   139      CNAME("cfull3", "bar.www.plts.org."),
   140  END);
   141  
   142  D_EXTEND("more.example.com",
   143      A("foo", "1.1.1.1"),
   144      A("bar", "2.2.2.2"),
   145      CNAME("mshort", "www"),
   146      CNAME("mfull", "www.plts.org."),
   147      CNAME("mfull2", "www.bar.plts.org."),
   148      CNAME("mfull3", "bar.www.plts.org."),
   149  END);
   150  ```
   151  {% endcode %}
   152  
   153  {% code %}
   154  ```javascript
   155      IGNORE("@", "", ""),
   156      // Would match:
   157      //    foo.example.com. A 1.1.1.1
   158      //    foo.more.example.com. A 1.1.1.1
   159  ```
   160  {% endcode %}
   161  
   162  {% code %}
   163  ```javascript
   164      IGNORE("example.com.", "", ""),
   165      // Would match:
   166      //    nothing
   167  ```
   168  {% endcode %}
   169  
   170  {% code %}
   171  ```javascript
   172      IGNORE("foo", "", ""),
   173      // Would match:
   174      //    foo.example.com. A 1.1.1.1
   175  ```
   176  {% endcode %}
   177  
   178  {% code %}
   179  ```javascript
   180      IGNORE("foo.**", "", ""),
   181      // Would match:
   182      //    foo.more.example.com. A 1.1.1.1
   183  ```
   184  {% endcode %}
   185  
   186  {% code %}
   187  ```javascript
   188      IGNORE("www", "", ""),
   189      // Would match:
   190      //    www.example.com. A 174.136.107.196
   191  ```
   192  {% endcode %}
   193  
   194  {% code %}
   195  ```javascript
   196      IGNORE("www.*", "", ""),
   197      // Would match:
   198      //    nothing
   199  ```
   200  {% endcode %}
   201  
   202  {% code %}
   203  ```javascript
   204      IGNORE("www.example.com", "", ""),
   205      // Would match:
   206      //    nothing
   207  ```
   208  {% endcode %}
   209  
   210  {% code %}
   211  ```javascript
   212      IGNORE("www.example.com.", "", ""),
   213      // Would match:
   214      //    none
   215  ```
   216  {% endcode %}
   217  
   218  {% code %}
   219  ```javascript
   220      //IGNORE("", "", "1.1.1.*"),
   221      // Would match:
   222      //    foo.example.com. A 1.1.1.1
   223      //    foo.more.example.com. A 1.1.1.1
   224  ```
   225  {% endcode %}
   226  
   227  {% code %}
   228  ```javascript
   229      //IGNORE("", "", "www"),
   230      // Would match:
   231      //    none
   232  ```
   233  {% endcode %}
   234  
   235  {% code %}
   236  ```javascript
   237      IGNORE("", "", "*bar*"),
   238      // Would match:
   239      //    cfull2.example.com. CNAME www.bar.plts.org.
   240      //    cfull3.example.com. CNAME bar.www.plts.org.
   241      //    mfull2.more.example.com. CNAME www.bar.plts.org.
   242      //    mfull3.more.example.com. CNAME bar.www.plts.org.
   243  ```
   244  {% endcode %}
   245  
   246  {% code %}
   247  ```javascript
   248      IGNORE("", "", "bar.**"),
   249      // Would match:
   250      //    cfull3.example.com. CNAME bar.www.plts.org.
   251      //    mfull3.more.example.com. CNAME bar.www.plts.org.
   252  ```
   253  {% endcode %}
   254  
   255  ## Conflict handling
   256  
   257  It is considered as an error for a `dnsconfig.js` to both ignore and insert the
   258  same record in a domain. This is done as a safety mechanism.
   259  
   260  This will generate an error:
   261  
   262  {% code title="dnsconfig.js" %}
   263  ```javascript
   264  D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
   265      ...
   266      TXT("myhost", "mytext"),
   267      IGNORE("myhost", "*", "*"),  // Error!  Ignoring an item we inserted
   268      ...
   269  ```
   270  {% endcode %}
   271  
   272  To disable this safety check, add the `DISABLE_IGNORE_SAFETY_CHECK` statement
   273  to the `D()`.
   274  
   275  {% code title="dnsconfig.js" %}
   276  ```javascript
   277  D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
   278      DISABLE_IGNORE_SAFETY_CHECK,
   279      ...
   280      TXT("myhost", "mytext"),
   281      IGNORE("myhost", "*", "*"),
   282      ...
   283  ```
   284  {% endcode %}
   285  
   286  {% hint style="info" %}
   287  FYI: Previously DNSControl permitted disabling this check on
   288  a per-record basis using `IGNORE_NAME_DISABLE_SAFETY_CHECK`:
   289  {% endhint %}
   290  
   291  The `IGNORE_NAME_DISABLE_SAFETY_CHECK` feature does not exist in the diff2
   292  world and its use will result in a validation error. Use the above example
   293  instead.
   294  
   295  {% code %}
   296  ```javascript
   297      // THIS NO LONGER WORKS! Use DISABLE_IGNORE_SAFETY_CHECK instead. See above.
   298      TXT("myhost", "mytext", IGNORE_NAME_DISABLE_SAFETY_CHECK),
   299  ```
   300  {% endcode %}
   301  
   302  ## Caveats
   303  
   304  {% hint style="warning" %}
   305  **WARNING**: Two systems updating the same domain is complex.  Complex things are risky. Use `IGNORE()`
   306  as a last resort. Even then, test extensively.
   307  {% endhint %}
   308  
   309  * There is no locking.  If the external system and DNSControl make updates at the exact same time, the results are undefined.
   310  * 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.
   311  * `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.
   312  * 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.