Skip to content

Latest commit

 

History

History
3105 lines (1864 loc) · 79.1 KB

REFERENCE.md

File metadata and controls

3105 lines (1864 loc) · 79.1 KB
Raw

Reference

Table of Contents

Classes

  • bind: Manage the Bind9 DNS daemon and configuration

Defined types

Public Defined types

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

Data types

Classes

bind

Manage the Bind9 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

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 files (e.g. primary zone files). Example: /var/lib/bind.

Default: operating system specific

cachedir

Data type: Stdlib::Absolutepath

The directory where Bind stores volatile data (e.g. secondary zone files). 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

checkzone_program

Data type: Stdlib::Absolutepath

The full path of the named-checkzone 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::DNSSEC::Validation

Should DNSSEC Validation be enabled.

Default value: 'auto'

empty_zones_enable

Data type: Boolean

Should automatic empty zones be enabled.

Default value: true

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_query_cache

Data type: Bind::AddressMatchList

An array of IP addresses/networks or ACL names that are allowed to use the query cache on 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'

root_mirror_enable

Data type: Boolean

Should a mirror for the root domain "." be installed locally. See RFC 7706 for details.

Default value: false

root_hints_enable

Data type: Boolean

Should a local copy of the list of servers that are authoritative for the root domain "." be included. This is normally not needed since Bind contains an internal list of root nameservers and named will query the servers in the list until an authoritative response is received. Normally this parameter can be left at default.

Default value: false

root_hints_source

Data type: String

The source file to use for the root hints. The default is a file provided by this module.

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

localhost_forward_enable

Data type: Boolean

Should the forward zone for localhost be enabled.

Default value: true

localhost_forward_source

Data type: String

The source file to use for the localhost forward zone. The default is a file provided by this module.

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

localhost_reverse_enable

Data type: Boolean

Should the reverse zone for localhost be enabled.

Default value: true

localhost_reverse_source

Data type: String

The source file to use for the localhost reverse zone. The default is a file provided by this module.

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

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. This parameter is ignored for Bind 9.16.0 or later.

Default value: undef

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 rate 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 rate 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 rate 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 when using rate limiting.

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

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

min_cache_ttl

Data type: Integer

The minimum number of seconds for which the server will cache positive answers.

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

min_ncache_ttl

Data type: Integer

The minimum number of seconds for which the server will cache negative answers.

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

servfail_ttl

Data type: Integer

The number of seconds that SERVFAIL responses caused by DNSSEC validation errors are cached. Can be set to 0 to disable caching.

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

querylog_enable

Data type: Optional[Boolean]

Should the querylog be enabled.

Default value: undef

trust_anchor_telemetry

Data type: Optional[Boolean]

Should the trust anchor telemetry transmission be enable. When enabled, once a day the DNSSEC trust anchors in use will be transmitted to the zon owners. This is enabled by default.

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

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

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

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::dnssec_policy

The policy should either define a Zone-Signing Key (ZSK) and a Key-Signing Key (KSK) or a Combined Signing Key (CSK). A ZSK is used to sign all records except for DNSKEY, CDS and CDNSKEY which are signed using the KSK. Alternatively a CSK can be used to sign all records.

Examples

Create a DNSSEC policy
bind::dnssec_policy { 'standard':
  csk_lifetime  => 'unlimited',
  csk_algorithm => 'ecdsap256sha256',
}

Parameters

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

policy

Data type: String

The name of the policy. This name will be referenced from the zone file.

Default value: $name

nsec3_enable

Data type: Boolean

Should NSEC3 be used instead of NSEC.

Default value: false

nsec3param_iterations

Data type: Optional[Integer]

The number of iterations for NSEC3.

Default value: undef

nsec3param_optout

Data type: Optional[Boolean]

Set optout for NSEC3.

Default value: undef

nsec3param_salt_length

Data type: Optional[Integer]

The length of the salt for NSEC3. The salt provides little value and each DNS zone is always salted using the zone name. Therefore operators are encouraged to use a value of zero for the salt length.

Default value: undef

dnskey_ttl

Data type: Optional[Bind::Duration]

The TTL for DNSKEY resource records in ISO8601 format.

Default value: undef

purge_keys

Data type: Optional[Bind::Duration]

The time in ISO8601 format after which keys will be purged from the configuraton after they have been deleted.

Default value: undef

publish_safety

Data type: Optional[Bind::Duration]

A safety margin in ISO8601 format that is added to the pre-publication interval when rollover times are calculated.

Default value: undef

retire_safety

Data type: Optional[Bind::Duration]

A safety margin in ISO8601 format that is added to the post-publication interval when rollover times are calculated.

Default value: undef

signatures_refresh

Data type: Optional[Bind::Duration]

The time in ISO8601 format after which RRSIG records are refreshed.

Default value: undef

signatures_validity

