Skip to content

Latest commit

 

History

History
936 lines (578 loc) · 23.7 KB

REFERENCE.md

File metadata and controls

936 lines (578 loc) · 23.7 KB
Raw

Reference

Table of Contents

Classes

Public Classes

  • bind: Manages the BIND domain name server and DNS zones

Private Classes

  • bind::config: Manages BIND configuration
  • bind::install: Manages BIND installation
  • bind::service: Manages BIND service

Defined types

  • bind::key: Create TSIG key for zone updates in the configuration file for BIND
  • bind::zone: A DNS zone

Resource types

Functions

Public Functions

Private Functions

  • bind::service_name: Determines the name of the BIND service

Data types

Classes

bind

Manages the BIND domain name server and DNS zones

Examples

Caching nameserver with default configuration
include bind

Parameters

The following parameters are available in the bind class:

authoritative

Data type: Boolean

Whether to enable features needed for authoritative server operation.

Default value: false

config_dir

Data type: Stdlib::Absolutepath

Directory for BIND configuration files.

Default value: '/etc/bind'

default_options

Data type: Bind::Options

Default BIND options loaded from Hiera data in this module's data directory. Merged with, and overridden by, the options parameter. You'll generally want to use the options parameter and leave default_options alone.

Default value: { 'directory' => '/var/cache/bind', }

default_zones

Data type: Boolean

Whether to include the default zones in the BIND configuration.

Default value: true

dev_packages

Data type: Array[String[1]]

List of BIND development packages.

Default value: ['bind9-dev']

doc_packages

Data type: Array[String[1]]

List of BIND documentation packages.

Default value: ['bind9-doc']

utils_packages

Data type: Array[String[1]]

List of BIND utilities packages.

Default value: ['bind9-dnsutils']

includes

Data type: Optional[Variant[Array[Bind::Include], Bind::Include]]

Additional configuration files to include in the BIND configuration using the include statement.

Default value: undef

dev_packages_ensure

Data type: Optional[String[1]]

The ensure value for the BIND development packages (libraries and header files).

Default value: undef

doc_packages_ensure

Data type: Optional[String[1]]

The ensure value for the BIND documentation packages.

Default value: undef

utils_packages_ensure

Data type: String[1]

The ensure value for the BIND utilities packages.

Default value: 'installed'

logging

Data type: Optional[Bind::Logging]

Configuration of the logging statement.

Default value: undef

keys

Data type: Hash

Hash for creating Bind::Key resources.

Default value: {}

options

Data type: Optional[Bind::Options]

Configuration of the options statement. Merged with, and overrides, the default_options parameter.

Default value: undef

package_manage

Data type: Boolean

Whether to have this module manage the BIND package.

Default value: true

service_manage

Data type: Boolean

Whether to have this module manage the BIND service.

Default value: true

package_backport

Data type: Boolean

Whether to install the BIND package from Debian backports.

Default value: false

package_name

Data type: String[1]

The name of the BIND package.

Default value: 'bind9'

package_ensure

Data type: String[1]

The ensure parameter for the BIND package.

Default value: installed

resolvconf_package_name

Data type: String[1]

The name of the resolvconf package to use if resolvconf_service_enable is true.

Default value: 'openresolv'

resolvconf_service_enable

Data type: Boolean

Whether to enable the named-resolvconf service so that localhost's BIND resolver is used in /etc/resolv.conf.

Default value: false

root_hint_zone

Data type: Boolean

Whether to include the root zone "." in the BIND configuration with type hint.

Default value: true

service_config_file

Data type: Stdlib::Absolutepath

The path to the BIND config file.

Default value: extlib::path_join([$config_dir, 'named.conf'])

service_enable

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

The enable parameter for the BIND service.

Default value: true

service_ensure

Data type: Stdlib::Ensure::Service

The ensure parameter for the BIND service.

Default value: running

service_group

Data type: String[1]

The primary group of $service_user. Used for directory permissions.

Default value: $service_user

service_name

Data type: String[1]

The name of the BIND service.

Default value: 'named'

service_user

Data type: String[1]

The user to run BIND as (for the -u command line option).

