Getting started

Default configuration

At the moment the role does not configure Unbound after installation and relies on the OS distribution package to provide sensible defaults (custom configuration can still be set using provided variables). The focus of this role is to provide a local, secure DNSSEC validation; more advanced DNS features should be served by a dedicated DNS authoritative service.

Usage with internal RFC 1918 private networks

This role does not configure any upstream DNS servers by default (for example Google DNS servers). This means that Unbound will try and resolve DNS and DNSSEC queries by itself, using the locally provided DNS root keys for DNSSEC verification. On the Debian/Ubuntu hosts, when the unbound service starts, it replaces the currently configured DNS servers with itself, using the resolvconf package.

This means that any private networks the host is connected to won't be resolvable anymore. If the default FQDN of the host is in a private network, the host's hostname and domain won't be resolvable either - this affects sudo and Ansible operation, among other things.

To avoid that, as long as you have configured local DNS nameserver for an internal domain with revDNS records, for example dnsmasq, you can add your private network as an insecure, transparent DNS zone:

unbound__zones:

  - name:       'internal-network'
    zone:       'nat.example.org.'
    revdns:     '192.0.2.0/24'
    nameserver: '192.0.2.1'

The above configuration will tell Unbound to forward all DNS queries for nat.example.org. and 0.2.0.192.in-addr.arpa. DNS zones to the 192.0.2.1 nameserver.

If the specified revdns subnet is in the private IP address range (RFC 1918), the configuration template will make sure that the specified subnet and domain zones are configured as transparent, which will tell Unbound to serve the responses from the upstream DNS server as usual. These zones will also be marked as insecure, to avoid issues with DNSSEC validation.

It's possible to use a bigger subnet size than /24 - subnets between /16 and /24 will have multiple /24 reverse DNS zones pointed to the specified nameserver. Bigger subnets however currently don't work correctly due to the netaddr Python library used to generate the correct DNS zone names using only class C addresses (/24 CIDR subnets).

Example inventory

The install and configure Unbound on a host, it needs to be present in the [debops_service_unbound] Ansible inventory group:

[debops_service_unbound]
hostname

Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.unbound role:

---

- name: Manage Unbound, local DNS resolver
  hosts: [ 'debops_service_unbound' ]
  become: True

  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'

  roles:

    - role: debops.apt_preferences
      tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
      apt_preferences__dependent_list:
        - '{{ unbound__apt_preferences__dependent_list }}'

    - role: debops.python
      tags: [ 'role::python', 'skip::python' ]
      python__dependent_packages3:
        - '{{ unbound__python__dependent_packages3 }}'
      python__dependent_packages2:
        - '{{ unbound__python__dependent_packages2 }}'

    - role: debops.etc_services
      tags: [ 'role::etc_services', 'skip::etc_services' ]
      etc_services__dependent_list:
        - '{{ unbound__etc_services__dependent_list }}'

    - role: debops.unbound
      tags: [ 'role::unbound', 'skip::unbound' ]

Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::unbound
Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.