From 51bb7979db2f781c65ee913ebec962b548aaf30f Mon Sep 17 00:00:00 2001
From: Daniel Akulenok <dak@keepit.com>
Date: Tue, 23 Aug 2022 12:10:39 +0200
Subject: [PATCH] expand readme

---
 README.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 68 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 5bca6d6..0b4787a 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,56 @@ 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
+
+```
+bind9_host_config:
+  - name: FILENAME # The filename of your desired config file. Will overwrite and manage by BIND if used
+    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
+
+      OPTION: # Any option that is valid within the section
+        - name: # Any option that can be repeated and has a name, will need to have a unique "name" var
+          addresses: # Any list of addresses, will need to include a list of addresses like so.
+                     # Even if they only contain one element
+            - 127.0.0.1
+            - 127.0.0.2
+      SIMPLE_OPTION: string, boolean or integer value
+
+      IP_PORT_DSCP_OPTION: # Any option that is defined as:
+      #  <option> [ port <port> ] [ dscp <dscp> ] { <address> [ port <port> ] [ dscp <dscp> ]; ... }
+      # 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
+      # Example 3: To define target port/dscp, use 'addresses' as a list of dicts
+        addresses:
+          - address: ADDRESS
+            [ port: PORT ]
+            [ dscp: DSCP ]
+      # Example 4: The various formats can be mixed and matched within the main element
+        - ADDRESS1
+        - address: ADDRESS2
+          port: PORT
+            
+    acl: # Sections that can contain multiple elements, or specified multiple times, are always defined as a list
+         # Even when they contain only a single item.
+      - name: my_acl_name # If the variable 
+```
+
 Role Variables
 --------------
 
@@ -73,16 +123,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
 -------