Tip

DNS - Unbound - Domain Override

STATE: stable

Service Docs: Unbound

Definition

Definition
Parameter	Type	Required	Default	Aliases	Comment
match_fields	string	false	[‘domain’, ‘server’]	-	Fields that are used to match configured domain-overrides with the running config - if any of those fields are changed, the module will think it’s a new entry. At least one of: ‘domain’, ‘server’, ‘description’
domain	string	true	-	dom, d	Domain to override
server	string	true	-	value, srv	IP address of the authoritative DNS server for this domain. To use a non-default port for communication, append an ‘@’ with the port number
description	string	false	-	desc	Optional description for the domain-override. Could be used as unique-identifier when set as only ‘match_field’.
reload	boolean	false	true	-	If the running config should be reloaded on change - this may take some time. For mass-managing items you might want to reload it ‘manually’ after all changes are done => using the ansibleguy.opnsense.reload module.

For basic parameters see: Basic

Info

This module manages DNS domain-overrides configuration that can be found in the WEB-UI menu: ‘Services - Unbound DNS - Overrides - Domain overrides’

Entries like these override an entire domain by specifying an authoritative DNS server to be queried for that domain.

Usage

First you will have to know about domain-matching.

The module somehow needs to link the configured and existing domain-overrides to manage them.

You can to set how this matching is done by setting the ‘match_fields’ parameter!

The default behaviour is that a domain-override is matched by its ‘domain’ and ‘server’ fields.

However - it is recommended to use/set ‘description’ as unique identifier if many overrides are used.

Mass-Manage

If you are mass-managing DNS records or using DNS-Blocklists - you might want to disable reload: false on single module-calls!

This takes a long time, as the service gets reloaded every time!

You might want to reload it ‘manually’ after all changes are done => using the ansibleguy.opnsense.reload module

Examples

- hosts: localhost
  gather_facts: no
  module_defaults:
    group/ansibleguy.opnsense.all:
      firewall: 'opnsense.template.ansibleguy.net'
      api_credential_file: '/home/guy/.secret/opn.key'

    ansibleguy.opnsense.unbound_domain:
      match_fields: ['description']

    ansibleguy.opnsense.list:
      target: 'unbound_domain'

  tasks:
    - name: Example
      ansibleguy.opnsense.unbound_domain:
        domain: 'opnsense.template.ansibleguy.net'
        server: '192.168.0.1'
        # match_fields: ['description']
        # description: 'example'
        # state: 'present'
        # enabled: true
        # debug: false

    - name: Adding
      ansibleguy.opnsense.unbound_domain:
        domain: 'opnsense.template.ansibleguy.net'
        server: '192.168.0.1'
        match_fields: ['description']
        description: 'test1'
        # match_fields: ['description']

    - name: Disabling
      ansibleguy.opnsense.unbound_domain:
        domain: 'opnsense.template.ansibleguy.net'
        server: '192.168.0.1'
        match_fields: ['description']
        description: 'test1'
        enabled: false
        # match_fields: ['description']

    - name: Removing
      ansibleguy.opnsense.unbound_domain:
        domain: 'opnsense.template.ansibleguy.net'
        server: '192.168.0.1'
        state: 'absent'
        description: 'test1'
        # match_fields: ['description']

    - name: Listing domains
      ansibleguy.opnsense.list:
      #  target: 'unbound_domain'
      register: existing_entries

    - name: Printing entries
      ansible.builtin.debug:
        var: existing_entries.data