bind

Table of Contents

1. Description
2. Setup - The basics of getting started with bind
   • What bind affects
   • Setup requirements
   • Beginning with bind
3. Usage - Configuration options and additional functionality
4. Limitations - OS compatibility, etc.
5. Development - Guide for contributing to the module

Description

This module manages the BIND Name Server on Debian and Ubuntu. The module supports setting up a Caching Name Server or an Authoritative Name Server using primary and secondary zones.

Setup

What bind affects

The module manages the named process and related service files. It also managed the configuration and zone files. On Debian and Ubuntu these files are below the /etc/bind, /var/lib/bind and /var/cache/bind directories. The module uses a multi-level directory tree below /var/lib/bind to separate primary and secondary zone files.

Setup Requirements

The module uses the stdlib and concat modules. It is tested on Debian and Ubuntu using Puppet 6.

Beginning with bind

Set up a caching name server on localhost:

class { 'bind':
  listen_on         => [ '127.0.0.1', ],
  listen_on_v6      => [ 'none', ],
  allow_query       => [ 'localhost', ],
  allow_query_cache => [ 'localhost', ],
  allow_recursion   => [ 'localhost', ],
}

Usage

Set up a caching name server that provides recursive name resolution for a local subnet:

class { 'bind':
  allow_query       => [ 'localhost', '10/8', ],
  allow_query_cache => [ 'localhost', '10/8', ],
  allow_recursion   => [ 'localhost', '10/8', ],
}

Set up a caching name server that provides recursive name resolution for a local subnet and uses forwarders:

class { 'bind':
  allow_query       => [ 'localhost', '10/8', ],
  allow_query_cache => [ 'localhost', '10/8', ],
  allow_recursion   => [ 'localhost', '10/8', ],
  forwarders        => [ '10.0.0.53', '10.1.1.53', ],
}

Add a primary zone for the example.com domain:

bind::zone::primary { 'example.com':
  source => 'puppet:///modules/profile/dns/example.com.zone',
}

The zone file will be managed on the server as /var/lib/bind/primary/com/example/db.example.com. This tree structure is better than a flat directory structure if many zones will be managed by the server.

Reference

See REFERENCE.md

Limitations

Not all BIND features are currently implemented as I started with the options I needed myself. Some options are not yet available and features like DNSSEC inline signing are not well tested.

Development

You may open Github issues for this module if you need additional options currently not available.

Feel free to send pull requests for new features.

Reference

Table of Contents

Classes

• bind: Manage the Bind DNS daemon and configuration
• bind::rate_limit: Manage rate limiting

Defined types

Public Defined types

• bind::acl: Manage ACL entries
• bind::controls::inet: Manage an inet control channel
• bind::controls::unix: Manage a unix control channel
• bind::key: Manage secret keys
• bind::listen_on: Manage listen-on option clause
• bind::listen_on_v6: Manage listen-on-v6 option clause
• bind::logging::category: Manage logging category
• bind::logging::channel_file: Manage logging channel to a logfile
• bind::logging::channel_syslog: Manage logging channel to syslog
• bind::statistics_channel: Manage statistics channel
• bind::view: Manage a view
• bind::zone::forward: Manage a forward zone
• bind::zone::hint: Manage a hint zone
• bind::zone::in_view: Manage a in-view zone reference
• bind::zone::mirror: Manage a mirror zone
• bind::zone::primary: Manage a primary zone
• bind::zone::secondary: Manage a secondary zone

Private Defined types

• bind::aml: Manage an address match list
• bind::config: Manage configuration files

Resource types

• dnssec_key: Create, delete and maintain DNSSEC key files on the DNS server.

Functions

• bind::gencfg: Generate a configuration snippet from a hash
• bind::zonefile_path: Generate the zonefile name from zone

Data types

• Bind::AddressMatchList: Type to match allowed values for an address match list
• Bind::Auto_dnssec: Type to match allowed values for the auto-dnssec option
• Bind::DNSSECValidation: Type to match allowed values for the dnssec-validation option
• Bind::Filter_aaaa_on_v4: Type to match allowed values for the filter-aaaa-on-v4 option
• Bind::Forward: Type to match allowed values for the forward option
• Bind::Key::Algorithm: Type to match allowed values for the key algorithm
• Bind::Notify_secondaries: Type to match allowed values for the notify option
• Bind::Syslog::Facility: Type to match allowed values for the syslog facility
• Bind::Syslog::Severity: Type to match allowed values for the syslog severity
• Bind::Zone::Class: Type to match allowed values for the zone class

Classes

bind

Manage the Bind DNS daemon and configuration

Examples

Install a local caching resolver

class { 'bind':
  listen_on         => [ '127.0.0.1' ],
  listen_on_v6      => [ '::1' ],
  allow_query       => [ '127.0.0.1', '::1' ],
  allow_query_cache => [ '127.0.0.1', '::1' ],
  allow_recursion   => [ '127.0.0.1', '::1' ],
}

Use custom options to set uncommon options

class { 'bind':
  listen_on      => [ '127.0.0.1' ],
  custom_options => {
    'tcp-idle-timeout' => 600,
    'dnstab'           => [ 'auth', 'resolver', ],
    'rrset-order'      => {
      'type A name "example.com"'    => 'order random',
      'type AAAA name "example.com"' => 'order cyclic',
    },
  },
}

Parameters

The following parameters are available in the bind class:

