community.dns.lookup_rfc8427 lookup – Look up DNS records and return RFC 8427 JSON format

Note

This lookup plugin is part of the community.dns collection (version 3.4.0).

You might already have this collection installed if you are using the ansible package. 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 community.dns. You need further requirements to be able to use this lookup plugin, see Requirements for details.

To use it in a playbook, specify: community.dns.lookup_rfc8427.

New in community.dns 3.4.0

Synopsis

Requirements

The below requirements are needed on the local controller node that executes this lookup.

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

Terms

Parameter

Comments

Terms

list / elements=string / required

Domain name(s) to query.

Keyword parameters

This describes keyword parameters of the lookup. These are the values key1=value1, key2=value2 and so on in the following examples: lookup('community.dns.lookup_rfc8427', key1=value1, key2=value2, ...) and query('community.dns.lookup_rfc8427', key1=value1, key2=value2, ...)

Parameter

Comments

nxdomain_handling

string

How to handle NXDOMAIN errors. These appear if an unknown domain name is queried.

empty (default) returns an empty result for that domain name. This means that for the corresponding domain name, nothing is added to _result.

fail makes the lookup fail.

Choices:

  • "empty" ← (default)

  • "fail"

query_retry

integer

Number of retries for DNS query timeouts.

Default: 3

query_timeout

float

Timeout per DNS query in seconds.

Default: 10.0

boolean

If false, the input is assumed to be an absolute domain name.

If true, the input is assumed to be a relative domain name if it does not end with ., the search list configured in the system’s resolver configuration will be used for relative names, and the resolver’s domain may be added to relative names.

Choices:

  • false

  • true ← (default)

server

list / elements=string

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.

servfail_retries

integer

How often to retry on SERVFAIL errors.

Default: 0

type

string

The record type to retrieve.

Support for HTTPS and SVCB has been added in community.dns 3.4.0.

Choices:

  • "A" ← (default)

  • "AAAA"

  • "CAA"

  • "CNAME"

  • "DNAME"

  • "DNSKEY"

  • "DS"

  • "HINFO"

  • "HTTPS"

  • "LOC"

  • "MX"

  • "NAPTR"

  • "NS"

  • "NSEC"

  • "NSEC3"

  • "NSEC3PARAM"

  • "PTR"

  • "RP"

  • "RRSIG"

  • "SOA"

  • "SPF"

  • "SRV"

  • "SSHFP"

  • "SVCB"

  • "TLSA"

  • "TXT"

Notes

Note

  • When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters: lookup('community.dns.lookup_rfc8427', term1, term2, key1=value1, key2=value2) and query('community.dns.lookup_rfc8427', term1, term2, key1=value1, key2=value2)

  • This plugin returns DNS messages in RFC 8427 JSON format, which includes Header, Question, Answer, Authority, and Additional sections.

  • Note that when using this lookup plugin with lookup(), and the result is a one-element list, Ansible simply returns the one element not as a list. Since this behavior is surprising and can cause problems, it is better to use query() instead of lookup(). See the examples and also Forcing lookups to return lists in the Ansible documentation.

Examples

- name: Look up A (IPv4) records for example.org in RFC 8427 JSON format
  ansible.builtin.debug:
    msg: "{{ query('community.dns.lookup_rfc8427', 'example.org.') }}"

- name: Look up AAAA (IPv6) records for example.org in RFC 8427 JSON format
  ansible.builtin.debug:
    msg: "{{ query('community.dns.lookup_rfc8427', 'example.org.', type='AAAA' ) }}"

- name: Get complete DNS message for MX records
  ansible.builtin.debug:
    msg: "{{ query('community.dns.lookup_rfc8427', 'example.org.', type='MX' ) }}"

Return Value

Key

Description

Return value

list / elements=dictionary

DNS messages in RFC 8427 JSON format for all queried DNS names.

Every element in _terms corresponds to one element in this list.

Returned: success

Sample: [{"Additional": [], "Answer": [{"TTL": 3600, "class": 1, "data": "93.184.216.34", "name": "example.org.", "type": 1}], "Authority": [], "Header": {"AA": false, "AD": false, "ANCOUNT": 1, "ARCOUNT": 0, "CD": false, "ID": 12345, "NSCOUNT": 0, "Opcode": 0, "QDCOUNT": 1, "QR": true, "RA": true, "RD": true, "Rcode": 0, "TC": false}, "Question": [{"class": 1, "name": "example.org.", "type": 1}]}]

Authors

  • Felix Fontein (@felixfontein)

  • Vasiliy Kiryanov (@vasiliyk)