Default value: 'bind'

service_options

Data type: Optional[String[1]]

Command line options for the BIND service.

Default value: undef

zones

Data type: Hash

Hash for creating Bind::Zone resources.

Default value: {}

zone_default_expire

Data type: String[1]

The default SOA expire time, set per a RIPE recommendation (same as with all of the default time values). Can be overridden by individual zones by providing a SOA record in the zone's hash of the $zones parameter. Reference: RFC 1035

Default value: '1000h'

zone_default_mname

Data type: String[1]

The default SOA MNAME. That is, the domain name of the primary name server for the zone. Can be overridden by individual zones by providing a SOA record in the zone's hash of the $zones parameter. Reference: RFC 1035

Default value: $facts['networking']['hostname']

zone_default_negative_caching_ttl

Data type: String[1]

The default negative caching TTL, the last field of the SOA record. Can be overridden by individual zones by providing a SOA record in the zone's hash of the $zones parameter. Reference: RFC 2308

Default value: '1h'

zone_default_refresh

Data type: String[1]

The default SOA refresh time. Can be overridden by individual zones by providing a SOA record in the zone's hash of the $zones parameter. Reference: RFC 1035

Default value: '24h'

zone_default_retry

Data type: String[1]

The default SOA retry time. Can be overridden by individual zones by providing a SOA record in the zone's hash of the $zones parameter. Reference: RFC 1035

Default value: '2h'

zone_default_rname

Data type: String[1]

The default SOA RNAME. That is, the domain name-formatted email address of the person responsible for the zone. Can be overridden by individual zones by providing a SOA record in the zone's hash of the $zones parameter. Reference: RFC 1035

Default value: 'hostmaster'

zone_default_serial

Data type: Integer[0]

The default initial serial number for the zone. Can be overridden by individual zones by providing a SOA record in the zone's hash of the $zones parameter.

Default value: 1

zone_default_ttl

Data type: String[1]

The default zone-wide TTL. This value is used in the zone's $TTL directive at the start of the zone. Individual zones can override this default with the ttl key in their configuration hashes in the $zones parameter. Also, individual resource records can override this value with the ttl key in their hashes. Reference: RFC 2308

Default value: '2d'

Defined types

bind::key

Create TSIG key for zone updates in the configuration file for BIND

Examples

Add a TSIG key to the nameserver
bind::key { 'tsig-client':
  algorithm => 'hmac-sha512',
  secret    => 'secret-key-data',
}

Parameters

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

algorithm

Data type: Enum['hmac-sha256', 'hmac-sha384', 'hmac-sha512']

Defines the algorithm which was used to generate the key data. For security reasons just allow algorithms hmac-sha256 and above: https://www.rfc-editor.org/rfc/rfc8945.html#name-algorithms-and-identifiers

secret

Data type: String[44]

Provide the secret data of the TSIG key, generated using tsig-keygen.

bind::zone

A DNS zone

Examples

Basic usage
bind::zone { 'example.com.': }

Parameters

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

zone_name

Data type: Pattern[/\.$/]

The name of the zone.

Default value: $title

allow_transfer

Data type: Optional[Array[Variant[Stdlib::Host, Stdlib::IP::Address]]]

Which hosts are allowed to receive zone transfers from the server. https://bind9.readthedocs.io/en/latest/reference.html#allow-transfer-access

Default value: undef

allow_update

Data type: Optional[Array[Variant[Stdlib::Host, Stdlib::IP::Address]]]

Which hosts are allowed to submit Dynamic DNS updates to the zone.

Default value: undef

also_notify

Data type: Optional[Array[Variant[Stdlib::Host, Stdlib::IP::Address]]]

list of IP addresses of name servers that are also sent NOTIFY messages whenever a fresh copy of the zone is loaded, in addition to the servers listed in the zone’s NS records.

Default value: undef

auto_dnssec

Data type: Optional[Enum['allow', 'maintain', 'off']]

The automatic DNSSEC key management mode.

Default value: undef

class

Data type: Optional[Enum['IN', 'HS', 'hesiod', 'CHAOS']]

