1. Overview
2. Module Description - What the module does and why it is useful
3. Setup - The basics of getting started with knot
   • What knot affects
   • Setup requirements
   • Beginning with knot
4. Usage - Configuration options and additional functionality
5. Reference - An under-the-hood peek at what the module is doing and how
6. Limitations - OS compatibility, etc.
7. Development - Guide for contributing to the module

This Puppet module manages the Knot DNS server.

Info: Module version 2.2.x is only compatible with Knot > 2.3.x. If you're still on Knot 1.x, please use the module version 1.x.

Knot DNS server is a "High-performance authoritative-only DNS server". This Puppet module manages the configuration file /etc/knot/knot.conf and includes a separate configuration file for the zones under /etc/knot/zones.conf. Not every configuration parameter is directly exposed, instead it uses a "key/value" approach in hashes, so that if there will be more/changed/other parameters in the future the module will just work without any changes. It also manages the installation of the package and starting/restarting the system service.

• Package knot installation. If manage_package_repo is true, it also adds the official apt repository by using the puppetlabs/apt module
• Service knot starting and restarting on configuration change
• Writing of configuration files:
  • /etc/knot/knot.conf.puppet
  • /etc/knot/zones.conf.puppet
• Creation of the folders and managing of the user and group rights on $default_storage
• Creation of Signing Policies

A simple include knot installs Knot DNS from the default package source and creates a configuration file with sane defaults. When starting Knot DNS it complains warning: no zones loaded, this tells us that it would make sense to add some zones. Please note: Your distro will most likely not yet include Knot 2.x. So you should set at least the parameter manage_package_repo to true.

Adding zones is as simple as follows:

class { 'knot':
  zones => { 'myzone.net'      => '',
             'myotherzone.com' => {
               'xfr-out'    => 'server1',
               'notify-out' => 'server1' },
           },
}

Zones will be added to /etc/knot/zones.conf.

Note: The paramter zones is a hash

All parameter defaults are defined in params.pp and init.pp. To pass a parameter to the module, they need to be passed to the main class. Here is a usage example for some parameters which most likely will be changed by the module user:

$zones = {
  'myzone.net'      => '',
  'myotherzone.com' => {
    'xfr-out'    => 'server1',
    'notify-out' => 'server1' },
}
class { 'knot':
  manage_package_repo => true,
  keys                => { 'key0.server0' => {
                             'algorithm' => 'hmac-md5',
                             'key'       => 'Wg==' }
  },
  zones               => $zones,
}

Hint: As you can see, most parameters are hashes which make them look weird and unreadable. That's a reason why using Hiera is recommended.

This module is fully compatible with Hiera. Here is an example on how to pass parameters to the module:

knot::manage_package_repo: true

knot::zones:
  myzone.ch:
    template: dnssec
  myotherzone.ch: {}
knot::server:
  identity: 'noidentityhere'
knot::acls:
  myacl1:
    action: transfer
knot::control:
  acl: myacl1
knot::remotes:
  myremote1:
    address: 127.0.0.1
    key: key1
knot::templates:
  dnssec:
    dnssec-signing: on
    dnssec-policy: default_rsa
    storage: /var/lib/knot
    zonefile-sync: -1
    kasp-db: /var/lib/knot/kasp
    file: /var/lib/knot/zones/%s.zone
  default:
    storage: /var/lib/knot
    file: /var/lib/knot/zones/%s.zone
knot::log:
  stderr:
    any: debug
knot::keys:
  key1:
    algorithm: hmac-md5
    secret: c0570d4931593d46333c9ddf15894a8550e131f4
  key2:
    algorithm: hmac-sha1
    secret: c0570d4931593d46333c9ddf15894a8550e131f4
knot::policies:
  default_rsa:
    algorithm: RSASHA256
    zsk-size: 1024
    ksk-size: 2048
knot::modules:
  dnstap:
    sink: unix:https://var/run/sink
  synth-record:
    type: forward
    prefix: bla
    origin: blubb.ch

Note: This is not a fully functional configuration, it's just here for an example on how to use Hiera.

Zones are passed to the main class in the zones hash. The configuration get's written to /etc/knot/zones.conf. To pass default values to all zones, the hash zone_defaults exists. Everything in this hash is applied to all zones. If a parameter needs to be overwritten for a single zone, just add this parameter to the zone, the zone parameters wins. Since Knot 2.x gained the template functionality, this feature will most likely only be used for setting a default template for all zones.

For an overview on how automatic DNSSEC signing works in Knot, see official docs.

Overview of file locations with the following template configured:

knot::templates:
  dnssec:
    dnssec-signing: on
    dnssec-policy: default_rsa
    storage: /var/lib/knot
    zonefile-sync: -1
    kasp-db: /var/lib/knot/kasp
    file: /var/lib/knot/zones/%s.zone

