{"id":19982041,"url":"https://github.com/mfinelli/puppet-nsd","last_synced_at":"2025-05-04T05:32:12.505Z","repository":{"id":31038002,"uuid":"34596616","full_name":"mfinelli/puppet-nsd","owner":"mfinelli","description":"Puppet module for managing NSD","archived":false,"fork":false,"pushed_at":"2020-01-04T02:42:13.000Z","size":111,"stargazers_count":2,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-18T15:09:28.206Z","etag":null,"topics":["nsd","puppet","zone-files"],"latest_commit_sha":null,"homepage":"https://forge.puppetlabs.com/mfinelli/nsd","language":"Puppet","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mfinelli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-26T03:37:57.000Z","updated_at":"2021-08-25T19:36:39.000Z","dependencies_parsed_at":"2022-09-26T21:31:34.220Z","dependency_job_id":null,"html_url":"https://github.com/mfinelli/puppet-nsd","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfinelli%2Fpuppet-nsd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfinelli%2Fpuppet-nsd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfinelli%2Fpuppet-nsd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfinelli%2Fpuppet-nsd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mfinelli","download_url":"https://codeload.github.com/mfinelli/puppet-nsd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252293082,"owners_count":21724960,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nsd","puppet","zone-files"],"created_at":"2024-11-13T04:08:41.527Z","updated_at":"2025-05-04T05:32:12.059Z","avatar_url":"https://github.com/mfinelli.png","language":"Puppet","readme":"# nsd\n\n[![Build Status](https://travis-ci.org/mfinelli/puppet-nsd.svg?branch=master)](https://travis-ci.org/mfinelli/puppet-nsd)\n[![Puppet Forge](https://img.shields.io/puppetforge/v/mfinelli/nsd.svg)](https://forge.puppetlabs.com/mfinelli/nsd)\n\n#### Table of Contents\n\n1. [Overview](#overview)\n2. [Module Description - What the module does and why it is useful](#module-description)\n3. [Setup - The basics of getting started with nsd](#setup)\n    * [What nsd affects](#what-nsd-affects)\n    * [Beginning with nsd](#beginning-with-nsd)\n4. [Usage - Configuration options and additional functionality](#usage)\n5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)\n5. [Limitations - OS compatibility, etc.](#limitations)\n6. [Development - Guide for contributing to the module](#development)\n\n## Overview\n\nManage the installation and configuration of NSD (name serve daemon) and zone\nfiles.\n\n## Module Description\n\nThis module allows for the management of all aspects of the NSD configuration\nfile, keys and zonefiles. It adds easy slave/master configuration but you can\nalso use the module to create authoritative zonefiles and essentially have\npuppet become the master nameserver and all nameservers would be the slaves.\n\nThe module only writes non-default options to the configuration file and allows\nyou to set any option through the use of hashes instead of predefined variables,\nwhere appropriate.\n\n## Setup\n\n### What nsd affects\n\n* Only non-default configuration options are written to `etc/nsd/nsd.conf`.\n* Also manages the nsd package and service (unless `service_manage = false`).\n* Create and manage BIND-compatible zone files.\n\n### Beginning with nsd\n\nInstall the package an make sure it is enabled and running with default options:\n\n```puppet\ninclude '::nsd'\n```\n\nWith some basic configuration:\n\n```puppet\nclass { '::nsd':\n  options =\u003e {\n    'server-count' =\u003e 1,\n    'ip-address'   =\u003e ['1.2.3.4', '5.6.7.8'],\n  }\n}\n```\n\n## Usage\n\n\nThe bare miniumum will make sure the nsd package is installed and the service is\nrunning:\n\n```puppet\ninclude '::nsd'\n```\n\nTo pass ins some configuration options:\n\n```puppet\nclass { '::nsd':\n  options =\u003e {\n    'server-count' =\u003e 1,\n    'ip-address'   =\u003e ['1.2.3.4', '5.6.7.8'],\n  }\n}\n```\n\nTo configure the remote with defaults:\n\n```puppet\ninclude '::nsd::remote'\n```\n\nTo set configuration options where puppet *does not* manage files:\n\n```puppet\nclass { '::nsd::remote':\n  port            =\u003e 8953,\n  server_key_file =\u003e '/etc/nsd/arbitrary_filename.key',\n}\n```\n\nTo have puppet manage the keys and certificate files:\n\n```puppet\nclass { '::nsd::remote':\n  server_key_manage  =\u003e true,\n  server_key_file    =\u003e 'puppet:///modules/nsd/nsd_server.key'\n  server_cert_manage =\u003e true,\n  server_cert_file   =\u003e 'puppet:///modules/nsd/nsd_server.pem'\n}\n```\n\nTo setup transfer keys:\n\n```puppet\n::nsd::key { 'testkey':\n  secret =\u003e 'INhFh7DsZRRXp2NX/0vB+nS7Nh+lOfBJnpQgVmXllVs='\n}\n```\n\nTo create an arbitrary pattern:\n\n```puppet\n::nsd::pattern { 'testpattern':\n  options =\u003e {\n    'notify-retry' =\u003e 5,\n  }\n}\n```\n\nTo create a master pattern: (note that the `slave_key` is just the key name and\nthat setting options is completely optional)\n\n```puppet\n::nsd::pattern::master { 'master':\n  slave_server =\u003e '127.0.0.1',\n  slave_key    =\u003e 'testkey',\n  options      =\u003e {\n    'notify-retry' =\u003e 5,\n  }\n}\n```\n\nNow the pattern can be included in zones by the name \"to_slave_127.0.0.1\".\n\nTo create a slave pattern: (note that the `master_key` is just the key name)\n\n```puppet\n::nsd::pattern::slave { 'slave':\n  master_server =\u003e '127.0.0.1',\n  master_key    =\u003e 'testkey',\n}\n```\n\nNow the pattern can be included in zones by the name \"from_master_127.0.0.1\".\n\nTo create a zone with a file managed by puppet and using the slave pattern from\nabove:\n\n```puppet\n::nsd::zone { 'example.com':\n  zonefile_manage =\u003e true,\n  zonefile        =\u003e 'puppet:///modules/nsd/example.com.zone',\n  options         =\u003e {\n    'include-pattern' =\u003e 'from_master_127.0.0.1'\n  }\n}\n```\n\nTo create an authoritative zone and include it in the main configuration file\nwith the master pattern from above:\n\n```puppet\n::nsd::zonefile { 'example.org':\n  serial_number =\u003e 2015050101,\n  admin_email   =\u003e 'admin@example.org',\n  nameservers   =\u003e ['ns1.example.org.', 'ns2.example.org.'],\n  mxservers     =\u003e {5 =\u003e 'mail1.example.org.', 10 =\u003e 'mail2.example.org.'},\n  records       =\u003e [\n    {'name' =\u003e 'ns1', 'type' =\u003e 'A', 'location' =\u003e '127.0.0.1'},\n    {'name' =\u003e 'ns2', 'type' =\u003e 'A', 'location' =\u003e '127.0.0.2'},\n    {'name' =\u003e '@', 'type' =\u003e 'A', 'location' =\u003e '123.123.123.123'},\n    {'name' =\u003e 'www', 'type' =\u003e 'CNAME', 'location' =\u003e '@'},\n  ],\n  'include_options' =\u003e {\n    'include-pattern' =\u003e 'to_slave_127.0.0.1',\n  },\n}\n```\n\nThis would result in the following authoritative zone for example.org saved in\n`etc/nsd/example.org.zone`:\n\n```\n;; example.org authoritative zone managed by puppet\n\n$ORIGIN example.org.\n$TTL 86400\n\n@ IN SOA ns1.example.org. admin.example.org. ( 2015050101 28800 7200 864000 86400 )\n\n NS ns1.example.org.\n NS ns2.example.org.\n\n MX 5 mail1.example.org.\n MX 10 mail2.example.org.\n\n ns1 A 127.0.0.1\n ns2 A 127.0.0.2\n @ A 123.123.123.123\n www CNAME @\n```\n\n## Reference\n\n### Classes\n\n#### Public classes\n\n* nsd: main class, includes all other private classes\n* nsd::remote: enables and configures the remote\n\n#### Private classes\n\n* nsd::install: Handles the packages.\n* nsd::config: Handles the configuration file.\n* nsd::service: Handles the service.\n\n### Defined types\n\n* nsd::key: creates transfer keys.\n* nsd::pattern: creates pattern sections.\n* nsd::pattern::master: a macro for the nsd::pattern type to ease creation of\n  master servers.\n* nsd::pattern::slave: a macro for the nsd::pattern type to ease creation of\n  slave servers.\n* nsd::zone: adds zones and zonefiles.\n* nsd::zonefile: creates authoritative zonefiles.\n\n### Parameters: `nsd`\n\nThe following parameters are available in the nsd module:\n\n#### `config`\n\nThis is the filename of the main configuration file. Default value:\n'/etc/nsd/nsd.conf'\n\n#### `config_template`\n\nThe template to use for the server section of the configuration file. Default\nvalue: 'nsd/nsd.conf.erb'\n\n#### `options`\n\nHash of options to set in the configuration file under the `server` section.\n\n```puppet\n$options = {\n  'option'       =\u003e 'value',\n  'other_option' =\u003e ['value1', 'value2']\n}\n```\n\n#### `package_ensure`\n\nTells Puppet whether the NSD package should be installed, and what version.\nValid options: 'present', 'latest', or a specific version number. Default value:\n'present'\n\n#### `package_name`\n\nTells Puppet what NSD package to manage. Valid options: string. Default value:\n'nsd'\n\n#### `service_manage`\n\nTells Puppet whether to manage the NSD service. Valid options: 'true' or\n'false'. Default value: 'true'\n\n#### `service_ensure`\n\nTells Puppet whether the NSD service should be running. Valid options: 'running'\nor 'stopped'. Default value: 'running'\n\n#### `service_enable`\n\nTells Puppet whether to enable the NSD service at boot. Valid options: 'true' or\n'false'. Default value: 'true'\n\n#### `service_name`\n\nTells Puppet what NSD service to manage. Valid options: string. Default value:\n'nsd'\n\n### Parameters: `nsd::remote`\n\nThe following parameters are available in the nsd::remote module:\n\n#### `config`\n\nThe config file to write the remote section. Inherits from nsd::params::config,\nso if you overwrite there you'll need to overwrite here as well.\n\n#### `config_template`\n\nThe template to use for writing the remote section. Default value:\n'nsd/remote.erb'\n\n#### `enable`\n\nWhether to enable the remote or not. Default value is true but it should never\nbe necessary to set it to false, in that case just don't include the nsd::remote\nmodule and nothing will be written to the configuration file.\n\n#### `interface`\n\nEither a string or an array of strings of interfaces that ar listened to for\ncontrol. Defaults to localhost.\n\n#### `port`\n\nPort number for remote control operations (uses TLS over TCP). Default value:\n8952\n\n#### `server_key_manage`\n\nWhether to have puppet manage the server key file. Default value: false\n\n#### `server_key_file`\n\nIf `server_key_manage` is true then this points to a source for the file.\nOtherwise it can be undefined or an arbitrary filename for server-key-file.\n\n#### `server_cert_manage`\n\nWhether to have puppet manage the server cert file. Default value: false\n\n#### `server_cert_file`\n\nIf `server_cert_manage` is true then this points to a source for the file.\nOtherwise it can be undefined or an arbitrary filename for server-cert-file.\n\n#### `control_key_manage`\n\nWhether to have puppet manage the control key file. Default value: false\n\n#### `control_key_file`\n\nIf `control_key_manage` is true then this points to a source for the file.\nOtherwise it can be undefined or an arbitrary filename for control-key-file.\n\n#### `control_cert_manage`\n\nWhether to have puppet manage the control cert file. Default value: false\n\n#### `control_cert_file`\n\nIf `control_cert_manage` is true then this points to a source for the file.\nOtherwise it can be undefined or an arbitrary filename for control-cert-file.\n\n### Parameters: `nsd::key`\n\nThe following parameters are available in the nsd::key defined type:\n\n#### `config`\n\nThe config file to write the key section. Inherits from nsd::params::config, so\nif you overwrite there you'll need to overwrite here as well.\n\n#### `config_template`\n\nThe template to use for writing the key section. Default value: 'nsd/key.erb'\n\n#### `algorithm`\n\nAlgorithm to use. Valid options: 'md5', 'sha1', 'sha256'. Defaul value: 'sha256'\n\n#### `secret`\n\nThe secret material to use. Recommended to generate with the command:\n`dd if=/dev/random of=/dev/stdout count=1 bs=32 | base64`.\n\n#### `secret_file`\n\nWhether the secret should be stored in a separate file with 640 permissions.\nDefaults to false. If true the filename will be `name.keyfile`.\n\n### Parameters `nsd::pattern`\n\nThe following parameters are available in the nsd::pattern defined type:\n\n#### `config`\n\nThe config file to write the pattern section. Inherits from nsd::params::config,\nso if you overwrite there you'll need to overwrite here as well.\n\n#### `config_template`\n\nThe template to use for writing the pattern section. Default value:\n'nsd/pattern.erb'\n\n#### `options`\n\nHash of options to set for the pattern.\n\n```puppet\n$options = {\n  'option' =\u003e 'value',\n}\n```\n\n### Parameters `nsd::pattern::master`\n\nThe following paramters are available in the nsd::pattern::master defined type:\n\n#### `slave_server`\n\nThe server that needs to be notified when zone files change.\n\n#### `slave_key`\n\nThe name of the TSIG key with which to perform the transfer.\n\n#### `options`\n\nAny additional valid pattern options to set.\n\n### Parameters `nsd::pattern::slave`\n\nThe following parameters are available in the nsd::pattern::slave defined type:\n\n#### `master_server`\n\nThe server to allow zone transfers from.\n\n#### `master_key`\n\nThe name of the TSIG key with which to perform the transfer.\n\n#### `transfer_mode`\n\nThe transfer mode. Since NSD only speaks AXFR you shouldn't ever need to change\nit, but depending on your other servers you might want something like IXFR/UDP.\n\n#### `options`\n\nAny additional valid pattern options to set.\n\n### Parameters `nsd::zone`\n\nThe following parameters are available in the nsd::zone defined type:\n\n#### `config`\n\nThe config file to write the zone section. Inherits from nsd::params::config, so\nif you overwrite there you'll need to overwrite here as well.\n\n#### `config_template`\n\nThe template to use for writing the zone section. Default value: 'nsd/zone.erb'\n\n#### `zonefile_manage`\n\nWhether to have puppet manage the zonefile. Default value: false\n\n#### `zonefile`\n\nIf `zonefile_manage` is true then this should be a path to a file that puppet\ncan serve. Otherwise it will enter the arbitrary name here as the zonefile value\nin nsd.conf.\n\n#### `options`\n\nAny additional valid zone options to set (e.g., \"include-pattern\").\n\n### Parameters `nsd::zonefile`\n\nThe following parameters are available in the nsd::zonefile defined type:\n\n#### `include_in_config`\n\nWhether or not to include the zone in `nsd.conf`. Default value: true\n\n#### `include_options`\n\nAny additional valid zone options to set when including the zone in `nsd.conf`\n(e.g., \"include-pattern\").\n\n#### `serial_number`\n\nThe serial number for the zone. Can be any valid integer but usually we use the\nform 'YYYYMMDDnn'.\n\n#### `admin_email`\n\nThe admin email address for the zone. Should *not* have a period at the end, it\nwill be automatically added in the template.\n\n#### `ttl`\n\nValue in seconds of the time to live. Should be less than three days. Default\nvalue: 86400 (1 day)\n\n#### `refresh`\n\nValue in seconds that a slave will try to refresh the zone. Recommended setting\nis between one hour and one day depending on how often your zone changes.\nDefault value: 28800 (8 hours)\n\n#### `retry`\n\nValue in seconds that a slave will wait before retrying if they are unable to\nconnect to the master. Recommended value is between five minutes and four hours.\nDefault value: 7200 (2 hours)\n\n#### `expire`\n\nValue in seconds that the zone is valid for. Recommended value is between one\nweek and four weeks. Default value is 864000 (10 days)\n\n#### `nameservers`\n\nAn array of nameservers for this domain. N.B. that they need to end in a period.\n\n#### `mxservers`\n\nA hash of the mail servers for the domain. The priority is the key and the\nserver is the value. The are automatically ordered. N.B. that the servers need\nto end in a period.\n\n#### `records`\n\nAn array of hashes of the records that the zone should serve. Each hash needs to\nhave three keys: name, type, and location.\n\n### Functions\n\nThis module defines several custom functions in order to validate data.\n\n#### `validate_ip_address_array`\n\nValidates an array of IP addresses, raising a ParseError should one or more\naddresses fail. Validates both v4 and v6 IP addresses.\n\n##### Examples\n\nThe following values will pass:\n\n```puppet\nvalidate_ip_address_array(['127.0.0.1', '::1'])\n```\n\nThe following values will raise an error:\n\n```puppet\nvalidate_ip_address_array('127.0.0.1')\nvalidate_ip_address_array(['not-an-address'])\n```\n\n## Limitations\n\nThis module has been tested on:\n\n* Debian 8 (jessie)\n\n## Development\n\nThis module is still under development. If you would like to help (especially\nfor platforms other than Debian) please send fork the project at\n[GitHub](https://github.com/mfinelli/puppet-nsd) and send a pull request. New\nfeatures belong in a feature branch named `feature/your-feature` and the pull\nrequest should be against the\n[develop](https://github.com/mfinelli/puppet-nsd/tree/develop) branch. Please\nadd your name below and to the authors section of any file that you modify.\nWhile not required, it would be nice if you wrote test cases for any\nfunctionality that you add.\n\n## Authors\n\n* Mario Finelli\n\n## License\n\nCopyright 2015 Mario Finelli\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfinelli%2Fpuppet-nsd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmfinelli%2Fpuppet-nsd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfinelli%2Fpuppet-nsd/lists"}