bind-formula

A SaltStack formula that is empty. It has dummy content to help with a quick start on a new formula and it serves as a style guide.

1. General notes

See the full SaltStack Formulas installation and usage instructions.

If you are interested in writing or contributing to formulas, please pay attention to the Writing Formula Section.

If you want to use this formula, please pay attention to the FORMULA file and/or git tag, which contains the currently released version. This formula is versioned according to Semantic Versioning.

See Formula Versioning Section for more details.

2. Contributing to this repo

Commit message formatting is significant!!

Please see How to contribute for more details.

3. Available states

3.1. `bind`

Install the bind package and start the bind service.

3.2. `bind.config`

Manage the bind configuration file.

4. Example Pillar

bind:
  configured_zones:
    example.com:
      type: master
      notify: False
  available_zones:
    example.com:
      file: example.com.txt
      soa:
        ns: ns1.example.com                       # Required
        contact: hostmaster.example.com           # Required
        serial: 2017041001                        # Required
      records:                                    # Records for the zone, grouped by type
        A:
          mx1:                                    # A RR with multiple values can
            - 1.2.3.228                           # be written as an array
            - 1.2.3.229
          cat: 2.3.4.188
          rat: 1.2.3.231
          live: 1.2.3.236
  configured_views:
    myview1:
      match_clients:
        - client1
        - client2
    configured_zones:
      my.zone:
        type: master
        notify: False

See pillar.example for a more complete example.

5. Management of zone files

5.1. named.conf.local

<zone> entries in named.conf.local will point to the file declared in

bind:configured_zones:<zone>:file (this takes precedence)
bind:available_zones:<zone>:file

5.2. zone files

The config.sls state will iterate on bind:available_zones and manage <zone> files for each <zone> that has bind:available_zones:<zone>:file` declared.

If bind:available_zones:<zone>:records exist, a zone file will be created using those records (see pillar.example for more details)
If bind:available_zones:<zone>:records is NOT declared, bind:available_zones:<zone>:file should point to an existing zone file that will be sourced by the formula.

5.3. Using Views

Using views introduces some restrictions by the BIND server in that once you have views defined, ALL of your zones have to be served via a view. You cannot have any zones defined outside of a view.

If you want multiple views to serve the same zone but with different record sets, follow the example in pillar-with-views.example to set this up. The key to this is the 'file' argument in the view configuration that allows you to set the view’s configured_zone to a zone that you define underneath 'available_zones'. Without specifying this 'file' argument, your views cannot serve the same zone; they will instead serve a zone that matches the name of the view.

5.4. External zone files

To use an external tool to manage the <zone> file, simply declare the location of the zone file in bind:configured_zones:<zone>:file and don’t add any entry for the <zone> in bind:available_zones

6. DNSSEC

The bind formula currently support two ways to enable DNSSEC:

Using the zonesigner binary provided by dnssec-tools (legacy) ;
Using internal features of bind.

Here is sample pillar entries to use the latter.

On the master server :

bind:
  lookup:
    key_directory: '/etc/bind/keys'
  config:
    options:
      dnssec-enable: 'yes'
      dnssec-validation: 'yes'
  configured_acls:
    slave_server:
      - 192.168.1.2
  configured_zones:
    domain.tld:
      file: "db.domain.tld"
      type: master
      notify: True
      allow-transfer:
        - localnets
        - localhost
        - slave_server
      allow-update: 'none'
      auto-dnssec: 'maintain'

On the slave server :

bind:
  config:
    options:
      dnssec-enable: 'yes'
      dnssec-validation: 'yes'
  configured_zones:
    domain.tld:
      file: "db.domain.tld.signed"
      type: slave
      masters:
        - master_server
  configured_masters:
    master_server:
      - 192.168.1.1

7. Notes

When using views all zones must be configured in views!

8. Salt Compatibility

Tested with:

2017.7.x
2018.3.x

9. OS Compatibility

Tested with:

Archlinux
CentOS 7
Debian-8
Debian-9
Fedora-27
Ubuntu-16.04
Ubuntu-18.04

10. Testing

Linux testing is done with kitchen-salt.

10.1. `kitchen converge`

Creates the docker instance and runs the template main state, ready for testing.

10.2. `kitchen verify`

Runs the inspec tests on the actual instance.

10.3. `kitchen destroy`

Removes the docker instance.

10.4. `kitchen test`

Runs all of the stages above in one go: i.e. destroy + converge
verify + destroy.

10.5. `kitchen login`

Gives you SSH access to the instance for manual testing.