Merge branch 'documentation' into 'main'

Documentation

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

README.md

@@ -20,6 +20,83 @@ 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.
 
+Configuration Grammar
+---------------------
+The bind9 role tries to replicate the official ISC bind9 configuration format as close as possible,
+only re-implementing them in YAML format. This means that for the most part,
+section names are the same as in named.conf but kebab-case ('var-name') is replaced with snake_case ('var_name')
+If you are missing some statements in your resulting config, it is most likely because of this.
+
+The main configuration variable used are a series of bind_*_config variables (See [Role Variables]) that have the following syntax
+
+Every config starts by defining the file name. Each file can contain any amount of top-level statements,
+as permitted by named.conf 
+
+```
+bind9_host_config:
+  - name: FILENAME # The filename of your desired config file.
+                   # You also need to specify a corresponding `include:` for the file
+    SECTION_NAME: # The section name of the bind config you want to define.
+                  # Can be 'acl', 'options', 'zone', etc.
+                  # See: https://bind9.readthedocs.io/en/v9_18_4/reference.html#configuration-file-grammar
+    SECTION_2_NAME: # Every file can have as many sections as needed. Generally, try to keep 
+                    # all definitions and references together in a file.
+```
+
+Any option that can be defined multiple times in a named.conf, must be defined as a list
+```
+bind9_host_config:
+  - name: named.conf.local
+    acl:
+      - name: ELEMENT_NAME
+        addresses: 
+          - 127.0.0.1
+          - 127.0.0.2
+      - name: ELEMENT_2_NAME
+        addresses:
+          - 127.0.0.3
+```
+
+Simple options are defined just as that.
+```
+      SIMPLE_OPTION: string, boolean or integer value
+```
+
+Some options have several optional parameters. For those, a somewhat flexible 
+configuration format has been created
+```
+      IP_PORT_DSCP_OPTION: # Any option that is defined as one of:
+      #  <option> [ port <port> ] [ dscp <dscp> ] { <address> [ port <port> ] [ dscp <dscp> ]; ... }
+      #  <option> [ port <port> ] [ dscp <dscp> ] { <address> [ port <port> ] [ key <key> ] [ tls <tls> ]; ... }
+      # has a few optional syntaxes 
+      # Example 1: Simple address list
+        - ADDRESS1
+        - ADDRESS2
+      # Example 2: To define source port/dscp, use 'addresses' sub-element
+        [ port: PORT ]
+        [ dscp: DSCP ]
+        addresses:
+          - ADDRESS1
+          - ADDRESS2
+          - 127.0.0.1
+      # Example 3: To define target port/dscp, use 'addresses' as a list of dicts
+        addresses:
+          - address: ADDRESS
+            [ port: PORT ]
+            [ dscp: DSCP ]
+          - address: 127.0.0.1
+            port: 53
+          - address: 127.0.0.1
+            dscp: 42
+          - address: 127.0.0.1
+            port: 5353
+            dscp: 42
+      # Example 4: The various formats can be mixed and matched within the main element
+        - ADDRESS1
+        - address: ADDRESS2
+          port: PORT
+```
+
 Role Variables
 --------------
 
@@ -85,16 +162,31 @@ The `named.conf.options` block in `bind9_default_config` got completely overwrit
 Dependencies
 ------------
 
-A list of other roles hosted on Galaxy should go here, plus any details in regards to parameters that may need to be set for other roles, or variables that are used from other roles.
+No dependencies
 
 Example Playbook
 ----------------
 
-Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
+Simple sample config of a recursive BIND server that allows your localnetwork to resolve addresses via 
 
     - hosts: servers
       roles:
-         - { role: username.rolename, x: 42 }
+         - bind9
+      vars:
+        bind9_host_config:
+          - name: named.conf.local
+            acl:
+              - name: mylan
+                addresses:
+                  - 10.0.0.0/8
+          - name: named.conf.options
+            options:
+              forwarders:
+                - 1.1.1.1
+              allow-query:
+                - mylan
+              allow-recursion:
+                - mylan
 
 License
 -------