felixfontein.tools.wait_for_txt – Wait for TXT entries to be available on all authoritative nameservers

Note

This plugin is part of the felixfontein.tools collection (version 1.4.1).

To install it use: ansible-galaxy collection install felixfontein.tools.

To use it in a playbook, specify: felixfontein.tools.wait_for_txt.

New in version 1.4.0: of felixfontein.tools

Synopsis

  • Wait for TXT entries with specific values to show up on all authoritative nameservers for the DNS name.

Requirements

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

  • dnspython >= 1.15.0 (maybe older versions also work)

Parameters

Parameter Choices/Defaults Comments
always_ask_default_resolver
boolean
    Choices:
  • no
  • yes ←
When set to true (default), will use the default resolver to find the authoritative nameservers of a subzone.
When set to false, will use the authoritative nameservers of the parent zone to find the authoritative nameservers of a subzone. This only makes sense when the nameservers were recently changed and haven't propagated.
max_sleep
float
Default:
10
Maximal amount of seconds to sleep between two rounds of probing the TXT records.
query_retry
integer
Default:
3
Number of retries for DNS query timeouts.
query_timeout
float
Default:
10
Timeout per DNS query in seconds.
records
list / elements=dictionary / required
A list of DNS names with TXT entries to look out for.
mode
string
    Choices:
  • subset ←
  • superset
  • superset_not_empty
  • equals
  • equals_ordered
Comparison modes for the values in values.
If subset, values should be a (not necessarily proper) subset of the TXT values set for the DNS name.
If superset, values should be a (not necessarily proper) superset of the TXT values set for the DNS name. This includes the case that no TXT entries are set.
If superset_not_empty, values should be a (not necessarily proper) superset of the TXT values set for the DNS name, assuming at least one TXT record is present.
If equals, values should be the same set of strings as the TXT values for the DNS name (up to order).
If equals_ordered, values should be the same ordered list of strings as the TXT values for the DNS name.
name
string / required
A DNS name, like www.example.com.
values
list / elements=string / required
The TXT values to look for.
timeout
float
Global timeout for waiting for all records in seconds.
If not set, will wait indefinitely.

Examples

- name: Wait for a TXT entry to appear
  felixfontein.tools.wait_for_txt:
    records:
      # We want that www.example.com has a single TXT record with value 'Hello world!'.
      # There should not be any other TXT record for www.example.com.
      - name: www.example.com
        values: "Hello world!"
        mode: equals
      # We want that example.com has a specific SPF record set.
      # We do not care about other TXT records.
      - name: www.example.com
        values: "v=spf1 a mx -all"
        mode: subset

Return Values

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

Key Returned Description
completed
integer
always
How many of the checks were completed.

Sample:
3
records
list / elements=dictionary
always
Results on the TXT records queried.
The entries are in a 1:1 correspondence to the entries of the records parameter, in exactly the same order.

Sample:
[{'check_count': 1, 'done': True, 'name': 'example.com', 'values': ['a', 'b', 'c']}, {'check_count': 0, 'done': False, 'name': 'foo.example.org'}]
 
check_count
integer
always
How often the TXT records for this DNS name were checked.

Sample:
3
 
done
boolean
always
Whether the check completed.
 
name
string
always
The DNS name this check is for.

Sample:
example.com
 
values
dictionary
lookup was done at least once
For every authoritative nameserver for the DNS name, lists the TXT records retrieved during the last lookup made.
Once the check completed for all TXT records retrieved, the TXT records for this DNS name are no longer checked.
If these are multiple TXT entries for a nameserver, the order is as it was received from that nameserver. This might not be the same order provided in the check.

Sample:
{'ns1.example.com': ['TXT value 1', 'TXT value 2'], 'ns2.example.com': ['TXT value 2']}


Authors

  • Felix Fontein (@felixfontein)