Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

Select Badges

Select Supported Platforms

Select Status

RSS

bind (42) Versions 2.1.0

Installs/Configures ISC BIND

Policyfile
Berkshelf
Knife
cookbook 'bind', '= 2.1.0', :supermarket
cookbook 'bind', '= 2.1.0'
knife supermarket install bind
knife supermarket download bind
README
Dependencies
Changelog
Quality 71%

BIND Build Status

Description

A chef cookbook to manage BIND servers and zones.

Contents

Requirements

This release migrates to using custom resources. Thus we require a more recent
version of chef (12.16 or above). To continue using this cookbook on older
versions please stick with the 1.x versions.

This cookbook now follows the library pattern. To use the cookbook effectively
you'll need a wrapper cookbook that has the resources listed.

A default recipe is provided. It only provides a basic recursive name server.

Supported Operating Systems:

  • CentOS/RHEL 6.9
  • CentOS/RHEL 7.3
  • Debian 8.9
  • Debian 9.2
  • Ubuntu 14.04
  • Ubuntu 16.04

Attributes

Most attributes have been removed in favour of custom resources.
See the MIGRATION.md document.

Usage

Using custom resources leads to a quite flexible configuration, but requires
a little bit more work in a wrapper cookbook to use. The following examples
are presented here:

  • Internal recursive nameserver
  • Authoritative primary nameserver
  • Authoritative secondary nameserver

Internal recursive nameserver

bind_service 'default' do
  action [:create, :start]
end

bind_config 'default' do
  ipv6_listen true
  options [
    'check-names slave ignore',
    'multi-master yes',
    'provide-ixfr yes',
    'recursive-clients 10000',
    'request-ixfr yes',
    'allow-notify { acl-dns-masters; acl-dns-slaves; }',
    'allow-query { example-lan; localhost; }',
    'allow-query-cache { example-lan; localhost; }',
    'allow-recursion { example-lan; localhost; }',
    'allow-transfer { acl-dns-masters; acl-dns-slaves; }',
    'allow-update-forwarding { any; }',
  ]
end

bind_acl 'acl-dns-masters' do
  entries [
    '! 10.1.1.1',
    '10/8'
  ]
end

bind_acl 'acl-dns-slaves' do
  entries [
    'acl-dns-masters'
  ]
end

bind_acl 'example-lan' do
  entries [
    '10.2/16',
    '10.3.2/24',
    '10.4.3.2'
  ]
end

Authoritative primary nameserver

There are two ways to create primary zone files with this cookbook. The first
is by providing a complete zone file that is placed in the correct directory
(and is added to the nameserver configuration by using the
bind_primary_zone resource). The second way is by using the
bind_primary_zone_template resource. To use this you need to provide
an array of hashes containing the records you want to be added to the zone file.

The following example has both options shown. In a wrapper cookbook add the code below with appropriate modifications.

You'll need to configure the ACL entries (and names) for the example-lan and
acl-dns-masters ACLs for your local configuration.

You will also need to arrange for the zone files to be placed in the configured
location (which is OS dependent by default).

Resource style:

bind_service 'default' do
  action [:create, :start]
end

bind_config 'default' do
  ipv6_listen true
  options [
    'recursion no',
    'allow-query { any; }',
    'allow-transfer { external-private-interfaces; external-dns; }',
    'allow-notify { external-private-interfaces; external-dns; localhost; }',
    'listen-on-v6 { any; }'
  ]
end

bind_acl 'external-private-interfaces' do
  entries [
  ]
end

bind_acl 'external-dns' do
  entries [
  ]
end

cookbook_file '/var/named/primary/db.example.com' do
  owner 'named'
  group 'named'
  mode '0440'
  action :create
end

bind_primary_zone 'example.com'