• confdir
• vardir
• cachedir
• rndc_keyfile
• rndc_program
• bind_user
• bind_group
• package_name
• service_name
• listen_on
• listen_on_v6
• ipv4_enable
• ipv6_enable
• views_enable
• dnssec_enable
• dnssec_lookaside
• dnssec_validation
• empty_zones_enable
• root_mirror_enable
• control_channels_enable
• allow_query
• allow_recursion
• blackhole
• forwarders
• forward
• filter_aaaa_on_v4
• max_cache_size
• max_cache_ttl
• max_ncache_ttl
• custom_options
• package_ensure
• service_ensure
• service_enable
• manage_rndc_keyfile
• report_hostname
• report_version
• allow_query_cache
• root_hints_enable
• root_hints_source
• localhost_forward_enable
• localhost_forward_source
• localhost_reverse_enable
• localhost_reverse_source
• min_cache_ttl
• min_ncache_ttl
• servfail_ttl
• querylog_enable

confdir

Data type: Stdlib::Absolutepath

The directory where the main Bind configuration file is located. Example: /etc/bind.

Default: operating system specific

vardir

Data type: Stdlib::Absolutepath

The directory where Bind stores other config files (zonefiles, ...). Example: /var/lib/bind.

Default: operating system specific

cachedir

Data type: Stdlib::Absolutepath

The directory where Bind stores volatile data. Example: /var/cache/bind.

Default: operating system specific

rndc_keyfile

Data type: Stdlib::Absolutepath

The file where the secret key for the rndc program is stored.

Default: operating system specific

rndc_program

Data type: Stdlib::Absolutepath

The full path of the rndc program.

Default: operating system specific

bind_user

Data type: String

Run the Bind daemon as this user. This parameter is also used to set the owner of some directories and files that the Bind daemon needs to write to.

Default: operating system specific

bind_group

Data type: String

The group ownership for some Bind related directories and files.

Default: operating system specific

package_name

Data type: String

The name of the Bind package to install.

Default: operating system specific

service_name

Data type: String

The name of the Bind service to manage.

Default: operating system specific

listen_on

Data type: Bind::AddressMatchList

An array of strings to define the IPv4 address(es) on which the daemon will listen for queries. The string any may be used to listen on all available interfaces and addresses. This is also the default if the parameter is unset. The string none may be used to disable IPv4.

Use bind::listen_on to define more complex configurations.

Default value: []

listen_on_v6

Data type: Bind::AddressMatchList

An array of strings to define the IPv6 address(es) on which the daemon will listen for queries. The string any may be used to listen on all available interfaces and addresses. This is also the default if the parameter is unset. The string none may be used to disable IPv6.

Use bind::listen_on_v6 to define more complex configurations.

Default value: []

ipv4_enable

Data type: Boolean

Should Bind use IPv4. At least one of ipv4_enable and ipv6_enable must be set to true.

Default value: true

ipv6_enable

Data type: Boolean

Should Bind use IPv6. At least one of ipv4_enable and ipv6_enable must be set to true.

Default value: true

views_enable

Data type: Boolean

Should views be enabled.

Default value: false

dnssec_enable

Data type: Boolean

Should DNSSEC be enabled. This parameter is ignored for Bind 9.16.0 or later where DNSSEC is always enabled.

Default value: true

dnssec_lookaside

Data type: Boolean

Should DNSSEC Lookaside Validation be enabled. This parameter is ignored for Bind 9.16.0 or later where DNSSEC Lookaside Validation is obsolete.

Default value: false

dnssec_validation

Data type: Bind::DNSSECValidation

Should DNSSEC Validation be enabled.

Default value: 'auto'

empty_zones_enable

Data type: Boolean

Should automatic empty zones be enabled.

Default value: true

root_mirror_enable

Data type: Boolean

Should a local mirror zone the root zone be configured.

Default value: false

control_channels_enable

Data type: Boolean

Should control channels be enabled. All bind::controls::unix and bind::controls::inet configuration items will be ignored if this is set to false. In this case an empty controls statement will be generated and the default control channel will also be disabled. The default control channel will be enabled automatically if this parameter is true and no explicit channels are created using the bind::controls::unix or bind::controls::inet defined type.

Default value: true

allow_query

Data type: Bind::AddressMatchList

An array of IP addresses/networks or ACL names that are allowed to query this Bind server.

Default value: []

allow_recursion

Data type: Bind::AddressMatchList

An array of IP addresses/networks or ACL names that are allowed to use this Bind server for recursion. Recursion is automatically turned on if this parameter is not empty.

Default value: []

blackhole

Data type: Bind::AddressMatchList

An array of IP addresses/networks that are ignored by the server. Requests from sources matching this list will not be answered.

Default value: []

forwarders

Data type: Bind::AddressMatchList

An array of other DNS servers that can be used to forward unresolvable queries to.

Default value: []

forward

Data type: Bind::Forward

The type of forwarding used. This parameter is only used if forwarders are actually defined. Valid values: 'first', 'only'. Note that automatic empty zones for RFC 6303 are ignored if this parameter is set to only.

Default value: 'first'

filter_aaaa_on_v4

Data type: Bind::Filter_aaaa_on_v4

Should AAAA records be omitted from the response if the IPv4 transport is used. If this is set to yes then it does not apply if the queried zone is DNSSEC-signed. Setting this parameter to break-dnssec will also omit DNSSEC related RRs if AAAA records are filtered. Valid options: no, yes, break-dnssec.

Default value: 'no'

max_cache_size

Data type: Integer

The maximum number of bytes to use for the server's cache. If views are used then the size applies to every view separately. If this value is zero then no limit is configured.

Default value: 0

max_cache_ttl

Data type: Integer

The maximum number of seconds for which the server will cache positive answers. If this value is zero then the config parameter will be omitted and the Bind default of 1 week will be used.

