378 lines
13 KiB
Markdown
378 lines
13 KiB
Markdown
bind
|
|
====
|
|
|
|
[](http://travis-ci.org/inkblot/puppet-bind)
|
|
|
|
## Description
|
|
Control BIND name servers and zones
|
|
=======
|
|
Overview
|
|
--------
|
|
|
|
The BIND module provides an interface for managing a BIND name server,
|
|
including installation of software, configuration of the server, creation of
|
|
keys, and definitions for zones.
|
|
|
|
Module Description
|
|
------------------
|
|
|
|
BIND automates configuration and operation of a BIND DNS server.
|
|
|
|
Setup
|
|
-----
|
|
|
|
**What BIND affects:**
|
|
|
|
* package installation and service control for BIND
|
|
* configuration of the server, zones, acls, keys, and views
|
|
* creation of TSIG and DNSSEC keys
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
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
|
|
|
|
class { 'bind': }
|
|
|
|
Puppet code that uses anything from the BIND module requires that the core bind
|
|
classes be declared.
|
|
|
|
###bind
|
|
|
|
`bind` provides a few parameters that control server-level configuration
|
|
parameters in the `named.conf` file, and also defines the overall structure of
|
|
DNS service on the node.
|
|
|
|
class { 'bind':
|
|
confdir => '/etc/bind',
|
|
cachedir => '/var/lib/bind',
|
|
forwarders => [
|
|
'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
|
|
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`.
|
|
|
|
###bind::updater
|
|
|
|
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.
|
|
|
|
###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.
|
|
|
|
bind::key { 'local-update':
|
|
algorithm => 'hmac-sha256', # default: 'hmac-sha256'
|
|
secret => '012345678901345678901234567890123456789=',
|
|
owner => 'root',
|
|
group => 'bind',
|
|
}
|
|
|
|
If no secret is specified, the bind::key define will generate one. The
|
|
secret_bits parameter controls the size of the secret.
|
|
|
|
bind::key { 'local-update':
|
|
secret_bits => 512, # default: 256
|
|
}
|
|
|
|
###bind::acl
|
|
|
|
Declares an acl in the server's configuration. The acl's name is the title of
|
|
the `bind::acl` declaration.
|
|
|
|
bind::acl { 'rfc1918':
|
|
addresses => [
|
|
'10.0.0.0/8',
|
|
'172.16.0.0/12',
|
|
'192.168.0.0/16',
|
|
]
|
|
}
|
|
|
|
bind::acl { 'secondary-dns':
|
|
addresses => '192.0.2.4/32',
|
|
}
|
|
|
|
###bind::zone
|
|
|
|
Declares a zone. Each zone must be included in at least one view in order to be
|
|
included in the server's configuration, and may be included in multiple views.
|
|
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 `bind::zone` declaration will be used as the
|
|
domain.
|
|
|
|
A master zone with a zone file managed directly by Puppet:
|
|
|
|
bind::zone { 'example.org':
|
|
zone_type => 'master',
|
|
dynamic => false,
|
|
source => 'puppet:///dns/db.example.org',
|
|
allow_transfers => [ 'secondary-dns', ],
|
|
}
|
|
|
|
A master zone with DNSSec disabled which allows updates using a TSIG key and
|
|
zone transfers to servers matching an acl:
|
|
|
|
bind::zone { 'example.com-internal':
|
|
zone_type => 'master',
|
|
domain => 'example.com',
|
|
allow_updates => [ 'key local-update', ],
|
|
allow_transfers => [ 'secondary-dns', ],
|
|
ns_notify => true,
|
|
dnssec => false,
|
|
}
|
|
|
|
A master zone with DNSSec enabled which allows updates using a TSIG key and
|
|
zone transfers to servers matching an acl:
|
|
|
|
bind::zone { 'example.com-external':
|
|
zone_type => 'master',
|
|
domain => 'example.com',
|
|
allow_updates => [ 'key local-update', ],
|
|
allow_transfers => [ 'secondary-dns', ],
|
|
ns_notify => true,
|
|
dnssec => true,
|
|
key_directory => '/var/cache/bind/example.com',
|
|
}
|
|
|
|
A master zone which is initialized with a pre-existing zone file (for example,
|
|
to migrate an existing zone to a bind-module controlled server or to recover
|
|
from a backup):
|
|
|
|
bind::zone { 'example.com':
|
|
zone_type => 'master',
|
|
source => 'puppet:///backups/dns/example.com',
|
|
}
|
|
|
|
A slave zone which allows notifications from servers matched by IP:
|
|
|
|
bind::zone { 'example.net':
|
|
zone_type => 'slave',
|
|
masters => [ '198.0.2.2' ],
|
|
allow_notify => [ '192.0.2.2' ],
|
|
ns_notify => false,
|
|
}
|
|
|
|
A forward zone:
|
|
|
|
bind::zone { 'example.org':
|
|
zone_type => 'forward',
|
|
forwarders => [ '10.0.2.4', ],
|
|
forward => 'only',
|
|
}
|
|
|
|
###bind::view
|
|
|
|
Declares a view in the BIND configuration. In order to declare zones in a
|
|
server configuration there must be at least one view declaration which includes
|
|
the zones.
|
|
|
|
A common use for views is to use a single dual-homed nameserver as a resolver
|
|
on a private network and an authoritative non-resolving nameserver on the
|
|
Internet. Furthermore, the Internet-facing and private network-facing views may
|
|
present different authoritative results for a domain. Given a BIND server
|
|
connected to the internet with the address 198.0.2.2 and connected to a private
|
|
network with the address 10.0.2.2, here are the `bind::view` declarations that
|
|
would create this configuration:
|
|
|
|
bind::view { 'internet':
|
|
recursion => false,
|
|
match_destinations => [ '198.0.2.2', ],
|
|
zones => [ 'example.net', 'example.com-external', ],
|
|
}
|
|
|
|
bind::view { 'private':
|
|
recursion => true,
|
|
match_destinations => [ '10.0.2.2', ],
|
|
zones => [ 'example.net', 'example.com-internal', ],
|
|
}
|
|
|
|
In this scenario, the example.com domain has two separate zones that are
|
|
presented in each of the `internet` and `private` views. These two zones are
|
|
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 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
|
|
this example, service is restricted to a specific set of client address ranges,
|
|
and queries for the `example.org` domain are handled using a declared zone (see
|
|
`bind::zone` declaration for `example.org` above):
|
|
|
|
bind::view { 'clients':
|
|
recursion => true,
|
|
match_clients => [
|
|
'10.10.0.0/24',
|
|
'10.100.0.0/24',
|
|
],
|
|
zones => [
|
|
'example.org',
|
|
],
|
|
}
|
|
|
|
View declarations can also include server clause configuration. The `servers`
|
|
property of `bind::view` accepts an array value which specifies each `server`
|
|
clause in the view as a hash. The hash must contain an `ip_addr` key which
|
|
specifies the IP address (optionally, a CIDR address range), and may contain a
|
|
`keys` key with a string value. The value of `keys` will be used as the name of
|
|
a key in the `server` clause. In this example, the `ns` view will contain a
|
|
`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 => [
|
|
{
|
|
'ip_addr' => '192.168.24.2',
|
|
'keys' => 'internal-ns',
|
|
},
|
|
{
|
|
'ip_addr' => '216.218.130.2',
|
|
'keys' => 'hurricane-electric',
|
|
}
|
|
],
|
|
...
|
|
}
|
|
|
|
###resource_record
|
|
|
|
Declares a resource record. For exampmle:
|
|
|
|
resource_record { 'www.example.com address':
|
|
ensure => present,
|
|
record => 'www.example.com',
|
|
type => 'A',
|
|
data => [ '172.16.32.10', '172.16.32.11' ],
|
|
ttl => 86400,
|
|
zone => 'example.com',
|
|
server => 'ns.example.com',
|
|
keyname => 'local',
|
|
hmac => 'hmac-sha1',
|
|
secret => 'aLE5LA=='
|
|
}
|
|
|
|
This resource declaration will result in address records with the addresses
|
|
172.16.32.10 and 172.16.32.11 (`data`), a TTL of 86400 (`ttl`) in the zone
|
|
example.com (`zone`). Any updates necessary to create, update, or destroy these
|
|
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
|
|
for disambiguation of resources within Puppet.
|
|
|
|
`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`
|
|
`CNAME` `NS` `MX` `SPF` `SRV` `NAPTR` `PTR` or `TXT`. Other DNS record types
|
|
are not currently supported.
|
|
|
|
`rrclass` is the class of the record. The default value is `IN` and allowed
|
|
values are `IN`, `CH`, and `HS`.
|
|
|
|
`data` is required, and may be a scalar value or an array of scalar values
|
|
whose format conform to the type of DNS resource record being created. `data`
|
|
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`, `PTR`, `NAPTR`, or `SRV`) you must specify
|
|
the name as a fully-qualified name with a trailing dot in order to satisfy
|
|
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
|
|
property and changes will be reflected in DNS.
|
|
|
|
`zone` is not required, and generally not needed. It is only necessary to
|
|
specify the zone to be updated if the target nameserver has the record in
|
|
multiple zones, e.g. the NS records of a zone whose parent zone is served by
|
|
the same nameserver.
|
|
|
|
`server` defaults to "localhost" and need not be specified. The value may be
|
|
either a hostname or IP address.
|
|
|
|
`query_section` indicates the section of the DNS response to check for existing
|
|
record values. It must be one of `answer`, `authority`, or `additional`.
|
|
Defaults to: `answer`
|
|
|
|
`keyname` defaults to "update" and need not be specified. This parameter
|
|
specifies the name of a TSIG key to be used to authenticate the update. The
|
|
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
|
|
parameter has no effect if a `secret` is specified.
|
|
|
|
`hmac` defaults to "hmac-sha1" and need not be specified. This parameter
|
|
specifies the algorithm of the TSIG key to be used to authenticate the update.
|
|
The resource only uses a TSIG key if a `secret` is specified.
|
|
|
|
`secret` is optional. This parameter specifies the encoded cryptographic secret
|
|
of the TSIG key to be used to authenticate the update. If no `secret` is
|
|
specified, then the update will not use TSIG authentication.
|
|
|
|
####resource_record examples
|
|
|
|
Mail exchangers for a domain. Declares three mail exchangers for the domain
|
|
`example.com`, which are `mx.example.com`, `mx2.example.com`, and
|
|
`mx.mail-host.ex` with priorities `10`, `20`, and `30`, respectively (note the
|
|
trailing dots in the values to denote fully-qualified names):
|
|
|
|
resource_record { 'example.com mail exchangers':
|
|
record => 'example.com',
|
|
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
|
|
`example.com`, which are `ns1.example.com`, `ns2.example.com`, and
|
|
`ns.dns-host.ex`:
|
|
|
|
resource_record { 'example.com name servers':
|
|
record => 'example.com',
|
|
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
|
|
the parent zone in order to delegate authority for a subdomain:
|
|
|
|
resource_record { 'sub.example.com delegation':
|
|
record => 'sub.example.com'
|
|
type => 'NS',
|
|
zone => 'example.com',
|
|
query_section => 'authority',
|
|
data => 'sub-ns.example.com.',
|
|
}
|
|
|
|
Service locators records for a domain. Declares a service locator for SIP over
|
|
UDP to the domain `example.com`, in which the service located at port `5060` of
|
|
`inbound.sip-host.ex` is given priority `5` and weight `100`.
|
|
|
|
resource_record { 'example.com SIP service locator':
|
|
record => '_sip._udp.example.com',
|
|
type => 'SRV',
|
|
data => [ '5 100 5060 inbound.sip-host.ex.', ],
|
|
}
|