bind_primary_zone_template 'example.org' do
  soa serial: 100
  default_ttl 200
  records [
    { type: 'NS', rdata: 'ns1.example.org.' },
    { type: 'NS', rdata: 'ns2.example.org.' },
    { type: 'MX', rdata: '10 mx1.example.org.' },
    { type: 'MX', rdata: '20 mx1.example.org.' },
    { owner: 'www', type: 'A', ttl: 20, rdata: '10.5.0.1' },
    { owner: 'ns1', type: 'A', ttl: 20, rdata: '10.5.1.1' },
    { owner: 'ns2', type: 'A', ttl: 20, rdata: '10.5.2.1' },
    { owner: 'mx1', type: 'A', ttl: 20, rdata: '10.5.1.100' },
    { owner: 'mx2', type: 'A', ttl: 20, rdata: '10.5.2.100' },
  ]

Authoritative secondary nameserver

In a wrapper cookbook add the code below with appropriate modifications.

You'll need to configure the ACL entries (and names) for the example-lan and
acl-dns-masters ACLs for your local configuration.

bind_service 'default' do
  action [:create, :start]
end

bind_config 'default' do
  ipv6_listen true
  options [
    'recursion no',
    'allow-query { any; }',
    'allow-transfer { external-private-interfaces; external-dns; }',
    'allow-notify { external-private-interfaces; external-dns; localhost; }',
    'listen-on-v6 { any; }'
  ]
end

bind_acl 'acl-dns-masters' do
  entries [
    '! 10.1.1.1',
    '10/8'
  ]
end

bind_acl 'acl-dns-slaves' do
  entries [
    'acl-dns-masters'
  ]
end

bind_acl 'example-lan' do
  entries [
    '10.2/16',
    '10.3.2/24',
    '10.4.3.2'
  ]
end

bind_secondary_zone 'example.com' do
  primaries %w(192.0.2.10 192.0.2.11 192.0.2.12)
end

bind_secondary_zone 'example.org' do
  primaries %w(192.0.2.10 192.0.2.11 192.0.2.12)
end

Nameserver in chroot mode

The bind_service and bind_config resources can accept a boolean true or false for chroot, declaring whether or not to install the BIND server in a chroot manner.
If one provider declares this value, the other must match or the converge will fail. Currently all supported platforms except Ubuntu 16.04 LTS are supported with chrooted configuration.
By default, this is set to false

bind_service 'default' do
  chroot true
  action :create
end

bind_config 'default' do
  chroot true
  options [
    'recursion no',
    'allow-transfer { internal-dns; }'
  ]
end

Available Custom Resources

bind_service

The bind_service resource installs the pre-requisites for the service to run.

The :create action installs packages and creates appropriate configuration
directories. It does not attempt to create a working configuration.

The :start action ensures that the name server will be started at the end of
the chef run and will be started automatically on boot.

The :restart wil immediately restart the name server.

Example

bind_service 'default' do
  action [:create, :start]
end

Properties

The following properties are supported:

  • sysconfdir - The system configuration directory where the named config will be located. The default is platform specific. Usually /etc/named or /etc/bind
  • vardir - The location for zone files and other data. The default is platform specific, usually /var/named or /var/cache/bind.
  • chroot - Boolean decleration to setup a chrooted nameserver installation. Defaults to false
  • chroot_dir - Define the chrooted base directory. Affects sysconfdir and vardir and is platform specific.
  • package_name - The package, or array of packages, needed to install the nameserver. Default is platform specific, usually includes bind and associated utility packages.
  • run_user - The user that the name server will run as. Defaults to named.
  • run_group - The groups that the name server will run as. Defaults to named.
  • service_name - The name of the service installed by the system packages. Defaults to a platform specific value.

bind_config

The bind_config resource creates the configuration files for the name server.

The only available action is :create which will create the default
configuration files (including RFC1912 zones), configure an rndc key, and
set any query logging parameters required.

Examples

bind_config 'default'

bind_config 'default' do
  ipv6_listen false

  options [
    'recursion no',
    'allow-transfer { external-dns; }'
  ]
end

