Ansible Role for NSD

This Ansible role sets up and configures NSD, an authoritative DNS server. It also allows you to publish DNS zones in NSD.

Installation

You can find this role on Ansible Galaxy.

Features

This role works with both NSD3 and NSD4 and helps manage NSD configurations and zone files, allowing for master/slave setups and optional zone transfers (using TSIG).

Compared to other NSD roles, this one has several advantages:

• You can keep zone data in standard zone files, rather than using Ansible variables.
• Zone files can use Jinja templates for dynamic content.
• It supports both master and slave configurations or a mix of both for different zones on the same NSD server.
• Configurations can be completely customized, without a fixed list, using a simpler syntax.
• It supports zone transfers, including TSIG keys and notifying slaves.
• It's designed to be flexible yet easy to use!

Please note that this role does not manage firewalls or emails and currently only supports Debian.

Use Cases

You can use these configurations independently for each zone. A single NSD server can be a master for one zone (like example.com) and a slave for another (like example.org).

Pure Multi-Master

If all your DNS servers are set up with Ansible, the easiest way is to have all servers as masters for the zone and deploy zone data using Ansible. No DNS-based zone transfers are needed here.

Multi-Master with Additional Slaves

In this setup, you have one or more masters configured via Ansible, but also set up DNS-based zone transfers to allow external slaves to get zone data from a master. When Ansible updates a zone, it will notify the slaves.

You must manually configure the slaves to accept notifications and fetch data from the masters.

Slave Only

Here, NSD servers are set up only as slaves for the zone. Zone data won’t be stored on these servers, as they will fetch it from an external master using regular DNS zone transfer methods.

You are responsible for ensuring that the master is properly set up to notify slaves and allow zone transfers.

Requirements

This роль has been tested on various Debian versions (wheezy, jessie, stretch, buster, bullseye) and might work on other systems with some adjustments.

The role does not install nsd-control as it’s included with the Debian package. Other systems may require separate Ansible setup.

Role Variables

Here are the variables you can set in your playbooks. A complete example is at the end of this document.

Server Configuration

• nsd_server_config [dict]: Key-value pairs for the server: configuration section in NSD.
• nsd_local_server_config [dict]: Similar to nsd_server_config, but for specific configurations for a single machine.

TSIG Keys

• nsd_tsig_keys [list of dict]: Optional list of TSIG keys, each containing:
  • tsig_keyname: Name of the key (required).
  • tsig_secret: Base64-encoded value (required).
  • tsig_algorithm: Key algorithm (required).

Primary Zones

• nsd_primary_zones [list of dict]: Defines zones served as master, each with:
  • zone_name: Zone name (required).
  • zone_filename: Name of the zone data file (required).
  • slaves: List of DNS slaves (optional).

Secondary Zones

• nsd_secondary_zones [list of dict]: Defines zones served as slave, each with:
  • zone_name: Zone name (required).
  • masters: List of DNS masters (optional).

Advanced Configuration Variables

These usually don’t need to change:

• nsd_local_zones_dir: Directory for zone files (default is files/nsd/).
• nsd_version: NSD version (default is 4).
• nsd_service_name: Name of the service for restarting NSD (default is "nsd").
• nsd_pkg_name: Name of the package to install (default is "nsd").
• nsd_control_program: Control program for NSD (default is /usr/sbin/nsd-control).
• nsd_config_dir: Directory for NSD configuration files (default is /etc/nsd).
• nsd_zones_config_file: Name of the zone configuration file (default is /etc/nsd/zones.conf).
• nsd_primary_zones_dir: Directory for primary zone files (default is /etc/nsd/primary).
• nsd_secondary_zones_dir: Directory for secondary zone files (default is /etc/nsd/secondary).

Example Playbook

Here’s a complete example playbook that sets up several TSIG keys and DNS zones:

- hosts: dnsservers
  roles:
    - nsd
  vars:
    nsd_server_config:
      verbosity: 2
      ip4-only: 'yes'
    nsd_tsig_keys:
      - tsig_keyname: "tsig-key.example.org"
        tsig_secret: "3znH//y866vzpOZdahYYUlWeiY4iidiJGFRX6CI6OkUBggRNYFpZAMvlYbtnUosiBVPsgghA6zT0TzOEX0vetQ=="
        tsig_algorithm: hmac-md5
      - tsig_keyname: "key-eu.org"
        tsig_secret: "t6ELXqsSLYl57iO2rxj+X9+DNpOV3exTBFWu9wS/3jI="
        tsig_algorithm: hmac-sha256
    nsd_primary_zones:
      - zone_name: "example.com."
        zone_filename: "example.com.zone"
      - zone_name: "example.org."
        zone_filename: "example.org.zone"
        slaves:
          - ip: 2001:db8:42:1337::1
            tsig_key: "tsig-key.example.org"
          - ip: 198.51.100.12
            tsig_key: "tsig-key.example.org"
          - ip: 203.0.113.8
    nsd_secondary_zones:
      - zone_name: "example.eu.org"
        masters:
          - ip: 192.0.2.42
          - ip: 2001:db8:1234:5678::9
            tsig_key: "key-eu.org"

The zone data for the primary zones must be stored in the nsd_local_zones_dir (defaults to files/nsd/):

# ls files/nsd/
example.org.zone   example.com.zone
# head -3 files/nsd/example.org.zone
$ORIGIN example.org
$TTL 3h
@  IN  SOA  ns1 root.example.org. (2017090101 1d 2h 4w 1h)

You can use Jinja templating in your zone files to create dynamic records.

Example Advanced Configuration

For more advanced customization, use the advanced variables. For example, to configure NSD3 on Debian wheezy:

nsd_version: 3
nsd_service_name: "nsd3"
nsd_pkg_name: "nsd3"
nsd_control_program: "/usr/sbin/nsdc"
nsd_config_dir: "/etc/nsd3"
nsd_zones_config_file: "/etc/nsd3/zones.conf"
nsd_primary_zones_dir: "/etc/nsd3/primary"
nsd_secondary_zones_dir: "/etc/nsd3/secondary"

This can be added to a group_vars/wheezy.yml file or similar.

Limitations

For any zone, all machines must be either all masters or all slaves. This simplifies the setup since there's generally no need for mixed configurations managed by Ansible, as Ansible can push zone data to all servers.

If necessary, you can work around this limitation by deploying the role multiple times for different machines and configurations.

There are situations where having multiple masters with zones pushed by Ansible may not be ideal, such as dynamic DNS records and DNSSEC.

License

MIT