- Overview
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with nsd
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
Manage the installation and configuration of NSD (name serve daemon) and zone files.
This module allows for the management of all aspects of the NSD configuration file, keys and zonefiles. It adds easy slave/master configuration but you can also use the module to create authoritative zonefiles and essentially have puppet become the master nameserver and all nameservers would be the slaves.
The module only writes non-default options to the configuration file and allows you to set any option through the use of hashes instead of predefined variables, where appropriate.
- Only non-default configuration options are written to
etc/nsd/nsd.conf
. - Also manages the nsd package and service (unless
service_manage = false
). - Create and manage BIND-compatible zone files.
Install the package an make sure it is enabled and running with default options:
include '::nsd'
With some basic configuration:
class { '::nsd':
options => {
'server-count' => 1,
'ip-address' => ['1.2.3.4', '5.6.7.8'],
}
}
The bare miniumum will make sure the nsd package is installed and the service is running:
include '::nsd'
To pass ins some configuration options:
class { '::nsd':
options => {
'server-count' => 1,
'ip-address' => ['1.2.3.4', '5.6.7.8'],
}
}
To configure the remote with defaults:
include '::nsd::remote'
To set configuration options where puppet does not manage files:
class { '::nsd::remote':
port => 8953,
server_key_file => '/etc/nsd/arbitrary_filename.key',
}
To have puppet manage the keys and certificate files:
class { '::nsd::remote':
server_key_manage => true,
server_key_file => 'puppet:///modules/nsd/nsd_server.key'
server_cert_manage => true,
server_cert_file => 'puppet:///modules/nsd/nsd_server.pem'
}
To setup transfer keys:
::nsd::key { 'testkey':
secret => 'INhFh7DsZRRXp2NX/0vB+nS7Nh+lOfBJnpQgVmXllVs='
}
To create an arbitrary pattern:
::nsd::pattern { 'testpattern':
options => {
'notify-retry' => 5,
}
}
To create a master pattern: (note that the slave_key
is just the key name and
that setting options is completely optional)
::nsd::pattern::master { 'master':
slave_server => '127.0.0.1',
slave_key => 'testkey',
options => {
'notify-retry' => 5,
}
}
Now the pattern can be included in zones by the name "to_slave_127.0.0.1".
To create a slave pattern: (note that the master_key
is just the key name)
::nsd::pattern::slave { 'slave':
master_server => '127.0.0.1',
master_key => 'testkey',
}
Now the pattern can be included in zones by the name "from_master_127.0.0.1".
To create a zone with a file managed by puppet and using the slave pattern from above:
::nsd::zone { 'example.com':
zonefile_manage => true,
zonefile => 'puppet:///modules/nsd/example.com.zone',
options => {
'include-pattern' => 'from_master_127.0.0.1'
}
}
To create an authoritative zone and include it in the main configuration file with the master pattern from above:
::nsd::zonefile { 'example.org':
serial_number => 2015050101,
admin_email => 'admin@example.org',
nameservers => ['ns1.example.org.', 'ns2.example.org.'],
mxservers => {5 => 'mail1.example.org.', 10 => 'mail2.example.org.'},
records => [
{'name' => 'ns1', 'type' => 'A', 'location' => '127.0.0.1'},
{'name' => 'ns2', 'type' => 'A', 'location' => '127.0.0.2'},
{'name' => '@', 'type' => 'A', 'location' => '123.123.123.123'},
{'name' => 'www', 'type' => 'CNAME', 'location' => '@'},
],
'include_options' => {
'include-pattern' => 'to_slave_127.0.0.1',
},
}
This would result in the following authoritative zone for example.org saved in
etc/nsd/example.org.zone
:
;; example.org authoritative zone managed by puppet
$ORIGIN example.org.
$TTL 86400
@ IN SOA ns1.example.org. admin.example.org. ( 2015050101 28800 7200 864000 86400 )
NS ns1.example.org.
NS ns2.example.org.
MX 5 mail1.example.org.
MX 10 mail2.example.org.
ns1 A 127.0.0.1
ns2 A 127.0.0.2
@ A 123.123.123.123
www CNAME @
- nsd: main class, includes all other private classes
- nsd::remote: enables and configures the remote
- nsd::install: Handles the packages.
- nsd::config: Handles the configuration file.
- nsd::service: Handles the service.
- nsd::key: creates transfer keys.
- nsd::pattern: creates pattern sections.
- nsd::pattern::master: a macro for the nsd::pattern type to ease creation of master servers.
- nsd::pattern::slave: a macro for the nsd::pattern type to ease creation of slave servers.
- nsd::zone: adds zones and zonefiles.
- nsd::zonefile: creates authoritative zonefiles.
The following parameters are available in the nsd module:
This is the filename of the main configuration file. Default value: '/etc/nsd/nsd.conf'
The template to use for the server section of the configuration file. Default value: 'nsd/nsd.conf.erb'
Hash of options to set in the configuration file under the server
section.
$options = {
'option' => 'value',
'other_option' => ['value1', 'value2']
}
Tells Puppet whether the NSD package should be installed, and what version. Valid options: 'present', 'latest', or a specific version number. Default value: 'present'
Tells Puppet what NSD package to manage. Valid options: string. Default value: 'nsd'
Tells Puppet whether to manage the NSD service. Valid options: 'true' or 'false'. Default value: 'true'
Tells Puppet whether the NSD service should be running. Valid options: 'running' or 'stopped'. Default value: 'running'
Tells Puppet whether to enable the NSD service at boot. Valid options: 'true' or 'false'. Default value: 'true'
Tells Puppet what NSD service to manage. Valid options: string. Default value: 'nsd'
The following parameters are available in the nsd::remote module:
The config file to write the remote section. Inherits from nsd::params::config, so if you overwrite there you'll need to overwrite here as well.
The template to use for writing the remote section. Default value: 'nsd/remote.erb'
Whether to enable the remote or not. Default value is true but it should never be necessary to set it to false, in that case just don't include the nsd::remote module and nothing will be written to the configuration file.
Either a string or an array of strings of interfaces that ar listened to for control. Defaults to localhost.
Port number for remote control operations (uses TLS over TCP). Default value: 8952
Whether to have puppet manage the server key file. Default value: false
If server_key_manage
is true then this points to a source for the file.
Otherwise it can be undefined or an arbitrary filename for server-key-file.
Whether to have puppet manage the server cert file. Default value: false
If server_cert_manage
is true then this points to a source for the file.
Otherwise it can be undefined or an arbitrary filename for server-cert-file.
Whether to have puppet manage the control key file. Default value: false
If control_key_manage
is true then this points to a source for the file.
Otherwise it can be undefined or an arbitrary filename for control-key-file.
Whether to have puppet manage the control cert file. Default value: false
If control_cert_manage
is true then this points to a source for the file.
Otherwise it can be undefined or an arbitrary filename for control-cert-file.
The following parameters are available in the nsd::key defined type:
The config file to write the key section. Inherits from nsd::params::config, so if you overwrite there you'll need to overwrite here as well.
The template to use for writing the key section. Default value: 'nsd/key.erb'
Algorithm to use. Valid options: 'md5', 'sha1', 'sha256'. Defaul value: 'sha256'
The secret material to use. Recommended to generate with the command:
dd if=/dev/random of=/dev/stdout count=1 bs=32 | base64
.
Whether the secret should be stored in a separate file with 640 permissions.
Defaults to false. If true the filename will be name.keyfile
.
The following parameters are available in the nsd::pattern defined type:
The config file to write the pattern section. Inherits from nsd::params::config, so if you overwrite there you'll need to overwrite here as well.
The template to use for writing the pattern section. Default value: 'nsd/pattern.erb'
Hash of options to set for the pattern.
$options = {
'option' => 'value',
}
The following paramters are available in the nsd::pattern::master defined type:
The server that needs to be notified when zone files change.
The name of the TSIG key with which to perform the transfer.
Any additional valid pattern options to set.
The following parameters are available in the nsd::pattern::slave defined type:
The server to allow zone transfers from.
The name of the TSIG key with which to perform the transfer.
The transfer mode. Since NSD only speaks AXFR you shouldn't ever need to change it, but depending on your other servers you might want something like IXFR/UDP.
Any additional valid pattern options to set.
The following parameters are available in the nsd::zone defined type:
The config file to write the zone section. Inherits from nsd::params::config, so if you overwrite there you'll need to overwrite here as well.
The template to use for writing the zone section. Default value: 'nsd/zone.erb'
Whether to have puppet manage the zonefile. Default value: false
If zonefile_manage
is true then this should be a path to a file that puppet
can serve. Otherwise it will enter the arbitrary name here as the zonefile value
in nsd.conf.
Any additional valid zone options to set (e.g., "include-pattern").
The following parameters are available in the nsd::zonefile defined type:
Whether or not to include the zone in nsd.conf
. Default value: true
Any additional valid zone options to set when including the zone in nsd.conf
(e.g., "include-pattern").
The serial number for the zone. Can be any valid integer but usually we use the form 'YYYYMMDDnn'.
The admin email address for the zone. Should not have a period at the end, it will be automatically added in the template.
Value in seconds of the time to live. Should be less than three days. Default value: 86400 (1 day)
Value in seconds that a slave will try to refresh the zone. Recommended setting is between one hour and one day depending on how often your zone changes. Default value: 28800 (8 hours)
Value in seconds that a slave will wait before retrying if they are unable to connect to the master. Recommended value is between five minutes and four hours. Default value: 7200 (2 hours)
Value in seconds that the zone is valid for. Recommended value is between one week and four weeks. Default value is 864000 (10 days)
An array of nameservers for this domain. N.B. that they need to end in a period.
A hash of the mail servers for the domain. The priority is the key and the server is the value. The are automatically ordered. N.B. that the servers need to end in a period.
An array of hashes of the records that the zone should serve. Each hash needs to have three keys: name, type, and location.
This module defines several custom functions in order to validate data.
Validates an array of IP addresses, raising a ParseError should one or more addresses fail. Validates both v4 and v6 IP addresses.
The following values will pass:
validate_ip_address_array(['127.0.0.1', '::1'])
The following values will raise an error:
validate_ip_address_array('127.0.0.1')
validate_ip_address_array(['not-an-address'])
This module has been tested on:
- Debian 8 (jessie)
This module is still under development. If you would like to help (especially
for platforms other than Debian) please send fork the project at
GitHub and send a pull request. New
features belong in a feature branch named feature/your-feature
and the pull
request should be against the
develop branch. Please
add your name below and to the authors section of any file that you modify.
While not required, it would be nice if you wrote test cases for any
functionality that you add.
- Mario Finelli
Copyright 2015 Mario Finelli
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.