Rename negative_ttl into default_ttl

README.md

@@ -13,15 +13,14 @@ Features:
   * automatic zone DNSSEC configuration
   * support to send DNSKEY/DS formatted output over XMPP
 * Support for hidden primary and authoritative secondary configuration
-* Basic support for dynamic creation of zone files from variables
-
-## Basic usage - master and slave server with static zones and forwarder
-
-* place your zone file in ansible directory (not in role directory): files/bind/zones/db.example.com
-* set vars for your master server:
-
-
-```
+* Support for so called "static" zones, i.e. zones defined uploading their raw .db bind file
+* Validity check of zone files with named-checkzone
+* Basic support for so called "dynamic" zones, i.e. defined from variables yaml variables sets
+
+## Basic server configuration
+### Master server
+* set vars for your master server, for instance in `host_vars/master_name/vars/XX_bind.yml`, here with an example.com static zones and forwarder:
+```yaml
 bind9_authoritative: yes
 bind9_zones_static: 
 - { name: example.com , type=master }
@@ -38,10 +37,13 @@ bind9_our_neighbors:
 - slave_ip_2
 - slave_ip_3
 ```
-* set vars for your slave server:
+* Place your BIND zone file in ansible directory (not in role directory): `files/bind/zones/db.example.com
 
+### Slave servers
 
-```
+* set vars for your slave servers:
+
+```yaml
 bind9_zones_static: 
 - { name: example.com, type: slave }
 bind9_forward: yes
@@ -52,7 +54,56 @@ bind9_masters:
 - { name: master_name, addresses: [master_ip] }
 bind9_recursor: our_network
 ```
+### Dynamic zones
+So called "dynamic" zones' records are defined through YAML ansible variable `bind9_zones_dynamic` which is parsed by [`bind/zones/db.template.j2`](templates/bind/zones/db.template.j2) template.
+As there can be several zones, and zones definitions can be long, zones vars are worthly defined in a different vars' file, for instance `host_vars/master_name/vars/YY_zones.yml`, and  `bind9_zones_dynamic` can be splited in several variables, that can bie defined in specific files. In `YY_zones.yml` we may have:
+```yaml
+bind9_zones_dynamic: >
+        {{ zones_my_domains
+        | union ( zone_my_reverse_inaddr_arpa )
+        | union ( zone_my_reverse_ip6_arpa ) }}
+
+# bind9_zone_static:  zone files copied from `files/bind/zones/`
+
+bind9_zones_static:
+- name: static_dom.org
+  type: master
+- name: static_dom2.org
+  type: master
+- name: static_dom3.org
+  type: slave
+```
+And in other vars files:
+```yaml
+zones_my_domains:
+# This is the variables set for my domain
+- name: dyn_domain.org
+  type: master
+  default_ttl: 600
+  serial: 2022050501
+  refresh: 1D
+  retry: 2H
+  expire: 1000H
+  # NS and other pre-formatted records values must be given as full qualified domain names, with or without final dot, but not relative to the zone
+  primary: ns1.dyn_domain.org         # Optional, if you don't define it, firs NS is taken 
+  admin: postmaster.dyn_domain.org
+  ns_records:
+  - ns1.dyn_domain.org
+  - ns2.dyn_domain.org
+  # RR values are either relative to the zone, either with a final dot when outside.
+  rrs:
+  - {label: "@", type: MX, rdata: 10 mail}
+  - {label: webmail, type: CNAME, rdata: mail}
+  - {label: "@", type: A, rdata: 8.8.8.221}
+  - {label: "@", type: AAAA, rdata: 2001:db8:6a::95}
+  - {label: www, type: CNAME, rdata: webserver.dyn_domain.org.}
+  - {label: mail, type: A, rdata: 8.8.8.222}
+  - {label: mail, type: AAAA, rdata: 2001:db8:6a::22}
+  - {label: webserver, ttl: 86400, type: A, rdata: 8.8.8.223}
+  - {label: webserver, ttl: 86400, type: AAAA, rdata: 2001:db8:6a::23}
+```
 
+And similarly `zone_my_reverse_inaddr_arpa` and `zone_my_reverse_ip6_arpa` for IP reverse DNS resolution. Note that we adopted for generic NS records the terminology defined in [RFC 1034, Section 3.6](https://datatracker.ietf.org/doc/html/rfc1034#section-3.6)
 
 * deploy role to your servers
 

templates/bind/zones/db.template.j2

@@ -21,8 +21,9 @@
 #}{% set zone=item %}
 ;; {{ ansible_managed }}
 $ORIGIN .
-$TTL {{ zone.negative_ttl|default('3600') }}   ; 1 hour
-{# We first deal in detail with SOA and NS, which is requiered, and root zone registers
+{# Default TTL of zone records. `negative_ttl` is a deprecated name of this variable.  #}
+$TTL {{ zone.default_ttl|default(zone.negative_ttl|default('3600')) }}   ; 1 hour. 
+{# We first deal in detail with SOA and NS, which are requiered, and root zone registers
    Empezamos detallando el SOA y NS, que son indispensables, y registros de raíz de zona #}
 {{ zone.name }} IN  SOA     {{ zone.primary|default(zone.ns_records.0) }}. {{ zone.admin|default(bind9_admin) }}. (
                 {{ zone.serial }} ; serial