github.com/StackExchange/dnscontrol/v4@v4.11.0/documentation/provider/bind.md (about)

     1  This provider maintains a directory with a collection of .zone files
     2  as appropriate for ISC BIND, and other systems that use the RFC 1035
     3  zone-file format.
     4  
     5  This provider does not generate or update the named.conf file, nor does it deploy the .zone files to the BIND master.
     6  Both of those tasks are different at each site, so they are best done by a locally-written script.
     7  
     8  
     9  ## Configuration
    10  
    11  To use this provider, add an entry to `creds.json` with `TYPE` set to `BIND`.
    12  
    13  Optional fields include:
    14  
    15  * `directory`: Location of the zone files.  Default: `zones` (in the current directory).
    16  * `filenameformat`: The formula used to generate the zone filenames. The default is usually sufficient.  Default: `"%U.zone"`
    17  
    18  Example:
    19  
    20  {% code title="creds.json" %}
    21  ```json
    22  {
    23    "bind": {
    24      "TYPE": "BIND",
    25      "directory": "myzones"
    26    }
    27  }
    28  ```
    29  {% endcode %}
    30  
    31  ## Meta configuration
    32  
    33  This provider accepts some optional metadata in the NewDnsProvider() call.
    34  
    35  * `default_soa`: If no SOA record exists in a zone file, one will be created. The values of the new SOA are specified here.
    36  * `default_ns`: Inject these NS records into the zone.
    37  
    38  In this example we set the default SOA settings and NS records.
    39  
    40  {% code title="dnsconfig.js" %}
    41  ```javascript
    42  var DSP_BIND = NewDnsProvider("bind", {
    43      "default_soa": {
    44          "master": "ns1.example.com.",
    45          "mbox": "spamtrap.example.com.",
    46          "refresh": 3600,
    47          "retry": 600,
    48          "expire": 604800,
    49          "minttl": 1440,
    50      },
    51      "default_ns": [
    52          "ns1.example.com.",
    53          "ns2.example.com.",
    54          "ns3.example.com.",
    55          "ns4.example.com."
    56      ]
    57  })
    58  ```
    59  {% endcode %}
    60  
    61  # FYI: SOA Records
    62  
    63  SOA records are a bit weird in DNSControl.   Most providers auto-generate SOA records and do not permit any modifications. BIND is unique in that it requires users to manage the SOA records themselves.
    64  
    65  Because BIND is unique, BIND's SOA support is kind of a hack.  It leaves the SOA record alone, with 2 exceptions:
    66  
    67  1. The serial number: If something in the zone changes, the serial number is incremented (see below).
    68  2. Missing SOAs: If there is no SOA record in a zone (or the zone is being created for the first time), the SOA is created.  The initial values are taken from the `default_soa` settings.
    69  
    70  The `default_soa` values are only used when creating an SOA for the first time. The values are not used to update an SOA.  Most people edit the SOA values by manually editing the zonefile or using the `SOA()` function.
    71  
    72  
    73  # FYI: SOA serial numbers
    74  
    75  DNSControl maintains beautiful zone serial numbers.
    76  
    77  DNSControl tries to maintain the serial number as yyyymmddvv. The algorithm for increasing the serial number is to select the max of (current serial + 1) and (yyyymmdd00). If you use a number larger than today's date (say, 2099000099) DNSControl will simply increment it forever.
    78  
    79  The good news is that DNSControl is smart enough to only increment a zone's serial number if something in the zone changed. It does not increment the serial number just because DNSControl ran.
    80  
    81  DNSControl does not handle special serial number math such as "looping through zero" nor does it pay attention to the rules around the maximum delta permitted. Those are simply avoided because yyyymmdd99 fits in the first quadrant of the 32-bit serial number space. If you don't understand this paragraph consider yourself lucky; with DNSControl you don't need to.
    82  
    83  
    84  # filenameformat
    85  
    86  The `filenameformat` parameter specifies the file name to be used when
    87  writing the zone file. The default (`%U.zone`) is acceptable in most cases: the
    88  file name is the name as specified in the `D()` function plus ".zone".
    89  
    90  The filenameformat is a string with a few printf-like `%` verbs:
    91  
    92    * `%U`  the domain name as specified in `D()`
    93    * `%D`  the domain name without any split horizon tag (the "example.com" part of "example.com!tag")
    94    * `%T`  the split horizon tag, or "" (the "tag" part of "example.com!tag")
    95    * `%?x` this returns `x` if the split horizon tag is non-null, otherwise nothing. `x` can be any printable.
    96    * `%%`  `%`
    97    * ordinary characters (not `%`) are copied unchanged to the output stream
    98    * FYI: format strings must not end with an incomplete `%` or `%?`
    99  
   100  Typical values:
   101  
   102    * `%U.zone` (The default)
   103      * `example.com.zone` or `example.com!tag.zone`
   104    * `%T%*U%D.zone`  (optional tag and `_` + domain + `.zone`)
   105      * `tag_example.com.zone` or `example.com.zone`
   106    * `db_%T%?_%D`
   107      * `db_inside_example.com` or `db_example.com`
   108    * `db_%D`
   109      * `db_example.com`
   110  
   111  The last example will generate the same name for both
   112  `D("example.com!inside")` and `D("example.com!outside")`.  This
   113  assumes two BIND providers are configured in `creds.json`, each with
   114  a different `directory` setting. Otherwise `dnscontrol` will write
   115  both domains to the same file, flapping between the two back and
   116  forth.
   117  
   118  (new in v4.2.0) `dnscontrol push` will create subdirectories along the path to
   119  the filename. This includes both the portion of the path created by the
   120  `directory` setting and the `filenameformat` setting. The automatic creation of
   121  subdirectories is disabled if `dnscontrol` is running as root for security
   122  reasons.
   123  
   124  # FYI: get-zones
   125  
   126  The DNSControl `get-zones all` subcommand scans the directory for
   127  any files named `*.zone` and assumes they are zone files.
   128  
   129  ```shell
   130  dnscontrol get-zones --format=nameonly - BIND all
   131  ```
   132  
   133  If `filenameformat` is defined, `dnscontrol` makes an guess at which
   134  filenames are zones but doesn't try to hard to get it right, which is
   135  mathematically impossible in some cases.  Feel free to file an issue if
   136  your format string doesn't work. I love a challenge!