DNS class. Defaults to 'IN', for Internet. https://bind9.readthedocs.io/en/latest/reference.html#class

Default value: undef

file

Data type: Optional[String[1]]

The zone's filename.

Default value: undef

forward

Data type: Optional[Enum['first', 'only']]

This option is only meaningful if the zone has a forwarders list. The 'only' value causes the lookup to fail after trying the forwarders and getting no answer, while 'first' allows a normal lookup to be tried. https://bind9.readthedocs.io/en/latest/reference.html#forwarding

Default value: undef

forwarders

Data type: Optional[Array[Stdlib::Host]]

Hosts to which queries are forwarded. https://bind9.readthedocs.io/en/latest/reference.html#forwarding

Default value: undef

in_view

Data type: Optional[String[1]]

Allows for referencing the zone in another view.

Default value: undef

inline_signing

Data type: Optional[Variant[Boolean, Stdlib::Yes_no]]

Allows BIND to automatically sign zones.

Default value: undef

key_directory

Data type: Optional[String[1]]

The directory where the public and private DNSSEC key files should be found when performing a dynamic update of secure zones, if different than the current working directory.

Default value: undef

manage

Data type: Boolean

Whether to manage the contents of this zone with Puppet. If false, only manages the configuration of the zone in named.conf. If true, creates and manages the zone file and resource records of the zone.

Default value: false

masters

Data type: Optional[Array[Stdlib::Host]]

Synonym for primaries.

Default value: undef

primaries

Data type: Optional[Array[Stdlib::Host]]

Defines a named list of servers for inclusion in stub and secondary zones' primaries or also-notify lists.

Default value: undef

purge

Data type: Boolean

Whether to purge unmanaged resource records from the zone.

Default value: false

resource_records

Data type: Hash

Hash for creating resource_record resources.

Default value: {}

serial_update_method

Data type: Optional[Enum['date', 'increment', 'unixtime']]

Method for incrementing the zone's serial number.

Default value: undef

ttl

Data type: Optional[String[1]]

The value for the $TTL directive, which sets the default resource record TTL for the zone.

Default value: undef

type

Data type: Optional[Enum[ 'primary', 'master', 'secondary', 'slave', 'mirror', 'hint', 'stub', 'static-stub', 'forward', 'redirect', 'delegation-only', ]]

The zone type. https://bind9.readthedocs.io/en/latest/reference.html#zone-types

Default value: undef

update_policy

Data type: Optional[Array[Bind::ZoneConfig::UpdatePolicy]]

The update-policy. https://bind9.readthedocs.io/en/latest/reference.html#dynamic-update-policies

Default value: undef

Resource types

resource_record

This type provides Puppet with the capabilities to manage DNS resource records.

Autorequires: If Puppet is managing the zone that this resource record belongs to, the resource record will autorequire the zone.

Examples

AAAA record in the example.com. zone
resource_record { 'foo.example.com.':
  ensure => 'present',
  type   => 'AAAA',
  data   => '2001:db8::1',
}

Properties

The following properties are available in the resource_record type.

data

Data type: String

The data for the resource record.

ensure

Data type: Enum[present, absent]

Whether this resource record should be present or absent on the target system.

Default value: present

record

Data type: String

The name of the resource record, also known as the owner or label.

ttl

Data type: Optional[String]

The TTL for the resource record.

type

Data type: String

The type of the resource record.

zone

Data type: String

The zone the resource record belongs to.

Functions

Data types

Bind::Include

Reference: https://bind9.readthedocs.io/en/latest/reference.html#include-statement-grammar

Alias of

Stdlib::Absolutepath

Bind::Logging

Reference: https://bind9.readthedocs.io/en/latest/reference.html#logging-statement-grammar

Alias of

Struct[{
  Optional['channels'] => Hash[Bind::Logging::ChannelName, Bind::Logging::ChannelPhrase],
  Optional['categories'] => Hash[Bind::Logging::Category, Bind::Logging::CategoryPhrase],
}]

Bind::Logging::Category

Reference: https://bind9.readthedocs.io/en/latest/reference.html#the-category-phrase

Alias of

