Ansible Role: dnsdist

This Ansible role was created by the team at PowerDNS to set up dnsdist.

Requirements

You need Ansible version 2.9 or higher.

Dependencies

None.

Role Variables

The available variables are listed below with their default values (see defaults/main.yml):

dnsdist_install_repo: ""

By default, dnsdist is installed from the software repositories available on the target hosts.

# To install dnsdist from the master branch
- hosts: dnsdist
  roles:
  - { role: PowerDNS.dnsdist,
      dnsdist_install_repo: "{{ dnsdist_powerdns_repo_master }}" }

# To install dnsdist 1.3.x
- hosts: dnsdist
  roles:
  - { role: PowerDNS.dnsdist,
      dnsdist_install_repo: "{{ dnsdist_powerdns_repo_13 }}" }

The examples above show how to install dnsdist from the official PowerDNS repositories (check out the full list of pre-defined repositories in vars/main.yml).

- hosts: all
  vars:
    dnsdist_install_repo:
      name: "dnsdist" # the repository name
      apt_repo_origin: "example.com"  # for pinning dnsdist to the provided repository
      apt_repo: "deb http://example.com/{{ ansible_distribution | lower }} {{ ansible_distribution_release | lower }}/dnsdist main"
      gpg_key: "http://example.com/MYREPOGPGPUBKEY.asc" # public GPG key for the repository
      gpg_key_id: "MYREPOGPGPUBKEYID" # to avoid re-importing the key each time the role runs
      yum_repo_baseurl: "http://example.com/centos/$basearch/$releasever/dnsdist"
      yum_debug_symbols_repo_baseurl: "http://example.com/centos/$basearch/$releasever/dnsdist/debug"
  roles:
  - { role: PowerDNS.dnsdist }

You can also install dnsdist from custom repositories as shown in the example above.

dnsdist_install_epel: True

By default, EPEL is installed to meet some dnsdist dependencies like libsodium. Set dnsdist_install_epel to False if you want to skip this.

dnsdist_package_name: "{{ default_dnsdist_package_name }}"

The name of the dnsdist package, which is "dnsdist" for both RHEL and Debian-based distributions.

dnsdist_package_version: ""

Optionally, specify a particular version of the dnsdist package to install.

dnsdist_install_debug_symbols_package: False

Install the debugging symbols package for dnsdist.

dnsdist_debug_symbols_package_name: "{{ default_dnsdist_debug_symbols_package_name }}"

The name of the dnsdist debug symbols package to install when dnsdist_install_debug_symbols_package is set to True.

dnsdist_acls: []

Set up the dnsdist ACLs (netmasks).

dnsdist_locals: ['127.0.0.1:5300']

Configure the listening addresses for dnsdist.

dnsdist_servers:
  - '127.0.0.1'
  - "{ address='127.0.0.1:5300', source='127.0.0.1@lo', order=1 }"

List the IP addresses of the downstream DNS servers that dnsdist should route traffic to, or use Lua tables that the newServer function can understand (see https://dnsdist.org/reference/config.html#newServer).

dnsdist_carbonserver: ""

The IP address of the Carbon server that should receive dnsdist metrics.

dnsdist_controlsocket: "127.0.0.1"

Specify the listening IP address for dnsdist's TCP control socket.

dnsdist_setkey: ""

The encryption key for dnsdist's TCP control socket. If left empty, a random key will be generated. If a key already exists in the file, it will remain unchanged.

dnsdist_webserver_address: ""

The listening IP address of the built-in webserver. It is disabled by default when empty.

dnsdist_webserver_password: ""

Authentication credentials for the built-in webserver. Must be set when dnsdist_webserver_address is specified.

dnsdist_webserver_apikey: ""

Authentication credentials for the built-in API.

dnsdist_webserver_acl: ""

Starting from version 1.5.0, only connections from 127.0.0.1 and ::1 are permitted by default. More details at https://dnsdist.org/guides/webserver.html.

dnsdist_config: ""

Additional configurations for dnsdist to be directly included in the dnsdist.conf file.

dnsdist_config_owner: 'root'
dnsdist_config_group: 'root'

User and group that own the dnsdist.conf file.

dnsdist_service_overrides: {}

Dictionary with overrides for the service (only for systemd). This can be used to change any settings in the [Service] section.

dnsdist_unit_overrides: {}

Dictionary with overrides for the service unit (only for systemd). This can change any settings in the [Unit] section.

dnsdist_environment_overrides: {}

Dictionary with overrides for service environments (only for systemd). This can change environment variables in settings from the [Service] section.

dnsdist_service_state: "started"
dnsdist_service_enabled: "yes"

Specify the desired state of the dnsdist service. For example, this allows installing and configuring dnsdist without automatically starting the service.

dnsdist_disable_handlers: False

Disable automatic service restarts when configuration changes occur.

dnsdist_tlslocals: []

Set up listeners for DNS over TLS. Entries are copied exactly as they are.

dnsdist_force_reinstall: False

Forces a reinstall of dnsdist packages by removing them before installation. Useful for cases where you need to downgrade dnsdist.

Example Playbook

Deploy dnsdist in front of Quad9 and enable the web monitoring interface:

- hosts: dnsdist
  roles:
    - { role: PowerDNS.dnsdist,
        dnsdist_servers: ['9.9.9.9'],
        dnsdist_webserver_address: "{{ ansible_default_ipv4['address'] }}:8083",
        dnsdist_webserver_password: 'geheim' }

Changelog

A detailed changelog of all changes made to the role can be found here.

Testing

Tests are conducted using Molecule.

$ pip install tox

To test all scenarios, run:

$ tox

To run a specific molecule command:

$ tox -e ansible29 -- molecule test -s dnsdist-18

License

MIT