Default value: 0

max_ncache_ttl

Data type: Integer

The maximum number of seconds for which the server will cache negative answers. If this value is zero then the config parameter will be omitted and the Bind default of 3 hours will be used.

Default value: 0

custom_options

Data type: Hash[String,Data]

Additional config options that are not implemented as class parameters can be set by a hash of custom options. Each key of the hash will be added to the option block of the configuration. For string or numeric values the value will be added as a normal option value. If the value is a hash or an array it will be included as an additional block enclosed in braces.

Default value: {}

package_ensure

Data type: String

The state of the Bind package. Normally this is set to installed or a specific version number.

Default value: 'installed'

service_ensure

Data type: Stdlib::Ensure::Service

Whether the Bind service should be running.

Default value: 'running'

service_enable

Data type: Boolean

Should the Bind service be enabled.

Default value: true

manage_rndc_keyfile

Data type: Boolean

Should the rndc key file be managed by the main class. If this is true (the default) then the secret key generated by the package installation will be used. Only the file mode and owner are managed without updating the content of the key file. If this is false then the key file for the rndc tool is not managed by the main class. Use the bind::key defined type to manage the key on your own. Caution: changing the key while named is running leads to a problem because Puppet can't reload or restart the service after the key file has been updated because the daemon still uses the old key.

Default value: true

report_hostname

Data type: Optional[String]

The hostname the will be reported by Bind. If this is undefined (default), then Bind will report the local hostname. Set this to a string to hide the hostname and report the given string instead. Use the empty string to disable hostname reporting completely.

Default value: undef

report_version

Data type: Optional[String]

The version string that will be reported by Bind. If this is undefined (default), then Bind will report the version that has been installed. Set this to a string to hide the version number and report the given string instead. Use the empty string to disable version reporting completely.

Use the following command to test: dig @127.0.0.1 version.bind chaos txt

Default value: undef

allow_query_cache

Data type: Bind::AddressMatchList

Default value: []

root_hints_enable

Data type: Boolean

Default value: true

root_hints_source

Data type: String

Default value: "puppet:///modules/${module_name}/zones/db.root"

localhost_forward_enable

Data type: Boolean

Default value: true

localhost_forward_source

Data type: String

Default value: "puppet:///modules/${module_name}/zones/db.localhost"

localhost_reverse_enable

Data type: Boolean

Default value: true

localhost_reverse_source

Data type: String

Default value: "puppet:///modules/${module_name}/zones/db.127"

min_cache_ttl

Data type: Integer

Default value: 0

min_ncache_ttl

Data type: Integer

Default value: 0

servfail_ttl

Data type: Integer

Default value: 0

querylog_enable

Data type: Optional[Boolean]

Default value: undef

bind::rate_limit

Manage rate limiting

Examples

Establish a limit

class { 'bind::rate_limit':
  all_per_second => 1000,
}

Parameters

The following parameters are available in the bind::rate_limit class:

• window
• ipv4_prefix_length
• ipv6_prefix_length
• log_only
• exempt_clients
• all_per_second
• errors_per_second
• responses_per_second
• referrals_per_second
• nodata_per_second
• nxdomains_per_second
• qps_scale
• slip

window

Data type: Integer[0,3600]

The size of the rolling window measured in seconds over which the rate limits are calculated.

Default value: 0

ipv4_prefix_length

Data type: Integer[0,32]

Define the number of bits that are used to group IPv4 addresses (like a netmask). The limits are applied to all requests having the same network prefix.

Default value: 0

ipv6_prefix_length

Data type: Integer[0,128]

Define the number of bits that are used to group IPv6 addresses (like a netmask). The limits are applied to all requests having the same network prefix.

Default value: 0

log_only

Data type: Boolean

Do not really limit the queries but only log that it would happen. This can be used to test limits before enforcing them.

Default value: false

exempt_clients

Data type: Array[String]

An array of IP addresses/networks or ACL names that are never limited.

Default value: []

all_per_second

Data type: Optional[Integer[0,1000]]

Limit the number of total answers per second for an IP address to the given value.

Default value: undef

errors_per_second

Data type: Optional[Integer[0,1000]]

Limit the number of total error answers per second for an IP address to the given value.

Default value: undef

responses_per_second

Data type: Optional[Integer[0,1000]]

Limit the number of identical responses per second for an IP address to the given value.

Default value: undef

referrals_per_second

Data type: Optional[Integer[0,1000]]

Limit the number of referrals per second to the given value.

Default value: undef

nodata_per_second

Data type: Optional[Integer[0,1000]]

Limit the number of NODATA responses per second to the given value.

Default value: undef

nxdomains_per_second

Data type: Optional[Integer[0,1000]]

Limit the number of NXDOMAIN responses per second to the given value.

Default value: undef

qps_scale

Data type: Optional[Integer[0,1000]]

Value to define the query per second scaling.

Default value: undef

slip

Data type: Optional[Integer[0,10]]

Set the rate at which queries over the defined limit are returned with the truncate bit.

Default value: undef

Defined types

bind::acl

Manage ACL entries

Examples

Create an ACL for an internal network

bind::acl { 'internal':
  address_match_list => [ '10.0.0.0/8', ],
  comment            => 'internal network',
}

Parameters

The following parameters are available in the bind::acl defined type:

• address_match_list
• comment
• order
• acl

address_match_list

Data type: Array[String,1]

An array of IP addresses/networks, which can be referenced in other Bind configuration clauses to limit access to a component. The array parameter must have at least one entry.

comment

Data type: Optional[String]

An optional string that is used as comment in the generated ACL file.

Default value: undef

order

Data type: String

