.. _readme:

bind-formula

|img_travis| |img_sr|

.. |img_travis| image:: https://travis-ci.com/saltstack-formulas/bind-formula.svg?branch=master :alt: Travis CI Build Status :scale: 100% :target: https://travis-ci.com/saltstack-formulas/bind-formula .. |img_sr| image:: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg :alt: Semantic Release :scale: 100% :target: https://github.com/semantic-release/semantic-release

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.

.. contents:: Table of Contents

General notes

See the full SaltStack Formulas installation and usage instructions <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html>_.

If you are interested in writing or contributing to formulas, please pay attention to the Writing Formula Section <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#writing-formulas>_.

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 <http://semver.org/>_.

See Formula Versioning Section <https://docs.saltstack.com/en/latest/topics/development/conventions/formulas.html#versioning>_ for more details.

Contributing to this repo

Commit message formatting is significant!!

Please see How to contribute <https://github.com/saltstack-formulas/.github/blob/master/CONTRIBUTING.rst>_ for more details.

Available states

.. contents:: :local:

bind ^^^^^^^^

Install the bind package and start the bind service.

bind.config ^^^^^^^^^^^^^^^

Manage the bind configuration file.

Example Pillar

.. code:: yaml

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.

Management of zone files

named.conf.local ^^^^^^^^^^^^^^^^^^

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

zone files ^^^^^^^^^^

The config.sls state will iterate on bind:available_zones and manage files for each that has bind:available_zones::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.

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.

External zone files ^^^^^^^^^^^^^^^^^^^

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

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 :

.. code:: yaml

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 :

.. code:: yaml

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

Notes

• When using views all zones must be configured in views!

Salt Compatibility

Tested with:

• 2017.7.x
• 2018.3.x

OS Compatibility

Tested with:

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

Testing

Linux testing is done with kitchen-salt.

kitchen converge ^^^^^^^^^^^^^^^^^^^^

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

kitchen verify ^^^^^^^^^^^^^^^^^^

Runs the inspec tests on the actual instance.

kitchen destroy ^^^^^^^^^^^^^^^^^^^

Removes the docker instance.

kitchen test ^^^^^^^^^^^^^^^^

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

kitchen login ^^^^^^^^^^^^^^^^^

Gives you SSH access to the instance for manual testing.