Merge branch 'dak-main-patch-16249' into 'main'

Update README.md

See merge request operations/ansible-bind9-role!2

README.md

@@ -20,6 +20,68 @@ Or, as I call them "happy accidents".
 * If you need a variable to be 0 or null, you need to define it as `var: '0'` or `var: 'null'`, otherwise jinja will assume you want it to be empty/null. Normal integers would be defined as `var: 1`, letting jinja type it as an integer.
 * If a named configuration option has the name 'key' or 'keys', it will be referenced as 'keyname' or 'keylist' respectively. key/keys are reserved values in most languages.
 
+Role Variables
+--------------
+
+General configuration
+=====================
+Review the [defaults](defaults/main.yml) for a full set of configurable parameters. Here are the most interesting ones:
+
+`bind9_backup_config: [true, false]`: Backup each named.conf.* file or not. Default is 'true'. This setting is useful for testing out configuration changes but can clutter up the destination directory quite a bit if used across many updates.
+
+`bind9_debug_config: [true, false]`: Print the resulting YAML configuration tree that was sent to the configuration template. Default is 'false'. Useful for comparing with the resulting named.conf files and comparing values.
+
+`bind9_config_indent: [integer]`: Indentation level for the configuration template. Default is '4'. Set this value to suit your style. Tabs are not supported.
+
+named.conf
+==========
+bind configuration is set through the various bind9_*_config parameters. These are, in order of precedence:
+1. bind9_default_config
+2. bind9_group_config
+3. bind9_leaf_config
+4. bind9_host_config
+
+All these configuration parameters are merged in a way where each successing config supercedes the previous one at a config-file level. To illustrate:
+
+```
+bind9_default_config:
+  - name: named.conf.options
+    options:
+      recursion: true
+
+bind9_group_config:
+  - name: named.conf.options
+    options:
+      recursion: false
+      notify: primary-only
+  - name: named.conf.local
+    zone:
+      - name: "."
+        type: mirror
+
+bind9_leaf_config:
+  - name: named.conf.local
+    zone:
+      - name: "."
+        type: hint
+        file: /etc/share/dns/root.hints
+```
+The resulting precedence and overwriting of variables will result in the following bind9_config passed to the configuration generator:
+
+```
+bind9_config:
+  - name: named.conf.options
+    options:
+      recursion: false
+  - name: named.conf.local
+    zone:
+      - name: "."
+        type: hint
+        file: /etc/share/dns/root.hints
+```
+
+The `named.conf.options` block in `bind9_default_config` got completely overwritten by the `bind9_group_config`, and the `bind9_leaf_config` completely overwrote `named.conf.local`, however, `named.conf.options` was left intact after merging with `bind9_leaf_config`.
+
 Configuration Grammar
 ---------------------
 The bind9 role tries to replicate the official ISC bind9 configuration format as close as possible,