bind_config 'default' do
  statistics_channel address: 127.0.0.1, port: 8090

  query_log '/var/log/named/query.log'
  query_log_versions 5
  query_log_max_size '10m'
  query_log_options [
    'print-time yes'
  ]
end

Properties

  • conf_file - The desired full path to the main configuration file. Platform specific default.
  • options_file - The desired full path to the configuration file containing options. Platform specific default.
  • chroot - Configuring a chrooted nameserver. Defaults to false
  • chroot_dir - Define the chrooted base directory. Platform specific default.
  • ipv6_listen - Enables listening on IPv6 instances. Can be true or false. Defaults to true.
  • options - Array of option strings. Each option should be a valid BIND option minus the trailing semicolon. Defaults to an empty array.
  • query_log - If provided will turn on general query logging. Should be the path to the desired log file. Default is empty and thus disabled. This will likely move to a separate resource in the future.
  • query_log_max_size - Maximum size of query log before rotation. Defaults to '1m'.
  • query_log_versions - Number of rotated query logs to keep on the system. Defaults to 2.
  • query_log_options - Array of additional query log options. Defaults to empty array.
  • statistics_channel - Presence turns on the statistics channel. Should be a hash containing :address and :port to configure the location where the statistics channel will listen on. This will likely move to a separate resource in the future.

bind_primary_zone

The bind_primary_zone resource will copy a zone file from your current
cookbook into the correct directory and add the zone as a master zone to your
BIND configuration. The file should be named for the zone you wish to configure.
For example to configure example.com the file should be in
files/default/example.com

Examples

bind_primary_zone 'example.com'

bind_primary_zone 'example.org' do
  options [
    'allow-transfer { none; }'
  ]
end

Properties

  • options - Array of option strings. Each option should be a valid BIND option minus the trailing semicolon. Defaults to an empty array.

bind_primary_zone_template

The bind_primary_zone_template resource will create a zone file from a
template and list of desired resources.

Examples

bind_primary_zone_template 'example.com' do
  soa serial: 100, minimum: 3600
  records [
    { type: 'NS', rdata: 'ns1.example.com.' },
    { owner: 'ns1', type: 'A', rdata: '10.0.1.1' }
  ]
end

Properties

  • soa - Hash of SOA entries. Available keys are:
    • :serial - The serial number of the zone. Defaults to '1'. If this zone has secondary servers configured then you will need to either manually manage this and update when the record set changes, or use the manage_serial property.
    • :mname - Domain name of the primary name server serving this zone. Defaults to 'localhost.'
    • :rname - The email address of the "Responsible Person" for this zone with the @-sign replaced by a .. Defaults to hostmaster.localhost.
    • :refresh - The period that a secondary name server will wait between checking if the zone file has been updated on the master. Defaults to '1w'.
    • :retry - The period that a secondary name server will attempt to retry checking a zone file if the initial attempt fails. Defaults to '15m'.
    • :expire - The length of time that a zone will be considered invalid if the primary name server is unavailable. Defaults to '52w'.
    • :minimum - The length of time that a name server will cache a negative (NXDOMAIN) result. Defaults to 30 seconds.
  • default_ttl - The default time to live for any records which do not have an explicitly configured TTL.
  • records - An array of hashes describing each desired record. Possible keys are:
    • :owner - The name to be looked up.
    • :type - The record type; examples include: 'NS', 'MX', 'A', 'AAAA'.
    • :ttl - A non-default TTL. If not present will use the default TTL of the zone.
    • :rdata - The value of the record. Freeform string that depends on the type for structure.
  • manage_serial - A boolean indicating if we should manage the serial number. Defaults to false. When true persists the current serial number and a digest of the current zone contents into the node object. If the records change the serial number will be incremented. The default serial number used is the value of soa[:serial].
  • template_cookbook - The cookbook to locate the primary zone template file. Defaults to 'bind'. You can override this to change the structure of the zone file.
  • template_name - The name of the primary zone template file within a cookbook. Defaults to 'primary_zone.erb'

A note on serial numbers

