From 5ddcbbec5c6a78cb096ee81b7d12cc83aeaf7102 Mon Sep 17 00:00:00 2001 From: Daniel Akulenok Date: Tue, 30 Aug 2022 08:02:31 +0000 Subject: [PATCH 1/4] Add variables documentation --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index 5bca6d6..eaec30e 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,18 @@ Or, as I call them "happy accidents". 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 From af3a9c7f33f5684db41d5773a0f982825f49dc94 Mon Sep 17 00:00:00 2001 From: Daniel Akulenok Date: Tue, 30 Aug 2022 08:03:51 +0000 Subject: [PATCH 2/4] Documentation --- README.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 95 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index eaec30e..2986dec 100644 --- a/README.md +++ b/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: + #