/ home / community / community.general / 3.8.10 / lookup / dig

community.general.dig (3.8.10) — lookup

query DNS using the dnspython library

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

Install collection

Install with ansible-galaxy collection install community.general:==3.8.10

Add to requirements.yml

  collections:
    - name: community.general
      version: 3.8.10

Description

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

dnspython (python library, http://www.dnspython.org/)

Usage examples

Scanned by Steampunk Spotter

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

Scanned by Steampunk Spotter

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

Scanned by Steampunk Spotter

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

Scanned by Steampunk Spotter

- 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) }}"

Scanned by Steampunk Spotter

- ansible.builtin.debug:
    msg: "Reverse DNS for 192.0.2.5 is {{ lookup('community.general.dig', '192.0.2.5/PTR') }}"

Scanned by Steampunk Spotter

- ansible.builtin.debug:
    msg: "Reverse DNS for 192.0.2.5 is {{ lookup('community.general.dig', '5.2.0.192.in-addr.arpa./PTR') }}"

Scanned by Steampunk Spotter

- 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') }}"

Scanned by Steampunk Spotter

- ansible.builtin.debug:
    msg: "Querying 198.51.100.23 for IPv4 address for example.com. produces {{ lookup('dig', 'example.com', '@198.51.100.23') }}"

Scanned by Steampunk Spotter

- 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) }}"

Scanned by Steampunk Spotter

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

Inputs

    
flat:
    default: 1
    description: If 0 each record is returned as a dictionary, otherwise a string

qtype:
    choices:
    - A
    - ALL
    - AAAA
    - CNAME
    - DNAME
    - DLV
    - DNSKEY
    - DS
    - HINFO
    - LOC
    - MX
    - NAPTR
    - NS
    - NSEC3PARAM
    - PTR
    - RP
    - RRSIG
    - SOA
    - SPF
    - SRV
    - SSHFP
    - TLSA
    - TXT
    default: A
    description: record type to query

_terms:
    description: domain(s) to query

retry_servfail:
    default: false
    description: Retry a nameserver if it returns SERVFAIL.
    type: bool
    version_added: 3.6.0
    version_added_collection: community.general

Outputs

_list:
  contains:
    A:
      description:
      - address
    AAAA:
      description:
      - address
    ALL:
      description:
      - owner, ttl, type
    CNAME:
      description:
      - target
    DLV:
      description:
      - algorithm, digest_type, key_tag, digest
    DNAME:
      description:
      - target
    DNSKEY:
      description:
      - flags, algorithm, protocol, key
    DS:
      description:
      - algorithm, digest_type, key_tag, digest
    HINFO:
      description:
      - cpu, os
    LOC:
      description:
      - latitude, longitude, altitude, size, horizontal_precision, vertical_precision
    MX:
      description:
      - preference, exchange
    NAPTR:
      description:
      - order, preference, flags, service, regexp, replacement
    NS:
      description:
      - target
    NSEC3PARAM:
      description:
      - algorithm, flags, iterations, salt
    PTR:
      description:
      - target
    RP:
      description:
      - mbox, txt
    SOA:
      description:
      - mname, rname, serial, refresh, retry, expire, minimum
    SPF:
      description:
      - strings
    SRV:
      description:
      - priority, weight, port, target
    SSHFP:
      description:
      - algorithm, fp_type, fingerprint
    TLSA:
      description:
      - usage, selector, mtype, cert
    TXT:
      description:
      - strings
  description:
  - List of composed strings or dictionaries with key and value If a dictionary, fields
    shows the keys returned depending on query type
  elements: raw
  type: list