DNS - Unbound - Domain Override
STATE: stable
TESTS: Playbook
API Docs: Core - Unbound
Service Docs: Unbound
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.
Warning
Unbound service actions like reload
can take long. Please be aware of the possible downtime!
You may also need to increase the module timeout
.
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'
# reload: true
# 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
ansibleguy.opnsense.list:
# target: 'unbound_domain'
register: existing_entries
- name: Printing domains
ansible.builtin.debug:
var: existing_entries.data