Serial numbers are primarily used by the DNS to discover if a zone has changed
and thus trigger a zone transfer by a secondary server. If you are managing all
of the authoritative servers for a zone with chef then you do not need to change
serial numbers when updating a zone. In this instance you can set a simple
static serial number ('1' is used by default and is just fine).

On the other hand, if you have non-chef managed secondary servers then you will
need to increment the serial number whenever the record set changes. This can be
done in two different ways: manually (where you control the serial number set
and will increment it each time the record set changes), or using the
manage_serial property.

If you use the manage_serial property then each time the record set changes
the serial number will be incremented. Providing a serial number in the soa
property will be used as a default value for the serial number. When enabled
this property will cause the cookbook to store the serial number and a hash of
the record set in the host's node object. If you destroy the node object then
this will result in the serial number being reset to the default value in the
soa property. Finally, ensure that you only have a single server using the
manage_serial property. Otherwise you may end up with different name servers
with different serial numbers. In this case, set up a single node as the
primary server and use the bind_secondary_zone on all the other authoritative
servers to pull the zone from that designated primary server.

bind_secondary_zone

The bind_secondary_zone resource will configure a zone to be pulled from a
primary name server.

Examples

bind_secondary_zone 'example.com' do
  primaries [
    '10.1.1.1',
    '10.2.2.2'
  ]
end

bind_secondary_zone 'example.org' do
  primaries [
    '10.1.1.1',
    '10.2.2.2'
  ]

  options [
    'zone-statistics full'
  ]
end

Properties

  • primaries - An array of IP addresses used as the upstream master for this zone. Is mandatory and has no default.
  • options - Array of option strings. Each option should be a valid BIND option minus the trailing semicolon. Defaults to an empty array.

bind_forwarder

The bind_forwarder resource will configure a forwarding only zone.

Examples

bind_forwarder 'example.com' do
  forwarders [
    '10.1.1.1',
    '10.2.2.2'
  ]
end

bind_forwarder 'example.org' do
  forward 'first'
  forwarders ['10.0.1.1', '10.2.1.1']
end

Properties

  • forwarders - An array of IP addresses to which requests for this zone will be forwarded to. Defaults to an empty list. (Which if set will disable forwarding for this zone if globally configured).
  • forward - Set to 'first' if you wish to try a regular lookup if forwaridng fails. 'only' will cause the query to fail if forwarding fails. Default is 'only'.

bind_acl

The bind_acl resource allows you to create a named ACL list within the
BIND configuration.

Examples

bind_acl 'google-dns-servers' do
  entries [
    '8.8.8.8',
    '8.8.4.4'
  ]
end

bind_acl 'internal-dns' do
  entries [
    '! 10.1.1.1',
    '10/8'
  ]
end

bind_acl 'tsig_key' do
  entries [
    'key "internal-key"',
  ]
end

Properties

  • entries - An array of strings representing each acl entry.

Each entry should be a valid BIND address match list. This means it can be:

  • an IP address
  • an IP prefix
  • a key id
  • the name of a different address march list from another acl statement
  • a nested address match list enclosed in braces

Predefined ACLs (from BIND itself) which do not need additional configuration are: any, none, localhost, and localnets.

bind_key

The bind_key resource adds a shared secret key (for either TSIG or
the command channel) to the configuration.

bind_key 'dns-update-key' do
  algorithm 'hmac-sha256'
  secret 'this_is_the_secret_key'
end

Properties

  • algorithm - The algorithm that the secret key was generated from.
  • secret - The secret key

bind_server

The bind_server resource allows specific options to be configured for a
particular upstream name server.

Examples

bind_server '10.1.1.1' do
  options [
    'bogus yes'
  ]
end

Properties

  • options - Array of option strings. Each option should be a valid BIND option minus the trailing semicolon. Defaults to an empty array.

License and Author

  • Copyright: 2011 Eric G. Wolfe
  • Copyright: 2017 David Bruce

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

bind changelog