Enum['client', 'cname', 'config', 'database', 'default', 'delegation-only', 'dispatch', 'dnssec', 'dnstap', 'edns-disabled', 'general', 'lame-servers', 'network', 'notify', 'nsid', 'queries', 'query-errors', 'rate-limit', 'resolver', 'rpz', 'rpz-passthru', 'security', 'serve-stale', 'spill', 'trust-anchor-telemetry', 'unmatched', 'update', 'update-security', 'xfer-in', 'xfer-out', 'zoneload']

Bind::Logging::CategoryPhrase

Reference: https://bind9.readthedocs.io/en/latest/reference.html#the-category-phrase

Alias of

Struct[{
  Optional['channels'] => Array[String[1]],
}]

Bind::Logging::ChannelName

Reference: https://bind9.readthedocs.io/en/latest/reference.html#the-channel-phrase

Alias of

Pattern[/\A\w+\Z/]

Bind::Logging::ChannelPhrase

Reference: https://bind9.readthedocs.io/en/latest/reference.html#the-channel-phrase

Alias of

Variant[Enum['null', 'stderr', 'syslog'], Struct[{
  Optional['buffered'] => Boolean,
  Optional['file'] => Struct[{
    'name' => String[1],
    Optional['versions'] => Variant[Enum['unlimited'], Integer[1]],
    Optional['size'] => Bind::Size,
    Optional['suffix'] => Enum['increment', 'timestamp'],
  }],
  Optional['print-category'] => Boolean,
  Optional['print-severity'] => Boolean,
  Optional['print-time'] => Variant[Boolean, Stdlib::Yes_no, Enum['iso8601', 'iso8601-utc', 'local']],
  Optional['severity'] => String[1],
  Optional['syslog'] => Stdlib::Syslogfacility,
}]]

Bind::Options

Reference: https://bind9.readthedocs.io/en/latest/reference.html#options-statement-grammar

Alias of

Struct[{
  Optional['allow-transfer'] => Array[Variant[Stdlib::Host, Stdlib::IP::Address]],
  Optional['allow-update'] => Array[Variant[Stdlib::Host, Stdlib::IP::Address]],
  Optional['allow-query'] => Array[Variant[Stdlib::Host, Stdlib::IP::Address]],
  Optional['also-notify'] => Array[Variant[Stdlib::Host, Stdlib::IP::Address]],
  Optional['auto-dnssec'] => Enum['allow', 'maintain', 'off'],
  Optional['directory'] => Stdlib::Absolutepath,
  Optional['inline-signing'] => Variant[Boolean, Stdlib::Yes_no],
  Optional['key-directory'] => String[1],
  Optional['serial-update-method'] => Enum['date', 'increment', 'unixtime'],
  Optional['zone-statistics'] => Variant[Boolean, Stdlib::Yes_no, Enum['full', 'terse', 'none']],
}]

Bind::Size

Reference: size_spec under https://bind9.readthedocs.io/en/latest/reference.html#configuration-file-elements

Alias of

Variant[Enum['unlimited', 'default'], Integer[0], Pattern[/\A\d+(?i:k|m|g)\Z/]]

Bind::ZoneConfig::UpdatePolicy

Reference: https://bind9.readthedocs.io/en/latest/reference.html#dynamic-update-policies

Alias of

Variant[Enum['local'], Bind::ZoneConfig::UpdatePolicy::Rule]

Bind::ZoneConfig::UpdatePolicy::Rule

Reference: https://bind9.readthedocs.io/en/latest/reference.html#dynamic-update-policies

Alias of

Struct[{
  'permission' => Enum['deny', 'grant'],
  'identity'   => String[1],
  'ruletype'   => Enum[
    'name',
    'subdomain',
    'zonesub',
    'wildcard',
    'self',
    'selfsub',
    'selfwild',
    'ms-self',
    'ms-selfsub',
    'ms-subdomain',
    'krb5-self',
    'krb5-selfsub',
    'krb5-subdomain',
    'tcp-self',
    '6to4-self',
    'external',
  ],
  Optional['name'] => String[1],
  Optional['types'] => String[1],
}]