diff --git a/DEFAULT_ZONES.md b/DEFAULT_ZONES.md new file mode 100644 index 0000000..5559353 --- /dev/null +++ b/DEFAULT_ZONES.md @@ -0,0 +1,98 @@ +Default zones in BIND +===================== + + +## What are default zones? + +The package which installs the BIND server includes a stock configuration that +defines five default zones. One of these, the [root +hints](https://www.iana.org/domains/root/files), is necessary for the proper +functioning of a recursive resolver. The remaining four - `localhost`, +`0.in-addr.arpa`, `127.in-addr.arpa`, and `255.in-addr.arpa` - are defined for +compliance with [RFC 1912](https://www.ietf.org/rfc/rfc1912.txt). The content +of these zones is standardized, and the zone files for them are maintained by +the package distributor. + +## Change Is Coming + + +### The Warning + +Most likely, you have reached this page because you have seen the notice on the +[README file](README.md) or a warning like this in your puppet logs: + +``` +The bind module will include a default definition for zone "localhost" starting in version 6.0.0. +``` + +If you are seeing this warning, it is because starting in version 6.0.0 certain +`bind::zone` definitions in your puppet manifests will result in an error and +catalog application failures. There are [steps](#configuration-changes) to take +prior to version 6.0.0 to prepare for it. + +### The Present: Debian and Red Hat Divergence + +The treatment of default zones in this module has been different between Debian +and Red Hat systems until now. + +On Debian systems, the `bind9` package installs a separate configuration file +at `/etc/bind/named.conf.default-zones` which defines these zones and also +installs a stock `named.conf` which includes `named.conf.default-zones`. The +module retains the `named.conf.default-zones` configuration file and although +the module completely rewrites `named.conf`, it includes the default zones file +so that the default zones continues to be a part of the complete server +configuration. + +On Red Hat systems, the default zones are defined in the stock version of +`named.conf` that the package installs. Since the module completely +rewrites this file, these definitions are lost. + +In both cases, the current behavior is not configurable and always happens. + +### The Future: Consistency with Flexibility + +Starting in version 6.0.0 of this module, default zones will be preserved on +both Debian and Red Hat, with the option of disabling them. This will not +result in any change in the behavior of the module on Debian systems, but on +Red Hat systems existing puppet manifests which use this module to configure a +nameserver may require modification in order to work with the newer version of +the module. + + +## Configuration Changes + +If you are seeing [the warning](#warning) in your puppet logs, you must take +action before upgrading to version 6.0.0 of this module. You are seeing the +warning because your puppet manifests include `bind::zone` definitions for one +or more of the [default zones](#default-zones). No action is necessary unless +you are seeing the warning. + +### Before Upgrading + +The step that you must take prior to upgrading to version 6.0.0 of the module +is to disable default zone inclusion. Setting this parameter has no effect in +5.x versions of this module other than to mute the warning but disabling the +feature will allow you to safely upgrade to 6.0.0. You can specify this as a +class parameter in the manifest where you use the `bind` class: + +``` +class { 'bind': + ... + include_default_zones => false, +} +``` + +Or you can override the class parameter via a hiera key: + +``` +bind::include_default_zones: false +``` + +Once this is done, you may safely upgrade to version 6.0.0. + +### After Upgrading + +After the upgrade, you will have the option of letting the module define your +default zones. However, when you reenable default zone inclusion you must also +remove your custom `bind::zone` definitions for the root zone `.`, `localhost`, +`0.in-addr.arpa`, `127.in-addr.arpa`, and `255.in-addr.arpa`. diff --git a/README.md b/README.md index a87d1ec..82c4fe3 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,11 @@ [![Build Status](https://secure.travis-ci.org/inkblot/puppet-bind.png)](http://travis-ci.org/inkblot/puppet-bind) +**IMPORTANT UPGRADE INFORMATION:** In a future version of this module there +will be significant changes to the handling of default zones that may require +preparations prior to upgrading. See [DEFAULT_ZONES.md](DEFAULT_ZONES.md) for +details. + ## Summary Control BIND name servers and zones diff --git a/data/common.yaml b/data/common.yaml index 14f23a3..0984f00 100644 --- a/data/common.yaml +++ b/data/common.yaml @@ -2,6 +2,7 @@ bind::defaults::supported: false bind::defaults::random_device: '/dev/random' bind::defaults::rndc: true +bind::defaults::default_zones_warning: false bind::forwarders: '' bind::dnssec: true diff --git a/data/osfamily/RedHat.yaml b/data/osfamily/RedHat.yaml index 8c87863..e405356 100644 --- a/data/osfamily/RedHat.yaml +++ b/data/osfamily/RedHat.yaml @@ -9,5 +9,6 @@ bind::defaults::managed_keys_directory: '/var/named/dynamic' bind::defaults::confdir: '/etc/named' bind::defaults::namedconf: '/etc/named.conf' bind::defaults::cachedir: '/var/named' +bind::defaults::default_zones_warning: true bind::updater::keydir: '/etc/named/keys' diff --git a/manifests/defaults.pp b/manifests/defaults.pp index 8336c96..7b0b1a1 100644 --- a/manifests/defaults.pp +++ b/manifests/defaults.pp @@ -12,6 +12,7 @@ class bind::defaults ( $bind_service = undef, $nsupdate_package = undef, $managed_keys_directory = undef, + $default_zones_warning = undef, ) { unless is_bool($supported) { fail('Please ensure that the dependencies of the bind module are installed and working correctly') diff --git a/manifests/init.pp b/manifests/init.pp index 65c7c52..a8314e3 100644 --- a/manifests/init.pp +++ b/manifests/init.pp @@ -1,13 +1,14 @@ # ex: syntax=puppet si ts=4 sw=4 et class bind ( - $forwarders = '', - $dnssec = true, - $version = '', - $rndc = undef, - $statistics_port = undef, - $auth_nxdomain = false, - $include_local = false, + $forwarders = '', + $dnssec = true, + $version = '', + $rndc = undef, + $statistics_port = undef, + $auth_nxdomain = false, + $include_local = false, + $include_default_zones = true, ) inherits bind::defaults { File { diff --git a/manifests/zone.pp b/manifests/zone.pp index c76c082..8fbd62f 100644 --- a/manifests/zone.pp +++ b/manifests/zone.pp @@ -22,14 +22,20 @@ define bind::zone ( # where there is a zone, there is a server include bind - # Pull some platform defaults into the local scope + # Pull some platform defaults and `bind` class parameters into the local scope $cachedir = $::bind::defaults::cachedir $random_device = $::bind::defaults::random_device $bind_user = $::bind::defaults::bind_user $bind_group = $::bind::defaults::bind_group + $default_zones_warning = $::bind::defaults::default_zones_warning + $include_default_zones = $::bind::include_default_zones $_domain = pick($domain, $name) + if $include_default_zones and $default_zones_warning and member(['.', 'localhost', '127.in-addr.arpa', '0.in-addr.arpa', '255.in-addr.arpa'], $_domain) { + warning("The bind module will include a default definition for zone \"${_domain}\" starting in version 6.0.0. Please see https://github.com/inkblot/puppet-bind/blob/master/DEFAULT_ZONES.md for more information about how this will affect your configuration.") + } + unless !($masters != '' and ! member(['slave', 'stub'], $zone_type)) { fail("masters may only be provided for bind::zone resources with zone_type 'slave' or 'stub'") }