Default variable details

some of debops.unbound default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

unbound__server

Configuration of the unbound__*_server variables is described in a separate document, Default variable details: unbound__server.

unbound__zones

The unbound__*_zones lists are used to configure forward or stub DNS zones published by Unbound service. Each DNS zone delegation is configured in its own /etc/unbound/unbound.conf.d/zone_<name>.conf configuration file.

Each list entry is a YAML dictionary with specific parameters:

name

Required. Name of the DNS zone, used in the filename. This parameter is used as an identifier during the variable parsing.

zone

Optional. If specified, this string will be used as the DNS zone name. With this parameter specified, name can be used as a general identifier of a particular delegation.

type

Optional. The zone type to use, either forward (default if not specified), local or stub. See the unbound.conf(5) for details about stub and forward zones.

local_zone_type

Optional. If the type parameter is set to local, this parameter can be used to define the type of the local zone (static (default), transparent, etc. See unbound.conf(5) manual page, local-zone: keyword for the details about local zone types.

local_zone_data

Optional. If the type parameter is set to local, this parameter can be used to define the data of a given local zone. This is a YAML list of entries, each entry can specify a DNS Resource Record as a string. See the examples section for an example local zone configuration.

nameserver, nameservers

Optional. IP address or list of IP addresses of the DNS nameservers of a particular zone. You can specify the port using the @ character, for example 192.0.2.1@5353.

revdns

Optional. Specify a CIDR subnet or multiple subnets for a given DNS zone. If specified, a revDNS zones will be included in the generated zone file; each revDNS zone will use the same nameserver IP addresses and other options specified for the main DNS zone. Currently only IPv4 C-class subnets (/16 to /24) are supported best.

If specified subnet is in a RFC 1918 private network range, the main DNS zone and revDNS zones will be set as local, insecure zones to avoid issues with DNSSEC. This can be overridden by setting the private_domain, domain_insecure and/or local_zone parameters to False.

state

Optional. If not specified or present, the zone file will be generated.

If absent, the configuration file will be removed.

If ignore, the given entry will not be evaluated by the role, and no changes will be done to the preceding parameters with the same name. This can be used to conditionally activate entries with different configuration.

If append, the given entry will be evaluated only if an entry with the same name already exists. The current state will not be changed.

comment

Optional. String or a YAML dictionary with additional comments for a given DNS zone.

options

Optional. List of configuration options for a particular zone. The format is the same as Default variable details: unbound__server configuration options. For a list of supported options, see the stub zone and forward zone sections of the unbound.conf(5) manual page.

server_options

Optional. List of server: configuration options associated with a particular zone. The format is the same as Default variable details: unbound__server configuration options.

Examples

Forward all queries to external Google DNS servers:

---

unbound__zones:

  # https://en.wikipedia.org/wiki/Google_Public_DNS
  - name: 'forward-all-to-google'
    comment: 'Forward all DNS queries to Google Public DNS'
    zone: '.'
    nameservers: [ '8.8.8.8', '8.8.4.4',
                   '2001:4860:4860::8888',
                   '2001:4860:4860::8844' ]

Create custom forward zone for internal network:

unbound__zones:

  - name: 'internal-net'
    zone: 'nat.example.org'
    revdns: '192.0.2.0/24'
    nameserver: '192.0.2.1'
    options:
      - 'forward-first': True

Define a local DNS entry example.test. with a few resource records:

unbound__zones:

  - name: 'example.test'
    zone: 'example.test.'
    type: 'local'
    local_zone_type: 'static'
    local_zone_data:
      - 'NS localhost.'
      - 'SOA localhost. nobody.invalid. 1 3600 1200 604800 10800'
      - 'PTR localhost.'
      - 'A 192.0.2.1'
      - 'AAAA 2001:db8::1'

Configure Unbound to support a stub DNS zone using an external DNS server, for example a home router with dnsmasq nameserver. Ensure that both normal and reverse lookups work as expected. The local zone is not signed with DNSSEC so we need to mark it as insecure.

unbound__zones:

  - name: 'example.net'
    zone: 'example.net.'
    type: 'stub'
    options:
      - 'stub-addr': '192.0.2.1'
    server_options:
      - 'domain-insecure': '"example.net"'
      - 'local-zone':      '"example.net." nodefault'

  - name: '2.0.192.in-addr.arpa'
    zone: '2.0.192.in-addr.arpa.'
    type: 'stub'
    options:
      - 'stub-addr': '192.0.2.1'
    server_options:
      - 'domain-insecure': '"2.0.192.in-addr.arpa."'
      - 'local-zone':      '"2.0.192.in-addr.arpa." nodefault'