Puppet module for managing the BIND DNS server and DNS zones
AGPL-3.0 License
This module manages the BIND DNS server and associated DNS zones.
resolvconf_service_enable
is true
. This causes the localhost's BIND to be used in/etc/resolv.conf
.See metadata.json
for supported operating systems, supported Puppet versions,
and Puppet module dependencies.
For a default configuration that provides recursive, caching name resolution service:
include bind
On Debian, install the bind9
package from the backports repository (ensures that the
$facts['os']['distro']['codename']-backports
apt source is configured using the
puppetlabs-apt
module, but will fail if a
backported package does not exist for your particular
$facts['os']['distro']['codename']-backports
repo; check on the Debian package
tracker):
class { 'bind':
package_backport => true,
}
See the reference for available class parameters and defaults. For
platform-specific defaults, see the data
directory, which is organized according to
hiera.yaml
.
The test suite in the spec
directory is a good source for usage examples.
To manage the resource records of a zone with this module, the zone must be dynamically updatable
by the host being managed, via either the allow-update
or update-policy
configuration
options.
Using a minimal configuration with BIND defaults:
include bind
TODO: provide more examples.
Note that support for authoritative servers is incomplete in this module.
When creating a new zone with BIND, the zone file must have a $TTL
, a SOA record, an NS record,
and an address record for that host used in the NS record. All of these have defaults (see the
zone_default_*
parameters of init.pp
and the initial zone
template) so you don't have to specify them. The default initial zone
creates A
and AAAA
records based on the host's facts. Those default NS records are only used
if no NS records are provided for the zone's origin. You should specify your own SOA and NS
records unless you happen to want those defaults. Note that if you want to provide your own NS
records at the zone origin, you also have to provide your own SOA record.
class { 'bind':
authoritative => true,
# TODO: add settings to disable recursive query support
}
TODO: provide more examples.
class { 'bind':
authoritative => true,
}
TODO: provide more examples.
resource_record
typeDNS resource records can be created with the resource_record
Puppet type.
Equivalent examples:
resource_record { 'www.example.com. AAAA':
data => '2001:db8::1',
}
resource_record { 'my record':
zone => 'example.com.',
record => 'www',
type => 'AAAA',
data => '2001:db8::1',
}
The title of resource_record
resources can be in one of the following formats:
www.example.com. AAAA
(AAAA record www
in the example.com.
zone)www.example.com.
(record www
in the example.com.
zone with type specified as a parameter)www AAAA
(AAAA record www
in a zone specified as a parameter)www
(record www
with zone and type specified as parameters)bind::key
defined typeTSIG keys for dynamic zone updates used by clients can be added to the configuration as follows.
bind::key { 'key_name':
algorithm => 'hmac-sha512',
secret => 'ZlfCDgP7d3g7LjV4YMLg62EbpLZRCt9BMh3MyqiZfPX5Y2IcTyx/la6PMsfAqLMM9QDadZiNiLVzD4IPoI/4hg==',
}
The key's secret needs to be generated using the BIND tool tsig-keygen
; example:
tsig-keygen -a $algorithm [$key_name]
See metadata.json
for supported operating systems, supported Puppet versions,
and Puppet module dependencies.
Downgrading the package by setting package_backport => false
(after it had been true
) is not
supported by this module, but you can of course do such a downgrade manually outside of Puppet.
Changing the value provided for a zone's $TTL
directive after initial zone creation is not
supported by this module (because the zone file is only created initially from a template and
then never replaced, only updated dynamically using the RFC
2136 method), but you can do this manually outside of
Puppet.
The development of this module attempts to be
test-driven as much as possible.
Therefore, changes should generally be accompanied by tests. The test suite is located in the
spec
directory. Acceptance tests (in the acceptance
directory) use
Serverspec, while unit tests (everything else) use
rspec-puppet.
PDK and
Docker must be installed and working.
GNU Parallel is used to run acceptance tests in
parallel by default. This can be disabled with the --no-parallel
option.
./run_tests
pdk bundle exec rake strings:generate:reference
See also:
git checkout main
metadata.json
to the to-be-released version.pdk bundle exec rake changelog
git commit --all
git tag -a <version>
pdk build
git push
(I have git config --global push.followTags true
so that the tag will also bepublish.yaml
GitHub workflow to build and publish a release to thegh release create <version> pkg/kenyon-bind-<version>.tar.gz
(using GitHub CLI)Other BIND modules on Puppet Forge
The following files came from the Debian package and are licensed under the MPL-2.0.
Copyright 2021 Kenyon Ralph
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.