Data type: Optional[Bind::Duration]

The time in ISO8601 format that an RRSIG record is valid.

Default value: undef

signatures_validity_dnskey

Data type: Optional[Bind::Duration]

The time in ISO8601 format that an DNSKEY record is valid.

Default value: undef

max_zone_ttl

Data type: Optional[Bind::Duration]

The maximum TTL in ISO8601 format allowed for the zone.

Default value: undef

zone_propagation_delay

Data type: Optional[Bind::Duration]

The expected propagation delay in ISO8601 format between updating a zone and all secondary servers catching up with the change.

Default value: undef

parent_ds_ttl

Data type: Optional[Bind::Duration]

The TTL of the DS RRSET of the parent zone in ISO8601 format .

Default value: undef

parent_propagation_delay

Data type: Optional[Bind::Duration]

The expected propagation delay in ISO8601 format between a parent zone update and all secondary servers catching up with the change.

Default value: undef

csk_lifetime

Data type: Optional[Bind::Key::Lifetime]

The lifetime in ISO8601 format of a CSK key.

Default value: undef

csk_algorithm

Data type: Optional[Bind::DNSSEC::Algorithm]

The algorithm used to generate the CSK key.

Default value: undef

csk_keysize

Data type: Optional[Integer]

The keysize used to generate the CSK key.

Default value: undef

ksk_lifetime

Data type: Optional[Bind::Key::Lifetime]

The lifetime in ISO8601 format of a KSK key.

Default value: undef

ksk_algorithm

Data type: Optional[Bind::DNSSEC::Algorithm]

The algorithm used to generate the KSK key.

Default value: undef

ksk_keysize

Data type: Optional[Integer]

The keysize used to generate the KSK key.

Default value: undef

zsk_lifetime

Data type: Optional[Bind::Key::Lifetime]

The lifetime in ISO8601 format of a ZSK key.

Default value: undef

zsk_algorithm

Data type: Optional[Bind::DNSSEC::Algorithm]

The algorithm used to generate the ZSK key.

Default value: undef

zsk_keysize

Data type: Optional[Integer]

The keysize used to generate the ZSK key.

Default value: undef

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

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

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

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

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

Data type: Stdlib::Absolutepath

The filename where the logs are written to.

mode

Data type: Stdlib::Filemode

The file mode of the logfile. The default allows access only for the user and group runnung the daemon.

Default value: '0640'

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

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

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

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

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_hints_enable

Data type: Boolean

Should a local copy of the list of servers that are authoritative for the root domain "." be included. This is normally not needed since Bind contains an internal list of root nameservers and named will query the servers in the list until an authoritative response is received. Normally this parameter can be left at default.

Default value: false

root_mirror_enable

Data type: Boolean

Should a mirror for the root domain "." be installed locally. See RFC 7706 for details.

Default value: false

localhost_forward_enable

Data type: Optional[Boolean]

Should the forward zone for localhost be enabled in this view.

Default value: undef

localhost_reverse_enable

Data type: Optional[Boolean]

Should the reverse zone for localhost be enabled in this view.

Default value: undef

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'

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

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

comment

Data type: Optional[String]

A comment to add to the zone file.

Default value: undef

zone

Data type: String

The name of the zone.

Default value: $name

class

Data type: Bind::Zone::Class

The zone class.

Default value: 'IN'

order

Data type: String

Zones are ordered by this parameter value in the zone file.

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:

file

Data type: String

The filename of the hint file.

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

comment

Data type: Optional[String]

A comment to add to the zone file.

Default value: undef

zone

Data type: String

The name of the zone.

Default value: $name

class

Data type: Bind::Zone::Class

The zone class.

Default value: 'IN'

order

Data type: String

Zones are ordered by this parameter value in the zone file.

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:

in_view

Data type: String

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

view

Data type: String

The name of the view that should include this zone.

comment

Data type: Optional[String]

A comment to add to the zone file.

Default value: undef

zone

Data type: String

The name of the zone.

Default value: $name

class

Data type: Bind::Zone::Class

The zone class.

Default value: 'IN'

order

Data type: String

Zones are ordered by this parameter value in the zone file.

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:

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

comment

Data type: Optional[String]

A comment to add to the zone file.

Default value: undef

zone

Data type: String

The name of the zone.

Default value: $name

class

Data type: Bind::Zone::Class

The zone class.

Default value: 'IN'

order

Data type: String

Zones are ordered by this parameter value in the zone file.

Default value: '50'

bind::zone::primary

The parameters source or content can be used to have Puppet manage the content of the zone file. No content is managed if both parameters are left undefined. For a dynamic updatable zone the parameters source and content are only applied if the zone file does not yet exist. This can be used to deploy a zone file template on the first Puppet run and have Bind manage the content subsequently.

Examples