v2.1.0

  • Add support for chrooted install
  • Chroot Supported platforms: CentOS/RedHat 6.x+, Debian 8.x+, Ubuntu 14.04 LTS
  • Chroot Incompatible platforms: Ubuntu 16.04 LTS ubuntu/+source/bind9/+bug/1630025
  • Updated rndc call to be compliant with current auto-configuration standards
  • Updated file paths using ::File,join() method
  • Delayed all template creation to avoid file busy conflicts
  • Added .kitchen.dokken.yml for faster testing with kitchen-dokken
  • Added support for env var CHEF_VERSION to affect kitchen-dokken chef-client version
  • Supports chef-client version 12.21.26 and 13.6.4

v2.0.1

  • Add manage_serial option to bind_primary_zone_template resource

v2.0.0

  • Migrate to using custom resources. See MIGRATION.md for details on migrating from v1.x.

v1.3.0

  • Change default for statistics channel to be false, and add an attribute to set the bind address.

v1.2.0

  • Add server clause.
  • Add bind forwardzones attribute.

v1.1.4

  • restore previous default for querylog size and amount
  • correct quoting for log file rotation
  • minor rubocop corrections

v1.1.3

  • Added log_file_size attribute.

v1.1.1

  • Added array for domainzones attribute

v1.1.0

  • Add named-checkconf sanity checking
  • Add thor/scmversion
  • Update specs

v1.0.3

  • Update documentation

v1.0.2

  • Stub file for service tests

v1.0.1

  • Add delayed timing to service reload
  • Fix a minor issue with rndc.key on CentOS 6.x

v1.0.0

Clearing out backlog of issues.

  • Add standalone logging support, to named.options file. #4
  • Revert incorrect /etc/named.conf location for EL6.
  • Graceful handling for lack of data_bags. #7
  • Added documentation for standalone logging support. #8
  • Added statistics-channel support. #9
  • Updated kitchen and build files.
  • Added bats tests.
  • Removed minitests/Added chefspec

BREAKING CHANGE

  • Removed etc_cookbook_files and etc_template_files in favor of simpler bind['included_files'] attribute

Explanation:

You could, for examplem, drop off other static files or templates in your sysconf
directory. Then include these files in your named.conf by overriding this attribute.

v0.2.0

This is the first cookbook, I have validated with @fnichol re-write
of test-kitchen. It took
about 3-4 minutes to validate this cookbook across 4 platforms.

I identified two RHEL 5, and one Ubuntu, recipe bugs which nobody
including myself has caught. I cannot overstate, how much time this
has saved me. If you have not tried the test-kitchen re-write,
do yourself the favor and start working with it now.

  • Add test-kitchen/Berkshelf skeleton files
  • Platform-specific fixes
    • Correct location of /etc/named.conf on RHEL 5
    • Added conf_file and options_file are attributes
    • Refactor service actions, and config file rendering
    • Enabled usage of search also on chef-solo via @fabn
    • Various Ubuntu platform fixes via @fabn
    • Added apt recipe to pass test-kitchen

v0.1.1

  • Pass zone array to template with uniq and sort

v0.1.0

  • Add bind zones attributes for "role (attribute)", "ldap", and "databag" sources.

v0.0.9

ldap host incorrectly being scoped as node.default

v0.0.8

Change node scope to node.default for Chef 11

v0.0.7

Update root nameserver D

v0.0.6

Move masters keyword to slave block

v0.0.4

Clean up and public release

v0.0.2

Initial prototype for internal use

Collaborator Number Metric
            

2.1.0 failed this metric

Failure: Cookbook has 0 collaborators. A cookbook must have at least 2 collaborators to pass this metric.

Contributing File Metric
            

2.1.0 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a CONTRIBUTING.md file

Foodcritic Metric
            

2.1.0 passed this metric

License Metric
            

2.1.0 passed this metric

No Binaries Metric
            

2.1.0 passed this metric

Testing File Metric
            

2.1.0 passed this metric

Version Tag Metric
            

2.1.0 passed this metric