The sorting order of the ACLs in the configuration file.

Default value: '10'

acl

Data type: String

The name of the ACL. Defaults to the name of the resource.

Default value: $name

bind::controls::inet

Manage an inet control channel

Examples

Using the defined type

bind::controls::inet { '*':
  keys => [ 'rndc.key', ],
}

Parameters

The following parameters are available in the bind::controls::inet defined type:

• allow
• keys
• read_only
• address
• port

allow

Data type: Bind::AddressMatchList

The client addresses that are allowed to access this control channel.

Default value: []

keys

Data type: Array[String]

The name of the keys that will be used to authenticate access to this control channel.

Default value: []

read_only

Data type: Boolean

Should the control channel only allow read-only access.

Default value: false

address

Data type: String

The IPv4 or IPv6 address where the control channel will be created. This can also be the string * for all local IPv4 addresses or the string :: for all local IPv6 addresses.

Default value: $name

port

Data type: Optional[Stdlib::Port]

The port where the control channel will be listening. The default port 953 will be ised if this is unset.

Default value: undef

bind::controls::unix

Manage a unix control channel

Examples

Using the defined type

bind::controls::unix { '/run/named.ctl':
  owner => 0,
  group => 0,
  perm  => '0640',
  keys  => [ 'rndc.key', ],
}

Parameters

The following parameters are available in the bind::controls::unix defined type:

• owner
• group
• perm
• keys
• read_only
• path

owner

Data type: Integer

The owner of the unix control channel socket. This must be the integer value of the owner's user id.

group

Data type: Integer

The group of the unix control channel socket. This must be the integer value of the owner's group id.

perm

Data type: Stdlib::Filemode

The file permisssions of the unix control channel socket.

keys

Data type: Array[String]

The name of the keys that will be used to authenticate access to this control channel.

Default value: []

read_only

Data type: Boolean

Should the control channel only allow read-only access.

Default value: false

path

Data type: Stdlib::AbsolutePath

The file path of the unix control socket to create.

Default value: $name

bind::key

Manage secret keys

Examples

Using the defined type

bind::key { 'rndc-key':
  secret  => 'secret',
  keyfile => '/etc/bind/rndc.key',
}

Parameters

The following parameters are available in the bind::key defined type:

• key
• algorithm
• owner
• group
• mode
• manage_keyfile
• manage_content
• keyfile
• base64_secret
• secret
• seed

key

Data type: String

The name of the key.

Default value: $name

algorithm

Data type: Bind::Key::Algorithm

The algorithm to use for the encoding of the secret key. Can be one of: hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, hmac-sha512. The default is hmac-sha256.

Default value: 'hmac-sha256'

owner

Data type: String

The file owner for the key file.

Default value: 'root'

group

Data type: String

The file group for the key file.

Default value: $::bind::bind_group

mode

Data type: Stdlib::Filemode

The file mode for the key file.

Default value: '0640'

manage_keyfile

Data type: Boolean

Should the key file be managed by this defined type. Set this to false if you need to manage the key file from your own Puppet code. The code to include the key file in the daemon configuration is still generated when this parameter is false.

Default value: true

manage_content

Data type: Boolean

Should the content of the key file be managed by this defined type. Set this to false if you want to manage file permissions but do not want to manage the content of the file. This is useful for the key file used by the rndc utility. Normally a secret key for rndc is created during installation. Updating this key with Puppet creates a problem since the service can't be restarted cleanly after the file has been changed when the daemon still uses the old secret. So the key for the rndc tool is best left alone. The code to include the key file in the daemon configuration is still generated when this parameter is false.

Default value: true

keyfile

Data type: Optional[Stdlib::Absolutepath]

Set this parameter to a file name if you need to reference the key from other tools (like 'rndc'). In this case the file with the key will be saved in the named file. Otherwise a a system selected file will be used.

Default value: undef

base64_secret

Data type: Optional[String]

A base64 encoded secret to copy verbatim into the key. The parameters secret and seed are ignored if this parameter is set.

Default value: undef

secret

Data type: Optional[String]

The secret to use for the key. A random secret is created internally if this parameter is not set.

Default value: undef

seed

Data type: Optional[String]

An optional seed to use if the random secret is created internally.

Default value: undef

bind::listen_on

Manage listen-on option clause

Examples

Listen on the loopback interface

listen_on { '127.0.0.1': }

Listen on two interfaces

listen_on { 'IPv4':
  address => [ '10.0.0.1', '192.168.0.1' ],
}

Listen on a non-default port

listen_on { '127.0.0.1':
  port    => 8053,
}

Parameters

The following parameters are available in the bind::listen_on defined type:

• address
• port

address

Data type: Bind::AddressMatchList

A single string or an array of strings to define the port and IP address(es) on which the daemon will listen for queries. The string any may be used to listen on all available interfaces and addresses. The string none may be used to disable IPv4.

Default value: $name

port

Data type: Optional[Stdlib::Port]

The port number on which the daemon will listen. Port 53 will be used if this is not defined.

Default value: undef

bind::listen_on_v6

Manage listen-on-v6 option clause

Examples

Listen on the IPv6 loopback interface

listen_on_v6 { '::1': }

Listen on a non-default port

listen_on_v6 { '::1':
  port => 8053,
}

Parameters

The following parameters are available in the bind::listen_on_v6 defined type:

• address
• port

address

Data type: Variant[String,Array[String,1]]

A single string or an array of strings to define the port and IP address(es) on which the daemon will listen for queries. The string any may be used to listen on all available interfaces and addresses. The string none may be used to disable IPv6.

Default value: $name

port

