community.dns.wait_for_txt (2.8.3) — module

Install collection

Install with ansible-galaxy collection install community.dns:==2.8.3

Add to requirements.yml

  collections:
    - name: community.dns
      version: 2.8.3

Description

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

Requirements

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

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Wait for a TXT entry to appear
  community.dns.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

Inputs

    
server:
    description:
    - The DNS server(s) to use to look up the result. Must be a list of one or more IP
      addresses.
    - By default, the system's standard resolver is used.
    elements: str
    type: list
    version_added: 2.7.0
    version_added_collection: community.dns

records:
    description:
    - A list of DNS names with TXT entries to look out for.
    elements: dict
    required: true
    suboptions:
      mode:
        choices:
        - subset
        - superset
        - superset_not_empty
        - equals
        - equals_ordered
        default: subset
        description:
        - Comparison modes for the values in O(records[].values).
        - If V(subset), O(records[].values) should be a (not necessarily proper) subset
          of the TXT values set for the DNS name.
        - If V(superset), O(records[].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 V(superset_not_empty), O(records[].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 V(equals), O(records[].values) should be the same set of strings as the TXT
          values for the DNS name (up to order).
        - If V(equals_ordered), O(records[].values) should be the same ordered list of
          strings as the TXT values for the DNS name.
        type: str
      name:
        description:
        - A DNS name, like V(www.example.com).
        required: true
        type: str
      values:
        description:
        - The TXT values to look for.
        elements: str
        required: true
        type: list
    type: list

timeout:
    description:
    - Global timeout for waiting for all records in seconds.
    - If not set, will wait indefinitely.
    type: float

max_sleep:
    default: 10
    description:
    - Maximal amount of seconds to sleep between two rounds of probing the TXT records.
    type: float

query_retry:
    default: 3
    description:
    - Number of retries for DNS query timeouts.
    type: int

query_timeout:
    default: 10
    description:
    - Timeout per DNS query in seconds.
    type: float

servfail_retries:
    default: 0
    description:
    - How often to retry on SERVFAIL errors.
    type: int
    version_added: 2.6.0
    version_added_collection: community.dns

always_ask_default_resolver:
    default: true
    description:
    - When set to V(true) (default), will use the default resolver to find the authoritative
      nameservers of a subzone. See O(server) for how to configure the default resolver.
    - When set to V(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 have not yet propagated.
    type: bool

Outputs

completed:
  description:
  - How many of the checks were completed.
  returned: always
  sample: 3
  type: int
records:
  contains:
    check_count:
      description:
      - How often the TXT records for this DNS name were checked.
      returned: always
      sample: 3
      type: int
    done:
      description:
      - Whether the check completed.
      returned: always
      sample: false
      type: bool
    name:
      description:
      - The DNS name this check is for.
      returned: always
      sample: example.com
      type: str
    values:
      description:
      - 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.
      elements: list
      returned: lookup was done at least once
      sample:
        ns1.example.com:
        - TXT value 1
        - TXT value 2
        ns2.example.com:
        - TXT value 2
      type: dict
  description:
  - Results on the TXT records queried.
  - The entries are in a 1:1 correspondence to the entries of the O(records) parameter,
    in exactly the same order.
  elements: dict
  returned: always
  sample:
  - check_count: 1
    done: true
    name: example.com
    values:
    - a
    - b
    - c
  - check_count: 0
    done: false
    name: foo.example.org
  type: list