Create a primary zone
bind::zone::primary { 'example.com':
  source => 'puppet:///modules/profile/example.com.zone',
}
Use DNSSEC signing for a primary zone using a DNSSEC policy
bind::zone::primary { 'example.com':
  dnssec_enable  => true,
  dnssec_policy  => 'standard',
  inline_signing => true,
  source         => 'puppet:///modules/profile/example.com.zone',
}
Create a dynamic updatable zone with an initial zone file
bind::zone::primary { '_acme-challenge.example.com':
  update_policy => ['grant certbot name _acme-challenge.example.com. txt'],
  source        => 'puppet:///modules/profile/acme-template.zone',
}

Parameters

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

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: []

update_policy

Data type: Variant[Enum['local'],Array[String]]

Enable dynamic updates for the zone and define the update policy. This can either be the string local or an array of strings. Using the string local enables an automatically created session key local-ddns stored on the server. Otherwise the array should contain individual grant or deny rules.

The zone file content can not be managed by Puppet for a dynamic zone. If the parameters source or content are set, the zone file will only be created by Puppet initially if it does not exist. An existing zone file will not be overwritten by Puppet.

Default value: []

dnssec_enable

Data type: Optional[Boolean]

Enable DNSSEC for the zone. This parameter is ignored for Bind 9.16.0 or later.

Default value: undef

dnssec_dnskey_kskonly

Data type: Optional[Boolean]

Should only key-signing keys be used to to sign the DNSKEY, CDNSKEY and CDSRRsets.

Default value: undef

dnssec_secure_to_insecure

Data type: Optional[Boolean]

Should the zone be allowed to got from signed to unsinged.

Default value: undef

inline_signing

Data type: Optional[Boolean]

Enable inline signing for the zone.

Default value: undef

dnssec_policy

Data type: Optional[String]

The name of the DNSSEC policy to use for this zone. The policy must be created using the bind::dnssec_policy defined type.

Default value: undef

dnskey_sig_validity

Data type: Optional[Integer]

The number of days after which the signatures for generated DNSKEY RRsets expire.

Default value: undef

dnssec_loadkeys_interval

Data type: Optional[Integer]

The time interval after which key are checked if auto_dnssec is set to maintain. The value is in minutes.

Default value: undef

dnssec_update_mode

Data type: Optional[Bind::DNSSEC::Updatemode]

Should RRSIG records be regenerated automatically (mode maintain) or not (mode no-resign) for a zone which allows dynamic updates.

Default value: undef

auto_dnssec

Data type: Optional[Bind::Auto_dnssec]

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

Default value: undef

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

file

Data type: Optional[String]

The name of the user managed zone file on the DNS server. The file must exist and have the correct format. Puppet does not manage the content or the file permissions of this file.

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

comment

Data type: Optional[String]

A comment to add to the zone file.

Default value: undef

zone

Data type: String

The name of the zone.

Default value: $name

class

Data type: Bind::Zone::Class

The zone class.

Default value: 'IN'

order

Data type: String

Zones are ordered by this parameter value in the zone file.

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

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

comment

Data type: Optional[String]

A comment to add to the zone file.

Default value: undef

zone

Data type: String

The name of the zone.

Default value: $name

class

Data type: Bind::Zone::Class

The zone class.

Default value: 'IN'

order

Data type: String

Zones are ordered by this parameter value in the zone file.

Default value: '30'

Resource types

dnssec_key

Notice: Automatic key rollover using this type is not thoroughly tested. Use bind::dnssec_policy to define a DNSSEC policy (available with Bind 9.16) and let Bind handle the heavy lifting instead of Puppet.

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

Key-2 is published with a prepublication interval while key-1 is still active. The activation time of key-2 matches the deactivation time of key-1. Key-1 changes state to retired when it is deactivated and is deleted eventually. The cycle continues with additional keys.

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

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::DNSSEC::Algorithm

Type to match allowed values for DNSSEC key algorithms

Alias of Enum['dsa', 'eccgost', 'ecdsap256sha256', 'ecdsap384sha384', 'ed25519', 'ed448', 'nsec3dsa', 'nsec3rsasha1', 'rsamd5', 'rsasha1', 'rsasha256', 'rsasha512']

Bind::DNSSEC::Updatemode

Type to match allowed values for the dnssec-update-mode option

Alias of Enum['maintain', 'no-resign']

Bind::DNSSEC::Validation

Type to match allowed values for the dnssec-validation option

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

Bind::Duration

Type to match ISO8601 durations

Alias of Pattern[/^(-?)P(?=\d|T\d)(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)([DW]))?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/]

Bind::Filter_aaaa_on_v4

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

Alias of Optional[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::Key::Lifetime

Type to match allowed values for the key lifetime

Alias of Pattern[/^(-?)P(?=\d|T\d)(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)([DW]))?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/, /\Aunlimited\Z/]

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