Data type: Optional[Stdlib::Port]

The port number on which the daemon will listen. Port 53 will be used if this is not defined.

Default value: undef

bind::logging::category

Manage logging category

Examples

Use a single channel

bind::logging::category { 'default':
  channels => 'syslog',
}

Use multiple channels

bind::logging::category { 'default':
  channels => [ 'syslog', 'file', ],
}

Parameters

The following parameters are available in the bind::logging::category defined type:

• channels
• category
• order

channels

Data type: Variant[String,Array[String]]

A string or an array of strings to define the channels to use for this category.

category

Data type: String

The logging category.

Default value: $name

order

Data type: String

A string to use for ordering different categories in the configuration file.

Default value: '50'

bind::logging::channel_file

Manage logging channel to a logfile

Examples

Define a logfile channel for Bind9

bind::logging::channel_file { 'security':
  logfile => '/var/lob/bind/security',
}

Parameters

The following parameters are available in the bind::logging::channel_file defined type:

• logfile
• channel
• severity
• print_category
• print_severity
• print_time
• size
• versions
• mode

logfile

Data type: Stdlib::Absolutepath

The filename where the logs are written to.

channel

Data type: String

The name of the channel for the logfile. Use bind::logging::category to route a given category to this channel.

Default value: $name

severity

Data type: Bind::Syslog::Severity

The severity of log messages that are written to the file. Valid values: critical, error, warning, notice, info, debug, dynamic.

Default value: 'notice'

print_category

Data type: Boolean

Should the category of the message be logged to the file.

Default value: true

print_severity

Data type: Boolean

Should the severity of the message be logged to the file.

Default value: true

print_time

Data type: Boolean

Should a timestamp be logged to the file.

Default value: true

size

Data type: Optional[String]

The maximum size of the logfile. Log rotation takes place if this size is reached. If the size is undefined then the logfile will not be rotated.

Default value: undef

versions

Data type: Optional[Integer]

The number of logfiles to keep if log rotation is used.

Default value: undef

mode

Data type: Optional[Stdlib::Filemode]

The file mode of the logfile. No file mode will be enforced if this is undefined.

Default value: undef

bind::logging::channel_syslog

Manage logging channel to syslog

Examples

Define a syslog channel for Bind9

bind::logging::channel_syslog { 'syslog':
  facility => 'local0',
  severity => 'info',
}

Parameters

The following parameters are available in the bind::logging::channel_syslog defined type:

• channel
• facility
• severity
• print_category
• print_severity
• print_time

channel

Data type: String

The name of the channel. Use bind::logging::category to route a given category to this channel.

Default value: $name

facility

Data type: Bind::Syslog::Facility

The syslog facility to use. Valid value: auth, authpriv, cron, daemon, ftp, kern, local0, local1, local2, local3, local4, local5, local6, local7, lpr, mail, news, syslog, user, uucp.

Default value: 'daemon'

severity

Data type: Bind::Syslog::Severity

The severity of log messages that are written to the file. Valid values: critical, error, warning, notice, info, debug, dynamic.

Default value: 'notice'

print_category

Data type: Optional[Boolean]

Should the category of the message be logged to the file.

Default value: undef

print_severity

Data type: Optional[Boolean]

Should the severity of the message be logged to the file.

Default value: undef

print_time

Data type: Optional[Boolean]

Should a timestamp be logged to the file.

Default value: undef

bind::statistics_channel

Manage statistics channel

Examples

Create a statistics channel for localhost access

bind::statistics_channel { '127.0.0.1':
  port  => 8053,
  allow => [ '127.0.0.1', ],
}

Parameters

The following parameters are available in the bind::statistics_channel defined type:

• port
• allow
• ip

port

Data type: Optional[Stdlib::Port]

The port number to listen on. If no port is specified, port 80 is used.

Default value: undef

allow

Data type: Array[String]

An array of IP addresses that are allowed to query the statistics. If this parameter is not set, all remote addresses are permitted to use the statistics channel.

Default value: []

ip

Data type: String

The IP address to listen on. This can be an IPv4 address or an IPv6 address if IPv6 is in use. An address of * is interpreted as the IPv4 wildcard address.

Default value: $name

bind::view

Manage a view

Examples

Create a view for a guest network

bind::view { 'guest':
  match_clients   => [ 'guest' ],
  allow_recursion => [ 'any' ],
}

Parameters

The following parameters are available in the bind::view defined type:

• match_clients
• match_destinations
• allow_query
• allow_query_on
• recursion
• match_recursive_only
• allow_recursion
• allow_recursion_on
• allow_query_cache
• allow_query_cache_on
• allow_transfer
• root_mirror_enable
• view
• order
• root_hints_enable
• localhost_forward_enable
• localhost_reverse_enable

match_clients

Data type: Array[String]

An array of ACL names or networks that this view will be used for.

Default value: [ 'any', ]

match_destinations

Data type: Array[String]

An array of ACL names or networks. The view is used if the query destination matches this list.

Default value: []

allow_query

Data type: Array[String]

An array of ACL names or networks that are allowed to query the view.

Default value: [ 'any', ]

allow_query_on

Data type: Array[String]

An array of interfaces on the DNS server from which queries are accepted.

Default value: []

recursion

Data type: Boolean

Should recursion be enabled for this view.

Default value: true

match_recursive_only

Data type: Boolean

Should this view be used for recursive queried only.

Default value: false

allow_recursion

Data type: Array[String]

An array of ACL names or networks for which recursive queries are allowed.

Default value: []

allow_recursion_on

Data type: Array[String]

An array of interfaces on the DNS server from which recursive queries are accepted.

Default value: []

