Add warnings and safety checks and documentation

The changes in the `redhat-default-zones` branch, when released, may cause
upgrade difficulties for Red Hat system administrators. Try to ease the
transition.

DEFAULT_ZONES.md

@@ -0,0 +1,98 @@
+Default zones in BIND
+=====================
+
+<a name="default-zones"></a>
+## 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
+
+<a name="warning"></a>
+### 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.
+
+<a name="configuration-changes"></a>
+## 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`.

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

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

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'

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')

manifests/init.pp

@@ -8,6 +8,7 @@ class bind (
     $statistics_port       = undef,
     $auth_nxdomain         = false,
     $include_local         = false,
+    $include_default_zones = true,
 ) inherits bind::defaults {
 
     File {

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'")
     }