@@ -97,67 +159,6 @@ configuration format has been created
           port: PORT
 ```
 
-Role Variables
---------------
-
-General configuration
-=====================
-Review the [defaults](defaults/main.yml) for a full set of configurable parameters. Here are the most interesting ones:
-
-`bind9_backup_config: [true, false]`: Backup each named.conf.* file or not. Default is 'true'. This setting is useful for testing out configuration changes but can clutter up the destination directory quite a bit if used across many updates.
-
-`bind9_debug_config: [true, false]`: Print the resulting YAML configuration tree that was sent to the configuration template. Default is 'false'. Useful for comparing with the resulting named.conf files and comparing values.
-
-`bind9_config_indent: [integer]`: Indentation level for the configuration template. Default is '4'. Set this value to suit your style. Tabs are not supported.
-
-named.conf
-==========
-bind configuration is set through the various bind9_*_config parameters. These are, in order of precedence:
-1. bind9_default_config
-2. bind9_group_config
-3. bind9_leaf_config
-4. bind9_host_config
-
-All these configuration parameters are merged in a way where each successing config supercedes the previous one at a config-file level. To illustrate:
-
-```
-bind9_default_config:
-  - name: named.conf.options
-    options:
-      recursion: true
-
-bind9_group_config:
-  - name: named.conf.options
-    options:
-      recursion: false
-      notify: primary-only
-  - name: named.conf.local
-    zone:
-      - name: "."
-        type: mirror
-
-bind9_leaf_config:
-  - name: named.conf.local
-    zone:
-      - name: "."
-        type: hint
-        file: /etc/share/dns/root.hints
-```
-The resulting precedence and overwriting of variables will result in the following bind9_config passed to the configuration generator:
-
-```
-bind9_config:
-  - name: named.conf.options
-    options:
-      recursion: false
-  - name: named.conf.local
-    zone:
-      - name: "."
-        type: hint
-        file: /etc/share/dns/root.hints
-```
-
-The `named.conf.options` block in `bind9_default_config` got completely overwritten by the `bind9_group_config`, and the `bind9_leaf_config` completely overwrote `named.conf.local`, however, `named.conf.options` was left intact after merging with `bind9_leaf_config`.
 
 Dependencies
 ------------
@@ -196,452 +197,5 @@ BSD
 Author Information
 ------------------
 
-An optional section for the role authors to include contact information, or a website (HTML is not allowed).
-
-```
-    options:
-      forwarders:
-        - 1.1.1.1
-        - 1.0.0.1
-      fetches_per_server: 200 fail
-      prefetch: 4 10
-      version: none
-      hostname: l33t.h4x0r
-      avoid_v4_udp_ports:
-        - "range 5132 5232"
-        - "range 1337 31337"
-      servfail_ttl: 0
-      allow_notify:
-        - 10.0.0.0/8
-      allow_query:
-        - "!10.0.2.1"
-        - 0/0
-      blackhole:
-        - 192.168.0.0/16
-      allow_recursion: []
-      empty_server: "empty.server.string"
-      dns64_server: "server.name"
-      dns64_contact: "dak.keepit.com"
-      directory: "{{ bind9_cachedir }}"
-      key_directory: "{{ bind9_cachedir }}/keys"
-      statistics_file: "{{ bind9_cachedir }}/named.stats"
-      rrset_order:
-        - type: A
-          name: foo.isc.org
-          order: random
-        - type: AAAA
-          name: foo.isc.org
-          order: cyclic
-        - name: bar.isc.org
-          order: random
-        - name: "*.bar.isc.org"
-          order: random
-        - name: "*.baz.isc.org"
-          order: cyclic
-      response_policy:
-        zones:
-          - zone: smorg.bop
-            max_policy_ttl: 30S
-            min_update_interval: 30S
-            policy: disabled
-            add_soa: true
-            log: true
-            recursive_only: false
-            nsip_enable: true
-            nsdname_enable: true
-        max_policy_ttl: 30S
-        min_update_interval: 30S
-        min_ns_dots: 2
-        add_soa: false
-        break_dnssec: false
-        nsip_wait_recurse: true
-        nsdname_wait_recurse: true
-        qname_wait_recurse: true
-        recursive_only: true
-        nsip_enable: true
-        nsdname_enable: true
-        dnsrps_enable: false
-        dnsrps_options:
-          - simple
-          - item
-          - list
-      response_padding:
-        block_size: 4096
-        addresses:
-          - 0/0
-      rate_limit:
-        all_per_second: 0
-        errors_per_second: 0
-        responses_per_second: 0
-        referrals_per_second: 0
-        nodata_per_second: 0
-        nxdomains_per_second: 0
-        ipv4_prefix_length: 24
-        ipv6_prefix_length: 54
-        max_table_size: 20000
-        min_table_size: 500
-        qps_scale: 250
-        slip: 2
-        window: 15
-        log_only: true
-        exempt_clients:
-          - 192.168.0.1
-          - 10.20.30.40
-      query_source_v6:
-        address: "*"
-        port: "*"
-        dscp: 42
-      parental_source_v6:
-        address: "*"
-        port: "*"
-        dscp: 42
-      notify_source_v6:
-        address: "*"
-      notify_source:
-        address: "*"
-      listen_on:
-        - port: 53
-          addresses:
-            - 0.0.0.0
-        - port: 5353
-          dscp: 42
-          addresses:
-            - 0.0.0.0
-            - 127.0.0.1
-      listen_on_v6:
-        - port: 5353
-          dscp: 42
-          addresses:
-            - "::"
-            - "de:ad::be:ef"
-      dialup: false
-      minimal_responses: true
-      zone_statistics: full
-      ixfr_from_differences: master
-      dual_stack_servers:
-        port: 4492
-        addresses:
-          - address: hostname.com
-            port: 4421
-            dscp: 42
-          - address: 10.128.128.182
-          - address: de:ad::be:ef
-      dnstap:
-        - type: auth
-        - type: client
-          log: response
-        - type: resolver
-          log: query
-      dnstap_output:
-        output_type: file
-        output_file: /tmp/dnstap
-        size: 10M
-        versions: 200
-        suffix: increment
-  - name: named.conf.local
-    acl:
-      localstuff:
-        - 10.0.0.0/8
-        - 192.168.0.0/16
-        - 172.16.0.0/12
-      external:
-        - 185.181.220.77
-        - "!0.0.0.0/0"
-    controls:
-      - type: inet
-        address: 127.0.0.1
-        port: 533
-        allow:
-          - 127.0.0.0/8
-          - "!127.13.37.1"
-        readonly: false
-      - type: inet
-        address: 10.20.30.40
-        allow:
-          - 100.0.0.0/8
-    view:
-      - name: recursive-view
-        match_clients:
-          - localstuff
-        match_destinations:
-          - remote
-        match-recursive-only: true
-        options:
-          transfer_source:
-            address: 0.0.0.0
-            port: '*'
-            dscp: 42
-          allow_recursion:
-            - localstuff
-        zones:
-          - name: google.com
-            type: forward
-            forward: only
-            forwarders:
-              - 1.1.1.1
-              - 1.0.0.1
-    dnssec_policy:
-      - name: mypolicy
-        keylist:
-          - role: ksk
-            key_directory: true
-            lifetime: unlimited
-            algorithm: rsasha256
-            keysize: 2048
-          - role: zsk
-            lifetime: P30D
-            algorithm: 8
-          - role: csk
-            lifetime: P6MT12H3M15S
-            algorithm: ecdsa256
-        max_zone_ttl: P4D
-        parent_ds_ttl: P14D
-        nsec3param:
-          iterations: '0'
-          optout: false
-          salt_length: '0'
-    dyndb:
-      - name: sample
-        driver: example.so
-        parameters:
-          - example.nil. arpa.
-          - example2.nil. arpa.
-    http:
-      - name: dohconf
-        endpoints:
-          - /dns-query
-          - /dns
-          - /query
-        listener_clients: 4
-        streams_per_connection: 1024
-    keylist:
-      - name: certbot.
-        algorithm: hmac-sha512
-        secret: "agyMWst4ZcbhGKqGuR6Pjgz1KJSHdcM0s5tz06n+ZxpfZYVWP67E2cr7Mru+HQRLl7HEBE5Zl4vS3S+SA4kXrA=="
-      - name: certbot2.
-        algorithm: hmac-sha512
-        secret: "agyMWst4ZcbhGKqGuR6Pjgz1KJSHdcM0s5tz06n+ZxpfZYVWP67E2cr7Mru+HQRLl7HEBE5Zl4vS3S+SA4kXrA=="
-    logging:
-      categories:
-        - name: default
-          channels:
-            - default_syslog
-            - default_debug
-            - tv2
-            - dr1
-        - name: unmatched
-          channels:
-            - tv3
-      channels:
-        - name: tv2
-          buffered: true
-          file:
-            name: /var/log/named.log
-            versions: 7
-            size: 20m
-            suffix: increment
-          print_category: false
-          print_severity: false
-          print_time: iso8601-utc
-          severity: info
-        - name: tv3
-          'null': true
-        - name: dr1
-          syslog: daemon
-        - name: kanalkobenhavn
-          stderr: true
-          severity: debug 3
-    parental_agents:
-      - name: parents
-        port: 53353
-        dscp: 42
-        addresses:
-          - address: 10.20.30.40
-            port: 53
-            key: certbot.
-          - address: 20.30.40.50
-            port: 53
-          - address: 30.40.50.60
-            key: certbot2.
-          - address: 40.50.60.70
-      - name: notparents
-        addresses:
-          - address: 10.20.30.40
-          - address: 30.40.50.60
-          - address: 40.50.60.70
-    primaries:
-      - name: parents
-        port: 53353
-        dscp: 42
-        addresses:
-          - address: 10.20.30.40
-            port: 53
-            key: certbot.
-          - address: 20.30.40.50
-            port: 53
-          - address: 30.40.50.60
-            key: certbot2.
-          - address: 40.50.60.70
-      - name: notparents
-        addresses:
-          - address: 10.20.30.40
-          - address: 30.40.50.60
-          - address: 40.50.60.70
-    tls:
-      - name: certbot
-        cert_file: /etc/ssl/private/snakeoil.pem
-        key_file: /etc/ssl/private/snakeoil.key
-        dhparam_file: /etc/ssl/dhparam.pem
-        ca_file: /etc/ssl/certs/ca-certificates.crt
-        remote_hostname: yourhostname
-        ciphers: HIGH:!aNULL:!MD5:!SHA1:!SHA256:!SHA384
-        protocols:
-          - TLSv1.2
-          - TLSv1.3
-        prefer_server_ciphers: true
-        session_tickets: true
-    trust_anchors:
-      - name: .
-        type: initial-key
-        flags: 257
-        protocol: 3
-        algorithm: 8
-        key: "AwEAAaz/tAm8yTn4Mfeh5eyI96WSVexTBAvkMgJzkKTOiW1vkIbzxeF3+/4RgWOq7HrxRixHlFlExOLAJr5emLvN7SWXgnLh4+B5xQlNVz8Og8kvArMtNROxVQuCaSnIDdD5LKyWbRd2n9WGe2R8PzgCmr3EgVLrjyBxWezF0jLHwVN8efS3rCj/EWgvIWgb9tarpVUDK/b58Da+sqqls3eNbuv7pr+eoZG+SrDK6nWeL3c6H5Apxz7LjVc1uTIdsIXxuOLYA4/ilBmSVIzuDWfdRUfhHdY6+cn8HFRm+2hM8AnXGXws9555KrUB5qihylGa8subX2Nn6UwNR1AkUTV74bU="
-      - name: hugs.dk
-        type: static-ds
-        flags: 64335
-        protocol: 7
-        algorithm: 2
-        key: "D6AAECB1BA13D51F072A229C957ACADEA18118FB17DA2DC7D45A963428091372"
-    server:
-      - prefix: 1.1.1.1
-        bogus: false
-        edns: true
-        tcp_only: false
-        tcp_keepalive: false
-        edns_version: '0'
-        padding: '0'
-        transfers: '0'
-        keyname: certbot.
-        query_source:
-          address: "*"
-          port: "*"
-    statistics_channels:
-      - address: 0.0.0.0
-        port: 8080
-        allow:
-          - 0/0
-  - name: named.conf.zones
-    backup: false
-    zones:
-      - name: "_acme-challenge.hugs.dk"
-        type: master
-        file: master/_acme-challenge.hugs.dk.zone
-        allow_query:
-          - any
-        dnssec_policy: default
-        inline_signing: true
-        serial_update_method: date
-        update_policy:
-          - permission: grant
-            identity: certbot.
-            ruletype: name
-            name: _acme-challenge.hugs.dk
-            types: txt
-      - name: forward.net
-        type: forward
-        forwarders:
-          port: 53
-          addresses:
-            - address: 1.1.1.1
-              port: 53
-              dscp: 42
-            - address: 4.2.2.4
-              port: 53
-      - name: stub.com
-        type: static-stub
-        allow_query:
-          - any
-        server_addresses:
-          - 1.1.1.1
-          - 8.8.8.8
-        zone_statistics: full
-      - name: example.com
-        type: slave
-        allow_query:
-          - 127.0.0.1
-          - 10.0.0.1
-          - 128.15.14.13
-        allow_query_on:
-          - 127.0.0.1
-        primaries:
-          port: 5522
-          dscp: 42
-          addresses:
-            - address: 127.0.0.1
-              port: 55222
-            - address: 10.20.30.40
-      - name: smorg.bop
-        type: slave
-        primaries:
-          addresses:
-            - address: 127.0.0.1
-        allow_query:
-          - 15.14.13.12
-          - 10.20.30.40
-          - 28.25.23.24
-          - "!10.13.14.15"
-        forwarders:
-          port: 53
-          dscp: 42
-          addresses:
-            - address: 127.0.0.1
-              port: 53
-              dscp: 42
-            - address: 10.20.30.40
-              port: 53
-            - address: 20.30.40.50
-            - address: 30.40.50.60
-              port: 53
-        allow_transfer:
-          port: 5522
-          transport: tls
-          addresses:
-            - 192.168.122.1
-        also_notify:
-          port: 5523
-          dscp: 42
-          addresses:
-            - address: 127.0.0.1
-              port: 5523
-            - address: 127.0.0.2
-        auto-dnssec: allow
-        dnskey_sig_validity: 0
-        dnssec-dnskey-kskonly: true
-        dnssec_loadkeys_interval: 0
-        file: "string"
-        forward: first
-        inline_signing: true
-        ixfr_from_differences: true
-        masterfile_format: raw
-        masterfile_style: full
-        max_ixfr_ratio: unlimited
-        max_journal_size: default
-        max_records: 0
-        max_transfer_idle_out: 0
-        max_transfer_time_out: 0
-        notify: true
-        notify_delay: '0'
-        notify_to_soa: false
-        parental_agents:
-          port: 44332
-          dscp: 42
-          addresses:
-            - address: 127.0.0.1
-              port: 53
-        sig_signing_nodes: '0'
-        sig_signing_signatures: '0'
-        sig_signing_type: 65281
-        zero_no_soa_ttl: true
-        zone_statistics: full
-```
+Daniel Akulenok <dak@keepit.com>
+Keepit A/S - keepit.com