allow_query_cache

Data type: Array[String]

An array of ACL names or networks for which access to the cache is allowed.

Default value: []

allow_query_cache_on

Data type: Array[String]

An array of interfaces on the DNS server from which access to the cache is allowed.

Default value: []

allow_transfer

Data type: Array[String]

An array of ACL names or networks that are allowed to transfer zone information from this server.

Default value: []

root_mirror_enable

Data type: Boolean

Enable local root zone mirror for the view.

Default value: false

view

Data type: String

The name of the view.

Default value: $name

order

Data type: String

The order in which different views are configured. The first matching view is used to answer the query for a client. If you use one view where match_clients contains any then this view should probably have the highest order value.

Default value: '10'

root_hints_enable

Data type: Optional[Boolean]

Default value: undef

localhost_forward_enable

Data type: Optional[Boolean]

Default value: undef

localhost_reverse_enable

Data type: Optional[Boolean]

Default value: undef

bind::zone::forward

Manage a forward zone

Examples

Using the defined type

bind::zone::forward { 'example.com':
  forwarders => [ '192.168.1.1', '192.168.1.2', ],
  forward    => 'only',
}

Parameters

The following parameters are available in the bind::zone::forward defined type:

• forwarders
• forward
• view
• zone
• comment
• class
• order

forwarders

Data type: Array[String]

An array of strings that define the forwarding servers for this zone. All queries for the zone will be forwarded to these servers.

Default value: []

forward

Data type: Optional[Bind::Forward]

Only forward queries (value only) or try to resolve if forwarders do not answer the query (value first).

Default value: undef

view

Data type: Optional[String]

The name of the view that should include this zone. Must be set if views are used.

Default value: undef

zone

Data type: String

The name of the zone.

Default value: $name

comment

Data type: Optional[String]

Default value: undef

class

Data type: Bind::Zone::Class

Default value: 'IN'

order

Data type: String

Default value: '40'

bind::zone::hint

Manage a hint zone

Examples

Using the defined type

bind::zone::hint { '.':
  file => '/etc/bind/db.root',
}

Parameters

The following parameters are available in the bind::zone::hint defined type:

• zone
• file
• view
• comment
• class
• order

zone

Data type: String

The name of the zone.

Default value: $name

file

Data type: String

view

Data type: Optional[String]

Default value: undef

comment

Data type: Optional[String]

Default value: undef

class

Data type: Bind::Zone::Class

Default value: 'IN'

order

Data type: String

Default value: '10'

bind::zone::in_view

Manage a in-view zone reference

Examples

Using the defined type

bind::zone::in_view { 'example.com':
  view    => 'internal',
  in_view => 'external',
}

Parameters

The following parameters are available in the bind::zone::in_view defined type:

• view
• in_view
• zone
• comment
• class
• order

view

Data type: String

The name of the view that should include this zone.

in_view

Data type: String

The name of the view where the referenced view is defined.

zone

Data type: String

The name of the zone.

Default value: $name

comment

Data type: Optional[String]

Default value: undef

class

Data type: Bind::Zone::Class

Default value: 'IN'

order

Data type: String

Default value: '60'

bind::zone::mirror

Manage a mirror zone

Examples

Using the defined type

bind::zone::mirror { '.':
}

Parameters

The following parameters are available in the bind::zone::mirror defined type:

• zone
• view
• comment
• class
• order

zone

Data type: String

The name of the zone.

Default value: $name

view

Data type: Optional[String]

Default value: undef

comment

Data type: Optional[String]

Default value: undef

class

Data type: Bind::Zone::Class

Default value: 'IN'

order

Data type: String

Default value: '50'

bind::zone::primary

Manage a primary zone

Examples

Create a primary zone

bind::zone::primary { 'example.com':
  source => 'puppet:///modules/profile/example.com.zone',
}

Use DNSSEC inline signing for a primary zone

bind::zone::primary { 'example.com':
  inline_signing => true,
  auto_dnssec    => 'maintain',
  source         => 'puppet:///modules/profile/example.com.zone',
}

Parameters

The following parameters are available in the bind::zone::primary defined type:

• dnssec
• inline_signing
• auto_dnssec
• also_notify
• notify_secondaries
• view
• source
• content
• zone_statistics
• zone
• file
• comment
• class
• order

dnssec

Data type: Boolean

Enable DNSSEC for the zone.

Default value: false

inline_signing

Data type: Boolean

Enable inline signing for the zone.

Default value: false

auto_dnssec

Data type: Bind::Auto_dnssec

How to sign and resign the DNSSEC zone. Can be one of allow, maintain or off.

Default value: 'off'

also_notify

Data type: Array[String]

Secondary servers that should be notified in addition to the nameservers that are listed in the zone file.

Default value: []

notify_secondaries

Data type: Optional[Bind::Notify_secondaries]

Should NOTIFY messages be sent out to the name servers defined in the NS records for the zone. The messages are sent to all name servers except itself and the primary name server defined in the SOA record and to any IPs listed in any also-notify statement. Can be either yes, no or explicit.

Default value: undef

view

Data type: Optional[String]

The name of the view that should include this zone. Must be set if views are used.

Default value: undef

source

Data type: Optional[String]

The source for the zone file. See the standard Puppet file type.

Default value: undef

content

Data type: Optional[String]

The content for the zone file. See the standard Puppet file type.

Default value: undef

zone_statistics

Data type: Optional[Boolean]

Collect statistics for this zone.

Default value: undef

zone

Data type: String

The name of the zone.

Default value: $name

file

Data type: Optional[String]

Default value: undef

comment

Data type: Optional[String]

