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.5.5).

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
Terms
Keyword parameters
Notes
Examples
Return Value

Synopsis

Look up DNS records and return them in RFC 8427 DNS message JSON format.
RFC 8427 defines a standardized format for representing DNS messages in JSON.

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`
search 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}]}]`

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)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/dns/lookup_rfc8427_lookup.html