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

     1  This provider uses the native DNS protocols. It uses the AXFR (RFC5936,
     2  Zone Transfer Protocol) to retrieve the existing records and DDNS
     3  (RFC2136, Dynamic Update) to make corrections. It can use TSIG (RFC2845) or
     4  IP-based authentication (ACLs).
     5  
     6  It is able to work with any standards-compliant
     7  authoritative DNS server. It has been tested with
     8  [BIND](https://www.isc.org/bind/), [Knot](https://www.knot-dns.cz/),
     9  and [Yadifa](https://www.yadifa.eu/home).
    10  
    11  ## Configuration
    12  
    13  To use this provider, add an entry to `creds.json` with `TYPE` set to `AXFRDDNS`.
    14  
    15  ### Connection modes
    16  
    17  Zone transfers default to TCP, DDNS updates default to UDP when
    18  using this provider.
    19  
    20  The following two parameters in `creds.json` allow switching
    21  to TCP or TCP over TLS.
    22  
    23  * `update-mode`: May contain `udp` (the default), `tcp`, or `tcp-tls`.
    24  * `transfer-mode`: May contain `tcp` (the default), or `tcp-tls`.
    25  
    26  ### Authentication
    27  
    28  Authentication information is included in the `creds.json` entry for
    29  the provider:
    30  
    31  * `transfer-key`: If this exists, the value is used to authenticate AXFR transfers.
    32  * `update-key`: If this exists, the value is used to authenticate DDNS updates.
    33  
    34  For instance, your `creds.json` might looks like:
    35  
    36  {% code title="creds.json" %}
    37  ```json
    38  {
    39    "axfrddns": {
    40      "TYPE": "AXFRDDNS",
    41      "transfer-key": "hmac-sha256:transfer-key-id:Base64EncodedSecret=",
    42      "update-key": "hmac-sha256:update-key-id:AnotherSecret="
    43    }
    44  }
    45  ```
    46  {% endcode %}
    47  
    48  If either key is missing, DNSControl defaults to IP-based ACL
    49  authentication for that function. Including both keys is the most
    50  secure option. Omitting both keys defaults to IP-based ACLs for all
    51  operations, which is the least secure option.
    52  
    53  If distinct zones require distinct keys, you will need to instantiate the
    54  provider once for each key:
    55  
    56  {% code title="dnsconfig.js" %}
    57  ```javascript
    58  var DSP_AXFRDDNS_A = NewDnsProvider("axfrddns-a");
    59  var DSP_AXFRDDNS_B = NewDnsProvider("axfrddns-b");
    60  ```
    61  {% endcode %}
    62  
    63  And update `creds.json` accordingly:
    64  
    65  {% code title="creds.json" %}
    66  ```json
    67  {
    68    "axfrddns-a": {
    69      "TYPE": "AXFRDDNS",
    70      "transfer-key": "hmac-sha256:transfer-key-id:Base64EncodedSecret=",
    71      "update-key": "hmac-sha256:update-key-id:AnotherSecret="
    72    },
    73    "axfrddns-b": {
    74      "TYPE": "AXFRDDNS",
    75      "transfer-key": "hmac-sha512:transfer-key-id-B:SmallSecret=",
    76      "update-key": "hmac-sha512:update-key-id-B:YetAnotherSecret="
    77    }
    78  }
    79  ```
    80  {% endcode %}
    81  
    82  ### Default nameservers
    83  
    84  The AXFR+DDNS provider can be configured with a list of default
    85  nameservers. They will be added to all the zones handled by the
    86  provider.
    87  
    88  This list can be provided either as metadata or in `creds.json`. Only
    89  the later allows `get-zones` to work properly.
    90  
    91  {% code title="dnsconfig.js" %}
    92  ```javascript
    93  var DSP_AXFRDDNS = NewDnsProvider("axfrddns", {
    94          "default_ns": [
    95              "ns1.example.com.",
    96              "ns2.example.com.",
    97              "ns3.example.com.",
    98              "ns4.example.com."
    99          ]
   100      }
   101  )
   102  ```
   103  {% endcode %}
   104  
   105  {% code title="creds.json" %}
   106  ```json
   107  {
   108    "axfrddns": {
   109      "TYPE": "AXFRDDNS",
   110      "nameservers": "ns1.example.com,ns2.example.com,ns3.example.com,ns4.example.com"
   111    }
   112  }
   113  ```
   114  {% endcode %}
   115  
   116  ### Primary master
   117  
   118  By default, the AXFR+DDNS provider will send the AXFR requests and the
   119  DDNS updates to the first nameserver of the zone, usually known as the
   120  "primary master". Typically, this is the first of the default
   121  nameservers. Though, on some networks, the primary master is a private
   122  node, hidden behind slaves, and it does not appear in the `NS` records
   123  of the zone. In that case, the IP or the name of the primary server
   124  must be provided in `creds.json`. With this option, a non-standard
   125  port might be used.
   126  
   127  {% code title="creds.json" %}
   128  ```json
   129  {
   130    "axfrddns": {
   131      "TYPE": "AXFRDDNS",
   132      "master": "10.20.30.40:5353"
   133    }
   134  }
   135  ```
   136  {% endcode %}
   137  
   138  When no nameserver appears in the zone, and no default nameservers nor
   139  custom master are configured, the AXFR+DDNS provider will fail with
   140  the following error message:
   141  
   142  ```text
   143  [Error] AXFRDDNS: the nameservers list cannot be empty.
   144  Please consider adding default `nameservers` or an explicit `master` in `creds.json`.
   145  ```
   146  
   147  ### Transfer/AXFR server
   148  
   149  As mentioned above, the AXFR+DDNS provider will send AXFR requests to the
   150  primary master for the zone. On some networks, the AXFR requests are handled
   151  by a separate server to DDNS requests. Use the `transfer-server` option in
   152  `creds.json`. If not specified, it falls back to the primary master.
   153  
   154  {% code title="creds.json" %}
   155  ```json
   156  {
   157    "axfrddns": {
   158      "TYPE": "AXFRDDNS",
   159      "transfer-server": "233.252.0.0"
   160    }
   161  }
   162  ```
   163  {% endcode %}
   164  
   165  ### Buggy DNS servers regarding CNAME updates
   166  
   167  When modifying a CNAME record, or when replacing an A record by a
   168  CNAME one in a single batched DDNS update, some DNS servers
   169  (e.g. Knot) will incorrectly reject the update. For this particular
   170  case, you might set the option `buggy-cname = "yes"` in `creds.json`.
   171  The changes will then be split in two DDNS updates, applied
   172  successively by the server. This will allow Knot to successfully apply
   173  the changes, but you will loose the atomic-update property.
   174  
   175  ### Example: local testing
   176  
   177  When testing `dnscontrol` against a local nameserver, you might use
   178  the following minimal configuration:
   179  
   180  {% code title="creds.json" %}
   181  ```json
   182  {
   183    "axfrddns": {
   184      "TYPE": "AXFRDDNS",
   185      "master": "127.0.0.1"
   186    }
   187  }
   188  ```
   189  {% endcode %}
   190  
   191  {% code title="dnsconfig.js" %}
   192  ```javascript
   193  var REG_NONE = NewRegistrar("none");
   194  var DNS = NewDnsProvider("axfrddns", {
   195      default_ns: [
   196          "ns.example.com.",
   197      ],
   198  });
   199  
   200  D("example.com", REG_NONE, DnsProvider(DNS),
   201      A("ns", "127.0.0.1")
   202  )
   203  ```
   204  {% endcode %}
   205  
   206  
   207  ## Server configuration examples
   208  
   209  ### Bind9
   210  
   211  Here is a sample `named.conf` example for an authauritative server on
   212  zone `example.com`. It uses a simple IP-based ACL for the AXFR
   213  transfer and a conjunction of TSIG and IP-based ACL for the updates.
   214  
   215  {% code title="named.conf" %}
   216  ```text
   217  options {
   218  
   219      listen-on { any; };
   220      listen-on-v6 { any; };
   221  
   222      allow-query { any; };
   223      allow-notify { none; };
   224      allow-recursion { none; };
   225      allow-transfer { none; };
   226      allow-update { none; };
   227      allow-query-cache { none; };
   228  
   229  };
   230  
   231  zone "example.com" {
   232    type master;
   233    file "/etc/bind/db.example.com";
   234    allow-transfer { example-transfer; };
   235    allow-update { example-update; };
   236  };
   237  
   238  ## Allow transfer to anyone on our private network
   239  
   240  acl example-transfer {
   241      172.17.0.0/16;
   242  };
   243  
   244  ## Allow update only from authenticated client on our private network
   245  
   246  acl example-update {
   247    ! {
   248     !172.17.0.0/16;
   249     any;
   250    };
   251    key update-key-id;
   252  };
   253  
   254  key update-key-id {
   255    algorithm HMAC-SHA256;
   256    secret "AnotherSecret=";
   257  };
   258  ```
   259  {% endcode %}
   260  
   261  ## FYI: get-zones
   262  
   263  When using `get-zones`, a custom master or a list of default
   264  nameservers should be configured in `creds.json`.
   265  
   266  THe AXFR+DDNS provider does not display DNSSec records. But, if any
   267  DNSSec records is found in the zone, it will replace all of them with
   268  a single placeholder record:
   269  
   270  ```text
   271      __dnssec         IN TXT   "Domain has DNSSec records, not displayed here."
   272  ```
   273  
   274  ## FYI: create-domain
   275  
   276  The AXFR+DDNS provider is not able to create domain.
   277  
   278  ## FYI: AUTODNSSEC
   279  
   280  The AXFR+DDNS provider is not able to ask the DNS server to sign the zone. But, it is able to check whether the server seems to do so or not.
   281  
   282  When AutoDNSSEC is enabled, the AXFR+DDNS provider will emit a warning when no RRSIG, DNSKEY or NSEC records are found in the zone.
   283  
   284  When AutoDNSSEC is disabled, the AXFR+DDNS provider will emit a warning when RRSIG, DNSKEY or NSEC records are found in the zone.
   285  
   286  When AutoDNSSEC is not enabled or disabled, no checking is done.
   287  
   288  ## FYI: MD5 Support
   289  
   290  By default the used DNS Go package by miekg has deprecated supporting the (insecure) MD5 algorithm [https://github.com/miekg/dns/commit/93945c284489394b77653323d11d5de83a2a6fb5](https://github.com/miekg/dns/commit/93945c284489394b77653323d11d5de83a2a6fb5). Some providers like the Leibniz Supercomputing Centre (LRZ) located in Munich still use this algorithm to authenticate internal dynamic DNS updates. To compensate the lack of MD5 a custom MD5 TSIG Provider was added into DNSControl.