unkinben/puppet-bind
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reformat README and add troubleshooting

Browse Source
This commit is contained in:
Nate Riffe 2016-01-18 20:41:12 -06:00
parent 0388e91dc6
commit ec67ec92b5
1 changed files with 299 additions and 285 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

584
README.md
View File

@ -1,376 +1,390 @@
bind # bind
====
[![Build Status](https://secure.travis-ci.org/inkblot/puppet-bind.png)](http://travis-ci.org/inkblot/puppet-bind) [![Build Status](https://secure.travis-ci.org/inkblot/puppet-bind.png)](http://travis-ci.org/inkblot/puppet-bind)
## Description ## Summary
Control BIND name servers and zones Control BIND name servers and zones
Overview ## Description
--------
The BIND module provides an interface for managing a BIND name server, The BIND module provides an interface for managing a BIND name server, including installation of software, configuration
including installation of software, configuration of the server, creation of of the server, creation of keys, and definitions for zones.
keys, and definitions for zones.
Module Description ## What BIND affects
------------------
BIND automates configuration and operation of a BIND DNS server.
Setup
-----
**What BIND affects:**
* package installation and service control for BIND * package installation and service control for BIND
* configuration of the server, zones, acls, keys, and views * configuration of the server, zones, acls, keys, and views
* creation of TSIG and DNSSEC keys * creation of TSIG and DNSSEC keys
Dependencies # Usage
------------
The BIND module depends on ## Dependencies
[ripienaar/module_data]](https://forge.puppetlabs.com/ripienaar/module_data)
for hiera module data support and
[puppetlabs/stdlib](https://forge.puppetlabs.com/puppetlabs/stdlib) for certain
parser functions. When using the BIND module, please install the module using
`puppet module install` or an equivalent substitute in order to ensure that its
dependencies are met.
###Getting started The BIND module depends on [ripienaar/module_data]](https://forge.puppetlabs.com/ripienaar/module_data) for hiera module
data support and [puppetlabs/stdlib](https://forge.puppetlabs.com/puppetlabs/stdlib) for certain parser functions. When
using the BIND module, please install the module using `puppet module install` or an equivalent substitute in order to
ensure that its dependencies are met.
## Getting started
To begin using the BIND module with default parameters, declare the class To begin using the BIND module with default parameters, declare the class
class { 'bind': } ```
class { 'bind': }
```
Puppet code that uses anything from the BIND module requires that the core bind Puppet code that uses anything from the BIND module requires that the core bind classes be declared.
classes be declared.
###bind ## Classes
`bind` provides a few parameters that control server-level configuration ### `bind`
parameters in the `named.conf` file, and also defines the overall structure of
DNS service on the node.
class { 'bind': `bind` provides a few parameters that control server-level configuration parameters in the `named.conf` file, and also
forwarders => [ defines the overall structure of DNS service on the node.
'8.8.8.8',
'8.8.4.4',
],
dnssec => true,
version => 'Controlled by Puppet',
}
Puppet will manage the entire `named.conf` file and its includes. Most ```
parameters are set to a fixed value, but the server's upstream resolvers are class { 'bind':
controlled using `forwarders`, enabling of DNSSec signature validation is forwarders => [
controlled using `dnssec`, and the reported version is controlled using '8.8.8.8',
`version`. It is unlikely that you will need to define an alternate value for '8.8.4.4',
`confdir` or `cachedir`. ],
dnssec => true,
version => 'Controlled by Puppet',
}
```
###bind::updater Puppet will manage the entire `named.conf` file and its includes. Most parameters are set to a fixed value, but the
server's upstream resolvers are controlled using `forwarders`, enabling of DNSSec signature validation is controlled
using `dnssec`, and the reported version is controlled using `version`. It is unlikely that you will need to define an
alternate value for `confdir` or `cachedir`.
The `bind::updater` class is an alternate entrypoint into the module. This ### `bind::updater`
class installs the BIND client tools but not a name server. The installed tools
are sufficient to allow the use of the `resource_record` custom resource.
###bind::key The `bind::updater` class is an alternate entrypoint into the module. This class installs the BIND client tools but not
a name server. The installed tools are sufficient to allow the use of the `resource_record` custom resource.
Creates a TSIG key file. Only the `secret` parameter is required, but it is ## Defines
recommended to explicitly supply the `algorithm` as well. The key file will be
stored in `${::bind::confdir}/keys` with a filename derived from the title of ### `bind::key`
Creates a TSIG key file. Only the `secret` parameter is required, but it is recommended to explicitly supply the
`algorithm` as well. The key file will be stored in `${::bind::confdir}/keys` with a filename derived from the title of
the `bind::key` declaration. the `bind::key` declaration.
bind::key { 'local-update': ```
algorithm => 'hmac-sha256', # default: 'hmac-sha256' bind::key { 'local-update':
secret => '012345678901345678901234567890123456789=', algorithm => 'hmac-sha256', # default: 'hmac-sha256'
owner => 'root', secret => '012345678901345678901234567890123456789=',
group => 'bind', owner => 'root',
} group => 'bind',
}
```
If no secret is specified, the bind::key define will generate one. The If no secret is specified, the bind::key define will generate one. The secret_bits parameter controls the size of the
secret_bits parameter controls the size of the secret. secret.
bind::key { 'local-update': ```
secret_bits => 512, # default: 256 bind::key { 'local-update':
} secret_bits => 512, # default: 256
}
```
###bind::acl ### `bind::acl`
Declares an acl in the server's configuration. The acl's name is the title of Declares an acl in the server's configuration. The acl's name is the title of the `bind::acl` declaration.
the `bind::acl` declaration.
bind::acl { 'rfc1918': ```
addresses => [ bind::acl { 'rfc1918':
'10.0.0.0/8', addresses => [
'172.16.0.0/12', '10.0.0.0/8',
'192.168.0.0/16', '172.16.0.0/12',
] '192.168.0.0/16',
} ]
}
bind::acl { 'secondary-dns': bind::acl { 'secondary-dns':
addresses => '192.0.2.4/32', addresses => '192.0.2.4/32',
} }
```
###bind::zone ### `bind::zone`
Declares a zone. Each zone must be included in at least one view in order to be Declares a zone. Each zone must be included in at least one view in order to be included in the server's configuration,
included in the server's configuration, and may be included in multiple views. and may be included in multiple views. The corresponding zone file will be created if it is absent, but any existing
The corresponding zone file will be created if it is absent, but any existing file will not be overwritten. Only the `zone_type` is required. If `domain` is unspecified, the title of the
file will not be overwritten. Only the `zone_type` is required. If `domain` is `bind::zone` declaration will be used as the domain.
unspecified, the title of the `bind::zone` declaration will be used as the
domain.
A master zone with a zone file managed directly by Puppet: A master zone with a zone file managed directly by Puppet:
bind::zone { 'example.org': ```
zone_type => 'master', bind::zone { 'example.org':
dynamic => false, zone_type => 'master',
source => 'puppet:///dns/db.example.org', dynamic => false,
allow_transfers => [ 'secondary-dns', ], source => 'puppet:///dns/db.example.org',
} allow_transfers => [ 'secondary-dns', ],
}
```
A master zone with DNSSec disabled which allows updates using a TSIG key and A master zone with DNSSec disabled which allows updates using a TSIG key and zone transfers to servers matching an acl:
zone transfers to servers matching an acl:
bind::zone { 'example.com-internal': ```
zone_type => 'master', bind::zone { 'example.com-internal':
domain => 'example.com', zone_type => 'master',
allow_updates => [ 'key local-update', ], domain => 'example.com',
allow_transfers => [ 'secondary-dns', ], allow_updates => [ 'key local-update', ],
ns_notify => true, allow_transfers => [ 'secondary-dns', ],
dnssec => false, ns_notify => true,
} dnssec => false,
}
```
A master zone with DNSSec enabled which allows updates using a TSIG key and A master zone with DNSSec enabled which allows updates using a TSIG key and zone transfers to servers matching an acl:
zone transfers to servers matching an acl:
bind::zone { 'example.com-external': ```
zone_type => 'master', bind::zone { 'example.com-external':
domain => 'example.com', zone_type => 'master',
allow_updates => [ 'key local-update', ], domain => 'example.com',
allow_transfers => [ 'secondary-dns', ], allow_updates => [ 'key local-update', ],
ns_notify => true, allow_transfers => [ 'secondary-dns', ],
dnssec => true, ns_notify => true,
key_directory => '/var/cache/bind/example.com', dnssec => true,
} key_directory => '/var/cache/bind/example.com',
}
```
A master zone which is initialized with a pre-existing zone file (for example, A master zone which is initialized with a pre-existing zone file (for example, to migrate an existing zone to a
to migrate an existing zone to a bind-module controlled server or to recover bind-module controlled server or to recover from a backup):
from a backup):
bind::zone { 'example.com': ```
zone_type => 'master', bind::zone { 'example.com':
source => 'puppet:///backups/dns/example.com', zone_type => 'master',
} source => 'puppet:///backups/dns/example.com',
}
```
A slave zone which allows notifications from servers matched by IP: A slave zone which allows notifications from servers matched by IP:
bind::zone { 'example.net': ```
zone_type => 'slave', bind::zone { 'example.net':
masters => [ '198.0.2.2' ], zone_type => 'slave',
allow_notify => [ '192.0.2.2' ], masters => [ '198.0.2.2' ],
ns_notify => false, allow_notify => [ '192.0.2.2' ],
} ns_notify => false,
}
```
A forward zone: A forward zone:
bind::zone { 'example.org': ```
zone_type => 'forward', bind::zone { 'example.org':
forwarders => [ '10.0.2.4', ], zone_type => 'forward',
forward => 'only', forwarders => [ '10.0.2.4', ],
} forward => 'only',
}
```
###bind::view ### `bind::view`
Declares a view in the BIND configuration. In order to declare zones in a Declares a view in the BIND configuration. In order to declare zones in a server configuration there must be at least
server configuration there must be at least one view declaration which includes one view declaration which includes the zones.
the zones.
A common use for views is to use a single dual-homed nameserver as a resolver A common use for views is to use a single dual-homed nameserver as a resolver on a private network and an authoritative
on a private network and an authoritative non-resolving nameserver on the non-resolving nameserver on the Internet. Furthermore, the Internet-facing and private network-facing views may present
Internet. Furthermore, the Internet-facing and private network-facing views may different authoritative results for a domain. Given a BIND server connected to the internet with the address 198.0.2.2
present different authoritative results for a domain. Given a BIND server and connected to a private network with the address 10.0.2.2, here are the `bind::view` declarations that would create
connected to the internet with the address 198.0.2.2 and connected to a private this configuration:
network with the address 10.0.2.2, here are the `bind::view` declarations that
would create this configuration:
bind::view { 'internet': ```
recursion => false, bind::view { 'internet':
match_destinations => [ '198.0.2.2', ], recursion => false,
zones => [ 'example.net', 'example.com-external', ], match_destinations => [ '198.0.2.2', ],
} zones => [ 'example.net', 'example.com-external', ],
}
bind::view { 'private': bind::view { 'private':
recursion => true, recursion => true,
match_destinations => [ '10.0.2.2', ], match_destinations => [ '10.0.2.2', ],
zones => [ 'example.net', 'example.com-internal', ], zones => [ 'example.net', 'example.com-internal', ],
} }
```
In this scenario, the example.com domain has two separate zones that are In this scenario, the example.com domain has two separate zones that are presented in each of the `internet` and
presented in each of the `internet` and `private` views. These two zones are `private` views. These two zones are independent, and TSIG-signed updates to example.com must be made to either
independent, and TSIG-signed updates to example.com must be made to either 198.0.2.2 or 10.0.2.2, to change the `internet` or `private` views of this domain. Updates to `example.net` may be made
198.0.2.2 or 10.0.2.2, to change the `internet` or `private` views of this via either address, since the zone is included in both views.
domain. Updates to `example.net` may be made via either address, since the zone
is included in both views.
Another use for views is to control access to the DNS server's services. In Another use for views is to control access to the DNS server's services. In this example, service is restricted to a
this example, service is restricted to a specific set of client address ranges, specific set of client address ranges, and queries for the `example.org` domain are handled using a declared zone (see
and queries for the `example.org` domain are handled using a declared zone (see
`bind::zone` declaration for `example.org` above): `bind::zone` declaration for `example.org` above):
bind::view { 'clients': ```
recursion => true, bind::view { 'clients':
match_clients => [ recursion => true,
'10.10.0.0/24', match_clients => [
'10.100.0.0/24', '10.10.0.0/24',
], '10.100.0.0/24',
zones => [ ],
'example.org', zones => [
], 'example.org',
} ],
}
```
View declarations can also include server clause configuration. The `servers` View declarations can also include server clause configuration. The `servers` property of `bind::view` accepts an array
property of `bind::view` accepts an array value which specifies each `server` value which specifies each `server` clause in the view as a hash. The hash must contain an `ip_addr` key which specifies
clause in the view as a hash. The hash must contain an `ip_addr` key which the IP address (optionally, a CIDR address range), and may contain a `keys` key with a string value. The value of `keys`
specifies the IP address (optionally, a CIDR address range), and may contain a will be used as the name of a key in the `server` clause. In this example, the `ns` view will contain a `server` clause
`keys` key with a string value. The value of `keys` will be used as the name of that configures BIND to use the key `internal-ns` to TSIG-sign transactions with `192.168.24.2` and the key
a key in the `server` clause. In this example, the `ns` view will contain a `hurricane-electric` to TSIG-sign transactions with `216.218.130.2`:
`server` clause that configures BIND to use the key `internal-ns` to TSIG-sign
transactions with `192.168.24.2` and the key `hurricane-electric` to TSIG-sign
transactions with `216.218.130.2`:
bind::view { 'ns': ```
servers => [ bind::view { 'ns':
{ servers => [
'ip_addr' => '192.168.24.2', {
'keys' => 'internal-ns', 'ip_addr' => '192.168.24.2',
}, 'keys' => 'internal-ns',
{ },
'ip_addr' => '216.218.130.2', {
'keys' => 'hurricane-electric', 'ip_addr' => '216.218.130.2',
} 'keys' => 'hurricane-electric',
], }
... ],
} ...
}
```
###resource_record ## Resources
### `resource_record`
Declares a resource record. For exampmle: Declares a resource record. For exampmle:
resource_record { 'www.example.com address': ```
ensure => present, resource_record { 'www.example.com address':
record => 'www.example.com', ensure => present,
type => 'A', record => 'www.example.com',
data => [ '172.16.32.10', '172.16.32.11' ], type => 'A',
ttl => 86400, data => [ '172.16.32.10', '172.16.32.11' ],
zone => 'example.com', ttl => 86400,
server => 'ns.example.com', zone => 'example.com',
keyname => 'local', server => 'ns.example.com',
hmac => 'hmac-sha1', keyname => 'local',
secret => 'aLE5LA==' hmac => 'hmac-sha1',
} secret => 'aLE5LA=='
}
```
This resource declaration will result in address records with the addresses This resource declaration will result in address records with the addresses 172.16.32.10 and 172.16.32.11 (`data`), a
172.16.32.10 and 172.16.32.11 (`data`), a TTL of 86400 (`ttl`) in the zone TTL of 86400 (`ttl`) in the zone example.com (`zone`). Any updates necessary to create, update, or destroy these records
example.com (`zone`). Any updates necessary to create, update, or destroy these are authenticated using a TSIG key named 'local' (`keyname`) of the given type (`hmac`) with the given `secret`.
records are authenticated using a TSIG key named 'local' (`keyname`) of the
given type (`hmac`) with the given `secret`.
No semantic information is communicated in the resource title. It is strictly No semantic information is communicated in the resource title. It is strictly for disambiguation of resources within
for disambiguation of resources within Puppet. Puppet.
`record` is required, and is the fully qualified record to be managed. `record` is required, and is the fully qualified record to be managed.
`type` is required, and is the record type. It must be one of: `A` `AAAA` `type` is required, and is the record type. It must be one of: `A` `AAAA` `CNAME` `NS` `MX` `SPF` `SRV` `NAPTR` `PTR` or
`CNAME` `NS` `MX` `SPF` `SRV` `NAPTR` `PTR` or `TXT`. Other DNS record types `TXT`. Other DNS record types are not currently supported.
are not currently supported.
`rrclass` is the class of the record. The default value is `IN` and allowed `rrclass` is the class of the record. The default value is `IN` and allowed values are `IN`, `CH`, and `HS`.
values are `IN`, `CH`, and `HS`.
`data` is required, and may be a scalar value or an array of scalar values `data` is required, and may be a scalar value or an array of scalar values whose format conform to the type of DNS
whose format conform to the type of DNS resource record being created. `data` resource record being created. `data` is an ensurable property and changes will be reflected in DNS. **Note**: for
is an ensurable property and changes will be reflected in DNS. **Note**: for record types that have a DNS name as either the whole value or a component of the value (e.g. `NS`, 'MX', `CNAME`,
record types that have a DNS name as either the whole value or a component of `PTR`, `NAPTR`, or `SRV`) you must specify the name as a fully-qualified name with a trailing dot in order to satisfy
the value (e.g. `NS`, 'MX', `CNAME`, `PTR`, `NAPTR`, or `SRV`) you must specify both BIND, which will otherwise consider it a name relative, and Puppet, which will not consider the dot-qualified
the name as a fully-qualified name with a trailing dot in order to satisfy output of dig equal to a non-dot-qualified value in the manifest.
both BIND, which will otherwise consider it a name relative, and Puppet, which
will not consider the dot-qualified output of dig equal to a non-dot-qualified
value in the manifest.
`ttl` defaults to 43200 and need not be specified. `ttl` is an ensurable `ttl` defaults to 43200 and need not be specified. `ttl` is an ensurable property and changes will be reflected in DNS.
property and changes will be reflected in DNS.
`zone` is not required, and generally not needed. It is only necessary to `zone` is not required, and generally not needed. It is only necessary to specify the zone to be updated if the target
specify the zone to be updated if the target nameserver has the record in nameserver has the record in multiple zones, e.g. the NS records of a zone whose parent zone is served by the same
multiple zones, e.g. the NS records of a zone whose parent zone is served by nameserver.
the same nameserver.
`server` defaults to "localhost" and need not be specified. The value may be `server` defaults to "localhost" and need not be specified. The value may be either a hostname or IP address.
either a hostname or IP address.
`query_section` indicates the section of the DNS response to check for existing `query_section` indicates the section of the DNS response to check for existing record values. It must be one of
record values. It must be one of `answer`, `authority`, or `additional`. `answer`, `authority`, or `additional`. Defaults to: `answer`
Defaults to: `answer`
`keyname` defaults to "update" and need not be specified. This parameter `keyname` defaults to "update" and need not be specified. This parameter specifies the name of a TSIG key to be used to
specifies the name of a TSIG key to be used to authenticate the update. The authenticate the update. The resource only uses a TSIG key if a `secret` is specified.
resource only uses a TSIG key if a `secret` is specified.
`keyfile` specifies the name of a key file to use to sign requests. This `keyfile` specifies the name of a key file to use to sign requests. This parameter has no effect if a `secret` is
parameter has no effect if a `secret` is specified. specified.
`hmac` defaults to "hmac-sha1" and need not be specified. This parameter `hmac` defaults to "hmac-sha1" and need not be specified. This parameter specifies the algorithm of the TSIG key to be
specifies the algorithm of the TSIG key to be used to authenticate the update. used to authenticate the update. The resource only uses a TSIG key if a `secret` is specified.
The resource only uses a TSIG key if a `secret` is specified.
`secret` is optional. This parameter specifies the encoded cryptographic secret `secret` is optional. This parameter specifies the encoded cryptographic secret of the TSIG key to be used to
of the TSIG key to be used to authenticate the update. If no `secret` is authenticate the update. If no `secret` is specified, then the update will not use TSIG authentication.
specified, then the update will not use TSIG authentication.
####resource_record examples #### `resource_record` examples
Mail exchangers for a domain. Declares three mail exchangers for the domain Mail exchangers for a domain. Declares three mail exchangers for the domain `example.com`, which are `mx.example.com`,
`example.com`, which are `mx.example.com`, `mx2.example.com`, and `mx2.example.com`, and `mx.mail-host.ex` with priorities `10`, `20`, and `30`, respectively (note the trailing dots in
`mx.mail-host.ex` with priorities `10`, `20`, and `30`, respectively (note the the values to denote fully-qualified names):
trailing dots in the values to denote fully-qualified names):
resource_record { 'example.com mail exchangers': ```
record => 'example.com', resource_record { 'example.com mail exchangers':
type => 'MX', record => 'example.com',
data => [ '10 mx.example.com.', '20 mx2.example.com.', '20 mx.mail-host.ex.', ], type => 'MX',
} data => [ '10 mx.example.com.', '20 mx2.example.com.', '20 mx.mail-host.ex.', ],
}
```
Nameserver records for a zone. Declares three nameserver records for the zone Nameserver records for a zone. Declares three nameserver records for the zone `example.com`, which are
`example.com`, which are `ns1.example.com`, `ns2.example.com`, and `ns1.example.com`, `ns2.example.com`, and `ns.dns-host.ex`:
`ns.dns-host.ex`:
resource_record { 'example.com name servers': ```
record => 'example.com', resource_record { 'example.com name servers':
type => 'NS', record => 'example.com',
data => [ 'ns1.example.com.', 'ns2.example.com.', 'ns.dns-host.ex.' ], type => 'NS',
} data => [ 'ns1.example.com.', 'ns2.example.com.', 'ns.dns-host.ex.' ],
}
```
Delegating nameserver records in a parent zone. Declares a nameserver record in Delegating nameserver records in a parent zone. Declares a nameserver record in the parent zone in order to delegate
the parent zone in order to delegate authority for a subdomain: authority for a subdomain:
resource_record { 'sub.example.com delegation': ```
record => 'sub.example.com' resource_record { 'sub.example.com delegation':
type => 'NS', record => 'sub.example.com'
zone => 'example.com', type => 'NS',
query_section => 'authority', zone => 'example.com',
data => 'sub-ns.example.com.', query_section => 'authority',
} data => 'sub-ns.example.com.',
}
```
Service locators records for a domain. Declares a service locator for SIP over Service locators records for a domain. Declares a service locator for SIP over UDP to the domain `example.com`, in which
UDP to the domain `example.com`, in which the service located at port `5060` of the service located at port `5060` of `inbound.sip-host.ex` is given priority `5` and weight `100`.
`inbound.sip-host.ex` is given priority `5` and weight `100`.
resource_record { 'example.com SIP service locator': ```
record => '_sip._udp.example.com', resource_record { 'example.com SIP service locator':
type => 'SRV', record => '_sip._udp.example.com',
data => [ '5 100 5060 inbound.sip-host.ex.', ], type => 'SRV',
} data => [ '5 100 5060 inbound.sip-host.ex.', ],
}
```
## Troubleshooting
### Error message: "Please ensure that the dependencies of the bind module are installed and working correctly
This error usually has one of two causes.
First of all, the `bind` module has dependencies. These are declared in the module manifest, and they are properly
installed via the [`puppet module install`](https://docs.puppetlabs.com/puppet/latest/reference/modules_installing.html)
command and when using [`librarian-puppet`](https://github.com/rodjek/librarian-puppet).
Secondly, after installing the module and its dependencies it is necessary to restart the Puppet master if you are using
master mode. The [`ripienaar/module_data`](https://github.com/ripienaar/puppet-module-data) module contains
functionality which is only loaded at startup.
### Error message: "Platform is not supported"
Support for specific platforms is explicit in this module. If you see this message and would like to try to make the
module work on your platform, you can do this by setting `bind::defaults::supported` to `true` in hiera, and then
overriding other parameters of the `bind::defaults` class as necessary to make the module work. If you succeed or if you
require help, please open an issue. I would be happy to include your changes in order to support additional platforms.