Ansible Role: PowerDNS Authoritative Server

An Ansible role created by the folks behind PowerDNS to setup the PowerDNS Authoritative Server.

Requirements

An Ansible 2.15 or higher installation.

Dependencies

None.

Role Variables

Available variables are listed below, along with their default values (see defaults/main.yml):

pdns_install_repo: ""

By default, the PowerDNS Authoritative Server is installed from the software repositories configured on the target hosts.

# Install the PowerDNS Authoritative Server from the 'master' official repository
- hosts: all
  roles:
    - { role: PowerDNS.pdns,
        pdns_install_repo: "{{ pdns_auth_powerdns_repo_master }}" }


# Install the PowerDNS Authoritative Server from the '4.8.x' official repository
- hosts: all
  roles:
    - { role: PowerDNS.pdns,
        pdns_install_repo: "{{ pdns_auth_powerdns_repo_48 }}" }

# Install the PowerDNS Authoritative Server from the '4.9.x' official repository
- hosts: all
  roles:
    - { role: PowerDNS.pdns,
        pdns_install_repo: "{{ pdns_auth_powerdns_repo_49 }}" }

# Install the PowerDNS Authoritative Server from the '5.0.x' official repository
- hosts: all
  roles:
    - { role: PowerDNS.pdns,
        pdns_install_repo: "{{ pdns_auth_powerdns_repo_50 }}" }

The examples above, show how to install the PowerDNS Authoritative Server from the official PowerDNS repositories (see the complete list of pre-defined repos in vars/main.yml).

- hosts: all
  vars:
    pdns_install_repo:
      name: "powerdns" # the name of the repository
      apt_repo_origin: "example.com"  # used to pin the PowerDNS packages to the provided repository
      apt_version: "auth-50"  # deb822 suites suffix (appended to release codename)
      apt_repo: "deb http://example.com/{{ ansible_distribution | lower }} {{ ansible_distribution_release | lower }}/pdns main"
      gpg_key: "http://example.com/MYREPOGPGPUBKEY.asc" # repository public GPG key
      gpg_key_id: "MYREPOGPGPUBKEYID" # to avoid to reimport the key each time the role is executed
      yum_repo_baseurl: "http://example.com/centos/$basearch/$releasever/pdns"
      yum_debug_symbols_repo_baseurl: "http://example.com/centos/$basearch/$releasever/pdns/debug"
  roles:
    - { role: PowerDNS.pdns }

It is also possible to install the PowerDNS Authoritative Server from custom repositories as demonstrated in the example above. Note: These repositories are ignored on Arch Linux

When pdns_install_repo.apt_version is set, this role configures Debian-family repositories using ansible.builtin.deb822_repository on supported releases (Ubuntu >=22.04, Debian >=11). If apt_version is omitted, the legacy apt_repo string is used with ansible.builtin.apt_repository.

 pdns_install_epel: true

By default, install EPEL to satisfy some PowerDNS Authoritative Server dependencies like protobuf. To skip the installation of EPEL set pdns_install_epel to false.

pdns_package_name: "{{ default_pdns_package_name }}"

The name of the PowerDNS Authoritative Server package, pdns on RedHat-like systems and pdns-server on Debian-like systems.

pdns_package_version: ""

Optionally, allow to set a specific version of the PowerDNS Authoritative Server package to be installed.

pdns_package_state: "present"

Desired package state for pdns_package_name. Supported values include present, latest, and absent. When set to absent, the role removes packages and skips runtime configuration tasks.

pdns_install_debug_symbols_package: false

Install the PowerDNS Authoritative Server debug symbols.

pdns_debug_symbols_package_name: "{{ default_pdns_debug_symbols_package_name }}"

The name of the PowerDNS Authoritative Server debug package to be installed when pdns_install_debug_symbols_package is true, pdns-debuginfo on RedHat-like systems and pdns-server-dbg on Debian-like systems.

pdns_debug_symbols_package_state: "{{ pdns_package_state }}"

Desired package state for the debug symbols package when it is managed by this role.

pdns_user: pdns
pdns_group: pdns
pdns_file_owner: root
pdns_file_group: "{{ pdns_group }}"

The user and group the PowerDNS Authoritative Server process will run as.
NOTE: This role does not create the user or group as we assume that they've been created by the package or other roles.

pdns_service_name: "pdns"

Name of the PowerDNS service.

pdns_service_state: "started"
pdns_service_enabled: true
pdns_service_masked: false

Allow to specify the desired state of the PowerDNS Authoritative Server service.

pdns_disable_handlers: false

Disable automated service restart on configuration changes.

pdns_manage_selinux: true

Enable management of SELinux booleans and ports on SELinux-enabled systems. Set to false to skip SELinux changes entirely.

pdns_config_dir: "{{ default_pdns_config_dir }}"
pdns_config_file: "pdns.conf"

PowerDNS Authoritative Server configuration file and directory.

pdns_config: {}

