community.general.dig – query DNS using the dnspython library

Note

This plugin is part of the community.general collection (version 3.8.1).

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.general.

To use it in a playbook, specify: community.general.dig.

Synopsis

  • The dig lookup runs queries against DNS servers to retrieve DNS records for a specific name (FQDN - fully qualified domain name). It is possible to lookup any DNS record in this manner.
  • There is a couple of different syntaxes that can be used to specify what record should be retrieved, and for which name. It is also possible to explicitly specify the DNS server(s) to use for lookups.
  • In its simplest form, the dig lookup plugin can be used to retrieve an IPv4 address (DNS A record) associated with FQDN
  • In addition to (default) A record, it is also possible to specify a different record type that should be queried. This can be done by either passing-in additional parameter of format qtype=TYPE to the dig lookup, or by appending /TYPE to the FQDN being queried.
  • If multiple values are associated with the requested record, the results will be returned as a comma-separated list. In such cases you may want to pass option wantlist=True to the plugin, which will result in the record values being returned as a list over which you can iterate later on.
  • By default, the lookup will rely on system-wide configured DNS servers for performing the query. It is also possible to explicitly specify DNS servers to query using the @DNS_SERVER_1,DNS_SERVER_2,…,DNS_SERVER_N notation. This needs to be passed-in as an additional parameter to the lookup

Requirements

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

Parameters

Parameter Choices/Defaults Configuration Comments
_terms
string
domain(s) to query
flat
string
Default:
1
If 0 each record is returned as a dictionary, otherwise a string
qtype
string
    Choices:
  • A
  • ALL
  • AAAA
  • CNAME
  • DNAME
  • DLV
  • DNSKEY
  • DS
  • HINFO
  • LOC
  • MX
  • NAPTR
  • NS
  • NSEC3PARAM
  • PTR
  • RP
  • RRSIG
  • SOA
  • SPF
  • SRV
  • SSHFP
  • TLSA
  • TXT
record type to query
retry_servfail
boolean
added in 3.6.0 of community.general
    Choices:
  • no
  • yes
Retry a nameserver if it returns SERVFAIL.

Notes

Note

  • ALL is not a record per-se, merely the listed fields are available for any record results you retrieve in the form of a dictionary.
  • While the ‘dig’ lookup plugin supports anything which dnspython supports out of the box, only a subset can be converted into a dictionary.
  • If you need to obtain the AAAA record (IPv6 address), you must specify the record type explicitly. Syntax for specifying the record type is shown in the examples below.
  • The trailing dot in most of the examples listed is purely optional, but is specified for completeness/correctness sake.

Examples

- name: Simple A record (IPV4 address) lookup for example.com
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.dig', 'example.com.')}}"

- name: "The TXT record for example.org."
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.dig', 'example.org.', 'qtype=TXT') }}"

- name: "The TXT record for example.org, alternative syntax."
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.dig', 'example.org./TXT') }}"

- name: use in a loop
  ansible.builtin.debug:
    msg: "MX record for gmail.com {{ item }}"
  with_items: "{{ lookup('community.general.dig', 'gmail.com./MX', wantlist=True) }}"

- ansible.builtin.debug:
    msg: "Reverse DNS for 192.0.2.5 is {{ lookup('community.general.dig', '192.0.2.5/PTR') }}"
- ansible.builtin.debug:
    msg: "Reverse DNS for 192.0.2.5 is {{ lookup('community.general.dig', '5.2.0.192.in-addr.arpa./PTR') }}"
- ansible.builtin.debug:
    msg: "Reverse DNS for 192.0.2.5 is {{ lookup('community.general.dig', '5.2.0.192.in-addr.arpa.', 'qtype=PTR') }}"
- ansible.builtin.debug:
    msg: "Querying 198.51.100.23 for IPv4 address for example.com. produces {{ lookup('dig', 'example.com', '@198.51.100.23') }}"

- ansible.builtin.debug:
    msg: "XMPP service for gmail.com. is available at {{ item.target }} on port {{ item.port }}"
  with_items: "{{ lookup('community.general.dig', '_xmpp-server._tcp.gmail.com./SRV', 'flat=0', wantlist=True) }}"

- name: Retry nameservers that return SERVFAIL
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.dig', 'example.org./A', 'retry_servfail=True') }}"

Return Values

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

Key Returned Description
_list
list / elements=any
success
List of composed strings or dictionaries with key and value If a dictionary, fields shows the keys returned depending on query type

A
string
success
address

AAAA
string
success
address

ALL
string
success
owner, ttl, type

CNAME
string
success
target

DLV
string
success
algorithm, digest_type, key_tag, digest

DNAME
string
success
target

DNSKEY
string
success
flags, algorithm, protocol, key

DS
string
success
algorithm, digest_type, key_tag, digest

HINFO
string
success
cpu, os

LOC
string
success
latitude, longitude, altitude, size, horizontal_precision, vertical_precision

MX
string
success
preference, exchange

NAPTR
string
success
order, preference, flags, service, regexp, replacement

NS
string
success
target

NSEC3PARAM
string
success
algorithm, flags, iterations, salt

PTR
string
success
target

RP
string
success
mbox, txt

SOA
string
success
mname, rname, serial, refresh, retry, expire, minimum

SPF
string
success
strings

SRV
string
success
priority, weight, port, target

SSHFP
string
success
algorithm, fp_type, fingerprint

TLSA
string
success
usage, selector, mtype, cert

TXT
string
success
strings



Authors

  • Jan-Piet Mens (@jpmens) <jpmens(at)gmail.com>

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