Default value: undef

class

Data type: Bind::Zone::Class

Default value: 'IN'

order

Data type: String

Default value: '20'

bind::zone::secondary

Manage a secondary zone

Examples

Create a secondary zone

bind::zone::secondary { 'example.com':
  masters => [ '192.168.1.1', ],
}

Parameters

The following parameters are available in the bind::zone::secondary defined type:

• masters
• view
• zone_statistics
• multi_master
• zone
• comment
• class
• order

masters

Data type: Array[String,1]

An array of strings that define the master servers for this zone. There must be at least one master server for a secondary zone.

view

Data type: Optional[String]

The name of the view that should include this zone. Must be set if views are used.

Default value: undef

zone_statistics

Data type: Optional[Boolean]

Collect statistics for this zone.

Default value: undef

multi_master

Data type: Optional[Boolean]

If the zone has multiple primaries and the serial might be different for the masters then named normally logs a message. Set this to true to disable the message in this case.

Default value: undef

zone

Data type: String

The name of the zone.

Default value: $name

comment

Data type: Optional[String]

Default value: undef

class

Data type: Bind::Zone::Class

Default value: 'IN'

order

Data type: String

Default value: '30'

Resource types

dnssec_key

Caution: This functionality is in beta and is subject to change. The design and code is less mature than other features.

All intervals are interpreted as seconds if no unit is given. The following interval units can be used: y (year), mo (months), w (weeks), d (days), h (hours), mi (minutes).

Examples for valid intervals: 1y, 12mo, 1w, 7d, 24h, 720mi

The following diagram illustrates the lifecycle of the keys:

key-1 ---- active ----------><-- retired --><-- deleted --

key-2     <--- published ---><---------- active ----------><-- retired -->

          <----------------->
            prepublication
               interval

Examples

Create a Key Signing Key using defaults

dnssec_key { 'example.com':
  key_directory => '/etc/bind/keys',
  ksk           => true,
}

Create a Zone Signing Key using a specified algorithm and key size

dnssec_key { 'ZSK/example.com':
  zone          => 'example.com',
  key_directory => '/etc/bind/keys',
  algorithm     => 'RSASHA256',
  bits          => 2048,
}

Create Zone Signing Keys using automatic key rollover

dnssec_key { 'ZSK/example.com':
  zone          => 'example.com',
  key_directory => '/etc/bind/keys',
  publish       => '2w',
  active        => '1y',
  retire        => '4w',
  delete        => '1w',
  successor     => true,
}

Properties

The following properties are available in the dnssec_key type.

ensure

Valid values: present, absent

Specifies whether the destination file should exist. Setting this to "absent" tells Puppet to delete the destination file if it exists, and negates the effect of any other parameters.

Default value: present

Parameters

The following parameters are available in the dnssec_key type.

• active
• algorithm
• bits
• key_directory
• ksk
• name
• nsec3
• precreate
• prepublish
• provider
• purge
• retire
• revoke
• rrtype
• successor
• zone

active

Valid values: %r{^[0-9]+(y|mo|w|d|h|mi)?$}

The time interval that the key will be used for signing the zone.

algorithm

Valid values: DSA, ECCGOST, ECDSAP256SHA256, ECDSAP384SHA384, ED25519, ED448, NSEC3DSA, NSEC3RSASHA1, RSAMD5, RSASHA1, RSASHA256, RSASHA512

The cryptographic algorithm that the key should use.

Default value: RSASHA1

bits

Valid values: %r{^[0-9]+$}

The number of bits in the key. The possible range depends on the selected algorithm:

RSA : 512 .. 2048 DH : 128 .. 4096 DSA : 512 .. 1024 and an exact multiple of 64 HMAC : 1 .. 512

Elliptic curve algorithms don't need this parameter.

key_directory

The directory where the key should be created. This parameter is mandatory.

ksk

Valid values: true, false

Whether the key should be a Key Signing Key.

Default value: false

name

namevar

The name of the resource.

nsec3

Valid values: true, false

Whether the key should be NSEC3-capable.

Default value: false

precreate

Valid values: %r{^[0-9]+(y|mo|w|d|h|mi)?$}

The time interval before prepublication in which the key will be created. The interval must be long enough to ensure Puppet will run during this interval.

prepublish

Valid values: %r{^[0-9]+(y|mo|w|d|h|mi)?$}

The time interval before activation when the key will be published.

provider

The specific backend to use for this dnssec_key resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

purge

Valid values: true, false

Whether old keys should be purged after they are retired.

Default value: false

retire

Valid values: %r{^[0-9]+(y|mo|w|d|h|mi)?$}

The time interval that the key is still published after it became inactive.

revoke

Valid values: %r{^[0-9]+(y|mo|w|d|h|mi)?$}

The time interval that the key will have the revoke bit set. This parameter may only be used for zone-signing keys.

rrtype

Valid values: DNSKEY, KEY

The resource record type to use for the key.

Default value: DNSKEY

successor

Valid values: true, false

Whether the key should be created as an explicit successor to an existing key. In this case the name, algorithm, size and type of the key will be take from the existing key. The activation date will match the inactivation date of the existing key.

Default value: false

zone

Valid values: %r{^[a-zA-Z][a-zA-Z0-9.-]+\.[a-zA-Z]+$}

The zone for which the key should be generated. This must be a valid domain name. Defaults to the resource title if unset.

Functions

bind::gencfg

Type: Puppet Language

Generate a Bind configuration snippet from a hash. Each key of the hash is used as a config option. The can be a string, a numeric value, a boolean or an array or hash. the config option is terminated with a ';' char.