• Zonefiles: /var/lib/knot/zones/%s.zone
• KASP DB: /var/lib/knot/kasp
• Zone keys: /var/lib/knot/kasp/keys
• Timers: /var/lib/knot/timers
• Signed zones: Only in memory (zonefile-sync is -1) and under /var/lib/knot/<zone>.db

Using this configuration the directory /var/lib/knot/zones can be savely managed with git.

• knot: Installs and configures Knot in your environment.

All configuration is passed to init.pp:

[manage_package_repo] Default: false. If set to true, make sure the puppetlabs/apt module is available as it adds the knot-dns.cz repo to the APT sources

[package_ensure] Default: installed. See Puppet type 'package' documentation

[package_name] Default: On Debian 'knot'. Package name to install knot

[package_repo_key] Default: Depends on $::lsbdistid, see params.pp. Only used when $manage_package_repo is true. Signing key of the packages

[package_repo_key_src] Default: Depends on $::lsbdistid, see params.pp. Only used when $manage_package_repo is true. Source of the package signing public key

[package_repo_location] Default: Depends on $::lsbdistid, see params.pp. Only used when $manage_package_repo is true. Location of the package repository

[package_repo_repos] Default: Depends on $::lsbdistid, see params.pp. Only used when $manage_package_repo is true. Repos used on the repository location

[manage_user] Default: true. Manages the Puppet user resource for the user $service_user

[service_enable] Default: true. See Puppet type 'service' documentation

[service_ensure] Default: running. See Puppet type 'service' documentation

[service_group] Default: On Debian 'knot'. Group under which the knot daemon runs

[service_manage] Default: true. If set to false, the Puppet type 'service' will not be created Can be usefull if the service is managed by a cluster manager

[service_name] Default: On Debian 'knot'. Name of the system service to manage

[service_restart] Default: '/usr/sbin/knotc reload'. Command to reload Knot

[service_status] Default: '/usr/sbin/knotc rstatus'. Command to check the status of Knot

[service_user] Default: On Debian 'knot'. User under which the knot daemon runs

[default_storage] Default: '/var/lib/knot'. Full path to the 'storage' dir

[main_config_file] Default: '/etc/knot/knot.conf'. Full path to the main configuration file

[manage_zones] Default: true. Set false if you want to manage only package and service.

[template_parameter] Default: template. Name of the template parameter used inside the zones hash.

[zone_defaults] Default: {}. Hash which contains default parameters which are added to every zone definition under the 'zones' statement. Can be used f.e. to set a default template. See https://www.knot-dns.cz/docs/2.x/html/reference.html#zone-section

[zones_config_file] Default: '/etc/knot/zones.conf'. Full path to the zones configuration file

[zones_config_template] Default: 'knot/zones.conf.erb'. Reference to zone.conf erb template

[acls] Default: {}. Acl section. See https://www.knot-dns.cz/docs/2.x/html/reference.html#acl-section

[control] Default: {}. Control section. See https://www.knot-dns.cz/docs/2.x/html/reference.html#control-section

[keys] Default: {}. Keys section. See https://www.knot-dns.cz/docs/2.x/html/reference.html#key-section

[log] Default:

    $log = {
      syslog => {
        any  => 'info'
      }
    }

Logging section. See https://www.knot-dns.cz/docs/2.x/html/reference.html#logging-section

[modules] Default: {}. Modules section. See https://www.knot-dns.cz/docs/2.x/html/reference.html -> module-X Key: module name without "mod-", Values: Hash of module parameters.

[policies] Default: {}. Configures DNSSEC policies. See https://www.knot-dns.cz/docs/2.x/html/reference.html#policy-section

[remotes] Default: {}. Remotes section. See https://www.knot-dns.cz/docs/2.x/html/reference.html#remote-section

[server] Default:

    $server = {
      listen => [
        '0.0.0.0@53',
        '::@53',
      ]
    }

Server section. See https://www.knot-dns.cz/docs/2.x/html/reference.html#server-section

[templates] Default: {}. Template section. See https://www.knot-dns.cz/docs/2.x/html/reference.html#template-section

[zones] Default: {}. Hash of zones. They will be added to the $zones_config_file file. See https://www.knot-dns.cz/docs/2.x/html/reference.html#zone-section Example:

  $zones = {
    'myzone.net'      => '',
    'myotherzone.com' => {
      'xfr-out'    => 'server1',
      'notify-out' => 'server1' },
  }

• knot::install: Manages the APT repo and installs Knot
• knot::config: Writes the Knot configuration files and prepares DNSSEC things
• knot::service: Manages the Knot system service

There are rspec-puppet tests available. To run them you first need to install all needed GEMs by running bundler. Then a rake task executes the Rspec tests: bundle exec rake spec.

At this time this module is only tested under Ubuntu 14.04, but it should also work on any other Linux distribution. However package repo management ($manage_package_repo) is only supported on Debian based OS families.

1. Fork it ( https://github.com/tobru/puppet-knot/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Make sure your PR passes the Rspec tests.