Dictionary containing the PowerDNS Authoritative Server configuration.
NOTE: The PowerDNS backends configuration and the config-dir, setuid and setgid directives must be configured through the pdns_user, pdns_group and pdns_backends role variables (see templates/pdns.conf.j2). For example:

pdns_config:
  primary: true
  secondary: false
  local-address: '192.0.2.53'
  local-ipv6: '2001:DB8:1::53'
  local-port: '5300'

configures PowerDNS Authoritative Server to listen incoming DNS requests on port 5300.

pdns_service_overrides:
  User: "{{ pdns_user }}"
  Group: "{{ pdns_group }}"

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

pdns_backends_packages: "{{ default_pdns_backends_packages }}"
pdns_backends_packages_state: "{{ pdns_package_state }}"
pdns_backends:
  bind:
    config: '/dev/null'

Dictionary declaring all the backends you'd like to enable. You can use multiple backends of the same kind by using the {backend}:{instance_name} syntax. For example:

pdns_backends:
  'gmysql:one':
    'user': root
    'host': 127.0.0.1
    'password': root
    'dbname': pdns
  'gmysql:two':
    'user': pdns_user
    'host': 192.0.2.15
    'password': my_password
    'dbname': dns
  'bind':
    'config': '/etc/named/named.conf'
    'hybrid': true
    'dnssec-db': '{{ pdns_config_dir }}/dnssec.db'

By default this role starts just the bind-backend with an empty config file. pdns_backends_packages_state controls install/update/removal of backend packages.

pdns_config_additional_dirs: []

Optional list of directories created before pdns_config_files are copied. Each item can be either a path string or an object with path, owner, group, mode. For example:

pdns_config_additional_dirs:
  - path: "{{ pdns_config['include-dir'] }}"
    mode: "0775"
  - "{{ pdns_config_dir }}/zones"
  - "/var/lib/powerdns/rpz"

pdns_config_files: []

Optional list of files copied before the service is started. Each item must define dest and one of src or content. dest can be absolute or relative to pdns_config_dir. Executable backend helper scripts should be shipped via this variable too (for example with mode: "0750"). For example:

pdns_config_files:
  - src: files/pdns/named.conf
    dest: named.conf
    mode: "0640"
  - dest: pipe-backend.py
    mode: "0750"
    content: |
      #!/usr/bin/env python3
      print("example")

pdns_mysql_manage_database: true
pdns_mysql_databases_credentials: {}
pdns_mysql_query_use_socket: false
pdns_mysql_unix_socket: "/var/run/mysqld/mysqld.sock"
pdns_backends_mysql_cmd: "{{ default_pdns_backends_mysql_cmd }}"
pdns_mysql_cli_extra_args: "{{ default_pdns_mysql_cli_extra_args }}"
pdns_mysql_auth_plugin: ""
pdns_mysql_user_update_password: ""
pdns_mysql_packages: "{{ default_pdns_mysql_packages }}"
pdns_mysql_packages_state: "present"

pdns_mysql_manage_database controls whether this role performs MySQL/MariaDB bootstrap operations (database creation, user/grants management and schema checks/import). Set it to false for config-only mode.

Administrative credentials for the MySQL backend used to create the PowerDNS Authoritative Server databases and users. For example:

pdns_mysql_databases_credentials:
  'gmysql:one':
    'priv_user': root
    'priv_password': my_first_password
    'priv_host':
      - "localhost"
      - "%"
  'gmysql:two':
    'priv_user': someprivuser
    'priv_password': my_second_password
    'priv_host':
      - "localhost"

Notice that this must only contain the credentials for the gmysql backends provided in pdns_backends.

When pdns_mysql_query_use_socket is set to true, role-internal MySQL operations (database/user creation and schema load checks/import) use the UNIX socket path defined by pdns_mysql_unix_socket instead of TCP host/port. pdns_backends_mysql_cmd and pdns_mysql_cli_extra_args control the MySQL/MariaDB CLI invocation used for schema checks/import. pdns_mysql_packages allows overriding OS-specific MySQL dependency package lists. pdns_mysql_packages_state controls install/update/removal of those dependency packages.

pdns_pgsql_manage_database: true
pdns_pgsql_databases_credentials: {}
pdns_pgsql_packages: "{{ default_pdns_pgsql_packages }}"
pdns_pgsql_packages_state: "present"

pdns_pgsql_manage_database controls whether this role performs PostgreSQL bootstrap operations (database/user creation and schema checks/import). Set it to false for config-only mode.

Administrative credentials for the PostgreSQL backend used to create the PowerDNS Authoritative Server databases and users. For example:

pdns_pgsql_databases_credentials:
  'gpgsql:one':
    priv_user: postgres
    priv_password: my_first_password

Notice that this must only contain the credentials for the gpgsql backends provided in pdns_backends.

pdns_pgsql_query_use_socket: false
pdns_pgsql_unix_socket: "/var/run/postgresql"

