kpfleming.powerdns_auth.zone module – Manages a zone in a PowerDNS Authoritative server

Note

This module is part of the kpfleming.powerdns_auth collection (version 24.3.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install kpfleming.powerdns_auth. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: kpfleming.powerdns_auth.zone.

Synopsis 

This module allows a task to manage the presence and configuration of a zone in a PowerDNS Authoritative server.

Requirements 

The below requirements are needed on the host that executes this module.

bravado

Parameters 

Parameter	Comments
api_key string / required	Key (token) used to authenticate to the API endpoint in the server.
api_spec_path string	Path of the OpenAPI (Swagger) API spec document in `api_url`. Default: `"/api/docs"`
api_url string	URL of the API endpoint in the server. Default: `"http://localhost:8081"`
metadata dictionary	Zone metadata. Ignored when `state=exists`, `state=absent`, `state=notify`, or `state=retrieve`.
allow_axfr_from list / elements=string	List of IPv4 and/or IPv6 subnets (or the special value AUTO-NS) from which AXFR requests will be accepted.
allow_dnsupdate_from list / elements=string	List of IPv4 and/or IPv6 subnets from which DNSUPDATE requests will be accepted.
also_notify list / elements=string	List of IPv4 and/or IPv6 addresses (with optional port numbers) which will receive NOTIFY for updates.
api_rectify boolean	Rectify zone’s record sets after changes made through the API. Choices: `false` `true`
axfr_master_tsig list / elements=string	List of TSIG keys used to validate NOTIFY requests from zone masters and to sign AXFR/IXFR requests to zone masters. Note: only the first key in the list will be used.
axfr_source string	IPv4 or IPv6 address to be used as the source address for AXFR and IXFR requests.
forward_dnsupdate boolean	Forward DNSUPDATE requests to one of the zone’s masters. Choices: `false` `true`
gss_acceptor_principal string	Kerberos/GSS principal which identifies this server.
gss_allow_axfr_principal string	Kerberos/GSS principal which must be included in AXFR requests.
ixfr boolean	Attempt IXFR when retrieving zone updates. Choices: `false` `true`
notify_dnsupdate boolean	Send a NOTIFY to all slave servers after processing a DNSUPDATE request. Choices: `false` `true`
nsec3narrow boolean	Indicates that this zone operations in NSEC3 ‘narrow’ mode. Choices: `false` `true`
nsec3param string	NSEC3 parameters for the zone when DNSSEC is used.
publish_cdnskey boolean	Publish CDNSKEY records of the KSKs for the zone. Choices: `false` `true`
publish_cds list / elements=string	List of signature algorithm numbers for CDS records of the KSKs for the zone.
slave_renotify boolean	Re-send NOTIFY to slaves after receiving AXFR from master. If this is not set, the ‘slave-renotify’ setting in the server configuration will be applied to the zone. Choices: `false` `true`
soa_edit string	Method to update the serial number in the SOA record when serving it. Choices: `"INCREMENT-WEEKS"` `"INCEPTION-EPOCH"` `"INCEPTION-INCREMENT"` `"EPOCH"` `"NONE"`
soa_edit_api string	Method to update the serial number in the SOA record after an API edit. Choices: `"DEFAULT"` ← (default) `"INCREASE"` `"EPOCH"` `"SOA-EDIT"` `"SOA-EDIT-INCREASE"`
soa_edit_dnsupdate string	Method to update the serial number in the SOA record after a DNSUPDATE. Choices: `"DEFAULT"` ← (default) `"INCREASE"` `"EPOCH"` `"SOA-EDIT"` `"SOA-EDIT-INCREASE"`
tsig_allow_axfr list / elements=string	List of TSIG keys used to sign NOTIFY requests and to validate AXFR/IXFR requests. Note: only the first key in the list will be used.
tsig_allow_dnsupdate list / elements=string	List of TSIG keys for which DNSUPDATE requests will be accepted.
name string / required	Name of the zone to be managed.
properties dictionary	Zone properties. Ignored when `state=exists`, `state=absent`, `state=notify`, or `state=retrieve`.
account string	Optional string used for local policy.
catalog string	Optional zone name, indicating that this zone should be a member of the specified catalog zone. Must be an absolute zone name (ending with ‘.’). Only supported in server version 4.7.0 or later.
kind string / required	Zone kind. `Producer` and `Consumer` are only supported in server version 4.7.0 or later. Choices: `"Native"` `"Master"` `"Slave"` `"Producer"` `"Consumer"`
master_tsig_key_ids list / elements=string	The id of the TSIG keys used for master operation in this zone. Only used when `properties.kind=Master` or `properties.kind=Producer`.
masters list / elements=string	List of IPv4 or IPv6 addresses which are masters for this zone. Only used when `properties.kind=Slave` or `properties.kind=Consumer`.
nameservers list / elements=string	List of nameserver names to be listed in NS records for zone. Only used when `properties.kind=Native`, `properties.kind=Master`, or `properties.kind=Producer`. Only used when zone is being created (`state=present` and zone is not present). Must be absolute names (ending with ‘.’).
rrsets list / elements=dictionary	Resource Record Set. Only used when `properties.kind=Native`, `properties.kind=Master`, or `properties.kind=Producer`. Only used when zone is being created (`state=present` and zone is not present). SOA and NS records are not permitted.
name string / required	Name for record set (e.g. “www.powerdns.com.”). Must be absolute names (ending with ‘.’).
records list / elements=dictionary / required	Represents a list of records.
content string / required	The content of resource record.
disabled boolean	Whether or not this record is disabled. Choices: `false` ← (default) `true`
ttl integer	TTL of the records, in seconds. Default: `3600`
type string / required	Type of resource record (e.g. “A”, “PTR”, “MX”).
slave_tsig_key_ids list / elements=string	The id of the TSIG keys used for slave operation in this zone. Only used when `properties.kind=Slave` or `properties.kind=Consumer`.
soa dictionary	SOA record fields. Only used when `properties.kind=Native`, `properties.kind=Master`, or `properties.kind=Producer`. Only used when zone is being created (`state=present` and zone is not present).
expire integer	Number of seconds after which secondary name servers should stop answering requests for this zone if the primary does not respond. Must be bigger than the sum of `properties.soa.refresh` and `properties.soa.retry`. Default: `3600000`
mname string / required	DNS name (absolute, ending with ‘.’) of primary name server for the zone.
refresh integer	Number of seconds after which secondary name servers should query the primary for the SOA record, to detect zone changes. Default: `86400`
retry integer	Number of seconds after which secondary name servers should retry to request the serial number from the primary if the primary does not respond. Must be less than `properties.soa.refresh`. Default: `7200`
rname string / required	Email address of the ‘responsible party’ for the zone, formatted as a DNS name (absolute, ending with ‘.’).
serial integer	Initial serial number. Default: `1`
ttl integer	Time to live for purposes of negative caching. Default: `172800`
ttl integer	Time to live for SOA and NS records. Only used when `properties.kind=Native`, `properties.kind=Master`, or `properties.kind=Producer`. Only used when zone is being created (`state=present` and zone is not present). Default: `86400`
server_id string	ID of the server instance which holds the key. Default: `"localhost"`
state string	If `present` the zone will be created if necessary; if it already exists, its configuration will be updated to match the provided properties. If `absent` the zone will be removed it if exists. If `exists` the zone’s existence will be checked, but it will not be modified. Any configuration properties provided will be ignored. If `notify` and `properties.kind=Master`, then NOTIFY will be sent to the zone’s slaves. If `notify` and `properties.kind=Slave`, then the slave zone will be updated as if a NOTIFY had been received. If `retrieve` and `properties.kind=Slave`, then the slave zone will be retrieved from the master. Choices: `"present"` ← (default) `"absent"` `"exists"` `"notify"` `"retrieve"`

Examples 

%YAML 1.2
---
- name: check that zone exists
  pdns_auth_zone:
    name: d1.example.
    state: exists
    api_key: 'foobar'

- name: check that zone exists on a non-default server
  pdns_auth_zone:
    name: d1.example.
    state: exists
    api_key: 'foobar'
    api_url: 'http://pdns.server.example:80'

- name: send NOTIFY to slave servers for zone
  pdns_auth_zone:
    name: d1.example.
    state: notify
    api_key: 'foobar'

- name: retrieve zone from master server
  pdns_auth_zone:
    name: d1.example.
    state: retrieve
    api_key: 'foobar'

- name: create native zone
  pdns_auth_zone:
    name: d2.example.
    state: present
    api_key: 'foobar'
    properties:
      kind: 'Native'
      nameservers:
        - 'ns1.example.'
      soa:
        mname: 'localhost.'
        rname: 'hostmaster.localhost.'
    metadata:
      allow_axfr_from: ['AUTO-NS']
      axfr_source: '127.0.0.1'

- name: change native zone to master
  pdns_auth_zone:
    name: d2.example.
    state: present
    api_key: 'foobar'
    properties:
      kind: 'Master'

- name: delete zone
  pdns_auth_zone:
    name: d2.example.
    state: absent
    api_key: 'foobar'

- name: create slave zone
  pdns_auth_zone:
    name: d3.example.
    state: present
    api_key: 'foobar'
    properties:
      kind: 'Slave'
      masters:
        - '1.1.1.1'
        - '::1'

Return Values 

Common return values are documented here, the following are the fields unique to this module:

Key	Description
zone dictionary	Information about the zone Returned: always
account string	Account label Returned: always
catalog string	Name of catalog zone containing this zone Returned: when present
dnssec boolean	Flag indicating whether zone is signed with DNSSEC Returned: when present
exists boolean	Indicate whether the zone exists Returned: always
kind string	Kind Returned: when present Can only return: `"Native"` `"Master"` `"Slave"` `"Producer"` `"Consumer"`
master_tsig_key_ids list / elements=string	The id of the TSIG keys used for master operation in this zone. Returned: when present
masters list / elements=string	IP addresses of masters (only for Slave and Consumer zones) Returned: when present
metadata dictionary	Zone metadata Returned: when present
allow_axfr_from list / elements=string	List of IPv4 and/or IPv6 subnets (or the special value AUTO-NS) from which AXFR requests will be accepted. Returned: success
allow_dnsupdate_from list / elements=string	List of IPv4 and/or IPv6 subnets from which DNSUPDATE requests will be accepted. Returned: success
also_notify list / elements=string	List of IPv4 and/or IPv6 addresses (with optional port numbers) which will receive NOTIFY for updates. Returned: success
api_rectify boolean	Rectify zone’s record sets after changes made through the API. Returned: success
axfr_master_tsig list / elements=string	List of TSIG keys used to validate NOTIFY requests from zone masters and to sign AXFR/IXFR requests to zone masters. Returned: success
axfr_source string	IPv4 or IPv6 address to be used as the source address for AXFR and IXFR requests. Returned: success
forward_dnsupdate boolean	Forward DNSUPDATE requests to one of the zone’s masters. Returned: success
gss_acceptor_principal string	Kerberos/GSS principal which identifies this server. Returned: success
gss_allow_axfr_principal string	Kerberos/GSS principal which must be included in AXFR requests. Returned: success
ixfr boolean	Attempt IXFR when retrieving zone updates. Returned: success
lua_axfr_script string	Script to be used to edit incoming AXFR requests; use ‘NONE’ to override a globally configured script. Returned: success
notify_dnsupdate boolean	Send a NOTIFY to all slave servers after processing a DNSUPDATE request. Returned: success
nsec3narrow boolean	Indicates that this zone operations in NSEC3 ‘narrow’ mode. Returned: success
nsec3param string	NSEC3 parameters for the zone when DNSSEC is used. Returned: success
presigned boolean	Indicates that this zone zone carries DNSSEC RRSIGs, and is presigned. Returned: success
publish_cdnskey boolean	Publish CDNSKEY records of the KSKs for the zone. Returned: success
publish_cds list / elements=string	List of signature algorithm numbers for CDS records of the KSKs for the zone. Returned: success
slave_renotify boolean	Re-send NOTIFY to slaves after receiving AXFR from master. Returned: success
soa_edit string	Method to update the serial number in the SOA record when serving it. Returned: success Can only return: `"INCREMENT-WEEKS"` `"INCEPTION-EPOCH"` `"INCEPTION-INCREMENT"` `"EPOCH"` `"NONE"`
soa_edit_api string	Method to update the serial number in the SOA record after an API edit. Returned: success Can only return: `"DEFAULT"` `"INCREASE"` `"EPOCH"` `"SOA-EDIT"` `"SOA-EDIT-INCREASE"`
soa_edit_dnsupdate string	Method to update the serial number in the SOA record after a DNSUPDATE. Returned: success Can only return: `"DEFAULT"` `"INCREASE"` `"EPOCH"` `"SOA-EDIT"` `"SOA-EDIT-INCREASE"`
tsig_allow_axfr list / elements=string	List of TSIG keys used to sign NOTIFY requests and to validate AXFR/IXFR requests. Returned: success
tsig_allow_dnsupdate list / elements=string	List of TSIG keys for which DNSUPDATE requests will be accepted. Returned: success
name string	Name Returned: always
serial integer	Serial number from SOA record Returned: when present
slave_tsig_key_ids list / elements=string	The id of the TSIG keys used for slave operation in this zone. Returned: when present

Authors

Kevin P. Fleming (@kpfleming)

kpfleming.powerdns_auth.zone module – Manages a zone in a PowerDNS Authoritative server

Synopsis

Requirements

Parameters

Examples

Return Values