Strings and numeric values are included normally as parameter value. A boolean value is written as 'yes' or 'no'. Arrays are enclosed in braces and array values are returned as a single line if the number of elements is zero or one. Otherwise a new line is used for each value. Hashes are also enclosed in braces and the keys and values are processed recursively.

Examples

String value

bind::gencfg({ 'foo' => 'bar' }, 2)

  foo bar;

Numeric value

bind::gencfg({ 'foo' => 42 }, 2)

  foo 42;

Boolean value

bind::gencfg({ 'foo' => true }, 2)

  foo yes;

Array value with zero elements

bind::gencfg({ 'foo' => [] }, 2)

  foo { };

Array value with one element

bind::gencfg({ 'foo' => ['bar'] }, 2)

  foo { bar; };

Array value with multiple elements

bind::gencfg({ 'foo' => ['bar', 'baz'] }, 2)

  foo {
    bar;
    baz;
  };

Hash value

bind::gencfg({ 'foo' => { 'bar' => 'qux', 'quux' => 'baz' } }, 2)

  foo {
    bar  qux;
    quux baz;
  };

bind::gencfg(Hash[String,Data] $config, Integer $indent = 0)

Generate a Bind configuration snippet from a hash. Each key of the hash is used as a config option. The can be a string, a numeric value, a boolean or an array or hash. the config option is terminated with a ';' char.

Strings and numeric values are included normally as parameter value. A boolean value is written as 'yes' or 'no'. Arrays are enclosed in braces and array values are returned as a single line if the number of elements is zero or one. Otherwise a new line is used for each value. Hashes are also enclosed in braces and the keys and values are processed recursively.

Returns: String The config in Bind9 syntax.

Examples

String value

bind::gencfg({ 'foo' => 'bar' }, 2)

  foo bar;

Numeric value

bind::gencfg({ 'foo' => 42 }, 2)

  foo 42;

Boolean value

bind::gencfg({ 'foo' => true }, 2)

  foo yes;

Array value with zero elements

bind::gencfg({ 'foo' => [] }, 2)

  foo { };

Array value with one element

bind::gencfg({ 'foo' => ['bar'] }, 2)

  foo { bar; };

Array value with multiple elements

bind::gencfg({ 'foo' => ['bar', 'baz'] }, 2)

  foo {
    bar;
    baz;
  };

Hash value

bind::gencfg({ 'foo' => { 'bar' => 'qux', 'quux' => 'baz' } }, 2)

  foo {
    bar  qux;
    quux baz;
  };

config

Data type: Hash[String,Data]

A hash with the configuration items. For each key the name of the key and the value are generated in Bind9 config file syntax. Values may be Booleans, Numbers, Strings, Arrays and other Hashes.

indent

Data type: Integer

The number of space characters to use as indentation for each line. The default value is 0; in this case no indentation is used.

bind::zonefile_path

Type: Puppet Language

Generate the zonefile name from zone

bind::zonefile_path(String $zone)

The bind::zonefile_path function.

Returns: String The relative path and filename where the zonefile should be stored. Example: 'com/example/db.example.com'

zone

Data type: String

The name of the zone for which the path should be returned. Example: 'example.com'

Data types

Bind::AddressMatchList

Type to match allowed values for an address match list

Alias of

Variant[String, Array[String]]

Bind::Auto_dnssec

Type to match allowed values for the auto-dnssec option

Alias of

Enum['allow', 'maintain', 'off']

Bind::DNSSECValidation

Type to match allowed values for the dnssec-validation option

Alias of

Enum['yes', 'no', 'auto']

Bind::Filter_aaaa_on_v4

Type to match allowed values for the filter-aaaa-on-v4 option

Alias of

Enum['no', 'yes', 'break-dnssec']

Bind::Forward

Type to match allowed values for the forward option

Alias of

Enum['first', 'only']

Bind::Key::Algorithm

Type to match allowed values for the key algorithm

Alias of

Enum['hmac-md5', 'hmac-sha1', 'hmac-sha224', 'hmac-sha256', 'hmac-sha384', 'hmac-sha512']

Bind::Notify_secondaries

Type to match allowed values for the notify option

Alias of

Enum['yes', 'no', 'explicit']

Bind::Syslog::Facility

Type to match allowed values for the syslog facility

Alias of

Enum['auth', 'authpriv', 'cron', 'daemon', 'ftp', 'kern', 'local0', 'local1', 'local2', 'local3', 'local4', 'local5', 'local6', 'local7', 'lpr', 'mail', 'news', 'syslog', 'user', 'uucp']

Bind::Syslog::Severity

Type to match allowed values for the syslog severity

Alias of

Enum['critical', 'error', 'warning', 'notice', 'info', 'debug', 'dynamic']

Bind::Zone::Class

Type to match allowed values for the zone class

Alias of

Enum['IN', 'HS', 'CH']

2021-11-30 - Release 0.4.0

Feature

• Add explicit class parameter dnssec_lookaside.
• Add explicit class parameter dnssec_validation.
• The parameters dnssec_enable and dnssec_lookaside are obsolete with Bind 9.16.0 or later. They will be removed from the configuration file when a applicable Bind version is detected.

2021-08-29 - Release 0.3.1

Enhancements

• Allow stdlib 8.0.0

2021-03-04 - Release 0.3.0

Feature

• Implement custom_options parameter to set unusual configuration options that are not implemented in the main class.

2021-01-05 - Release 0.2.0

Features

• Implement purge, prepublish, revoke and retire parameters for dnssec_key type.
• Implement user defined logfile mode for defined type bind::logging::channel_file.

2020-11-02 - Release 0.1.0

Initial release