When pdns_pgsql_query_use_socket is set to true, role-internal PostgreSQL operations (database/user creation and schema load checks/import) use the UNIX socket path defined by pdns_pgsql_unix_socket instead of TCP host/port. pdns_pgsql_packages allows overriding OS-specific PostgreSQL dependency package lists. pdns_pgsql_packages_state controls install/update/removal of those dependency packages.

pdns_sqlite_databases_locations: []

Locations of the SQLite3 databases that have to be created if using the gsqlite3 backend.

pdns_sqlite_package_state: "present"

Desired package state for the SQLite CLI dependency used during schema bootstrap.

pdns_lmdb_databases_locations: []

Locations of the LMDB databases that have to be created if using the lmdb backend.

Locations of the mysql, pgsql and sqlite3 base schema. When set, this value is used and they are not automatically detected.

pdns_mysql_schema_load: true
pdns_mysql_schema_file: ''
pdns_mysql_schema_on_first_node_only: true

pdns_pgsql_schema_load: true
pdns_pgsql_schema_file: ''
pdns_pgsql_schema_on_first_node_only: true

pdns_sqlite_schema_file: ''

pdns_mysql_schema_load and pdns_pgsql_schema_load only control schema check/import tasks. When SQL bootstrap is enabled (pdns_mysql_manage_database / pdns_pgsql_manage_database) and administrative credentials are provided, user/database creation still runs even if schema load is disabled.

pdns_mysql_schema_on_first_node_only and pdns_pgsql_schema_on_first_node_only control cluster bootstrap execution for shared SQL backends (database/user/grants/schema import).

pdns_verbose: "{{ ansible_verbosity | int >= 2 }}"

Enable verbose/debug role behavior. This currently controls whether sensitive SQL task details are hidden in logs (false) or visible for troubleshooting (true).

Role Tags

This role uses the following standard tags so filtered runs stay predictable with --tags / --skip-tags:

• install: package/module installation or software provisioning.
• config: configuration/state changes (templates, files, directories, settings, data bootstrap).
• service: service state management and service-related handlers.
• repository: repository/key/pinning setup and repository cache refresh.

Some prerequisite tasks intentionally have multiple tags (for example install + repository, or install + config) so filtered runs include the dependencies required by the selected path.

Example Playbooks

Run as a primary using the bind backend (when you already have a named.conf file):

- hosts: ns1.example.net
  roles:
    - { role: PowerDNS.pdns }
  vars:
    pdns_config:
      primary: true
      local-address: '192.0.2.53'
    pdns_backends:
      bind:
        config: '/etc/named/named.conf'

Install the latest '50' build of PowerDNS Authoritative Server enabling the MySQL backend. Provides also the MySQL administrative credentials to automatically create and initialize the PowerDNS Authoritative Server user and database:

- hosts: ns2.example.net
  roles:
    - { role: PowerDNS.pdns }
  vars:
    pdns_config:
      primary: true
      secondary: false
      local-address: '192.0.2.77'
    pdns_backends:
      gmysql:
        host: 192.0.2.120
        port: 3306
        user: powerdns
        password: P0w3rDn5
        dbname: pdns
    pdns_mysql_databases_credentials:
      gmysql:
        priv_user: root
        priv_password: myrootpass
        priv_host:
          - "%"
    pdns_install_repo: "{{ pdns_auth_powerdns_repo_50 }}"

NOTE: In this case the role will use the credentials provided in pdns_mysql_databases_credentials to automatically create and initialize the user (user, password) and database (dbname) connecting to the MySQL server (host, port).

Configure PowerDNS Authoritative Server in 'primary' mode reading zones from two different PostgreSQL databases:

- hosts: ns2.example.net
  roles:
    - { role: PowerDNS.pdns }
  vars:
    pdns_config:
      primary: true
      local-port: 5300
      local-address: '192.0.2.111'
    pdns_backends:
      'gpgsql:serverone':
        host: 192.0.2.124
        user: powerdns
        password: P0w3rDn5
        dbname: pdns2
      'gpgsql:otherserver':
        host: 192.0.2.125
        user: root
        password: root
        dbname: dns

Configure PowerDNS Authoritative Server to run with the gsqlite3 backend. The SQLite database will be created and initialized by the role in the location specified by the database_name variable.

- hosts: ns4.example.net
  roles:
    - { role: PowerDNS.pdns }
  vars:
    database_name: '/var/lib/powerdns/pdns.sqlite3'
    pdns_config:
      primary: true
      secondary: false
      local-address: '192.0.2.73'
    pdns_backends:
      gsqlite3:
        database: "{{ database_name }}"
        dnssec: true
    pdns_sqlite_databases_locations:
      - "{{ database_name }}"

Changelog

A detailed changelog of all the changes applied to the role is available here.

Testing

Tests are performed by Molecule.

$ pip install tox

To test all the scenarios run

$ tox

To run a custom molecule command

$ tox -e ansible216 -- molecule test -s pdns-50

The Molecule backend matrix validates LMDB, SQLite3, MySQL, MariaDB, BIND and PostgreSQL instance profiles.

License

MIT