community.general.dig 查询 — 使用 dnspython 库查询 DNS

注意

此查找插件是 community.general 集合 (版本 10.1.0) 的一部分。

如果您使用的是 ansible 包，则可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.general。要使用此查找插件，您需要其他需求，有关详细信息，请参阅 需求。

要在剧本中使用它，请指定：community.general.dig。

概要

  • dig 查找对 DNS 服务器运行查询，以检索特定名称（FQDN - 完全限定域名）的 DNS 记录。可以使用这种方式查找任何 DNS 记录。

  • 可以使用几种不同的语法来指定要检索的记录以及名称。还可以显式指定用于查找的 DNS 服务器。

  • 在其最简单的形式中，dig 查找插件可用于检索与 FQDN 关联的 IPv4 地址（DNS A 记录）

  • 除了（默认）A 记录外，还可以指定应查询的不同记录类型。这可以通过向 dig 查找传递格式为 qtype=TYPE 的附加参数来完成，或者通过将 /TYPE 附加到要查询的 FQDN 来完成。

  • 如果多个值与请求的记录关联，则结果将作为逗号分隔的列表返回。在这种情况下，您可能希望将选项 wantlist=true 传递给 lookup 调用，或者使用 query 代替 lookup，这将导致记录值作为列表返回，您可以在稍后迭代该列表。

  • 默认情况下，查找将依赖于系统范围配置的 DNS 服务器来执行查询。还可以使用 @DNS_SERVER_1,DNS_SERVER_2,…,DNS_SERVER_N 符号显式指定要查询的 DNS 服务器。这需要作为附加参数传递给查找。

需求

以下需求是在执行此查找的本地控制器节点上需要的。

术语

参数

注释

术语

列表 / 元素=字符串

要查询的域名。

关键字参数

这描述了查找的关键字参数。这些是以下示例中的 key1=value1、key2=value2 等值：lookup('community.general.dig', key1=value1, key2=value2, ...) 和 query('community.general.dig', key1=value1, key2=value2, ...)

参数

注释

class

字符串

类。

默认值： "IN"

fail_on_error

布尔值

在 community.general 5.4.0 中添加

在查找错误时中止执行。

此选项的默认值将来可能会更改为 true。当前的默认值 false 用于向后兼容性，如果发生错误，则会导致结果为空字符串或字符串 NXDOMAIN。

选项

  • false ← (默认)

  • true

flat

整数

如果为 0，则每个记录都作为字典返回，否则为字符串。

默认值： 1

port

整数

在 community.general 9.5.0 中添加

查找 DNS 记录时使用端口作为目标端口。

默认值： 53

qtype

字符串

要查询的记录类型。

DLV 已在 community.general 6.0.0 中删除。

CAA 已在 community.general 6.3.0 中添加。

选项

  • "A" ← (默认)

  • "ALL"

  • "AAAA"

  • "CAA"

  • "CNAME"

  • "DNAME"

  • "DNSKEY"

  • "DS"

  • "HINFO"

  • "LOC"

  • "MX"

  • "NAPTR"

  • "NS"

  • "NSEC3PARAM"

  • "PTR"

  • "RP"

  • "RRSIG"

  • "SOA"

  • "SPF"

  • "SRV"

  • "SSHFP"

  • "TLSA"

  • "TXT"

real_empty

布尔值

在 community.general 6.0.0 中添加

返回空结果，不带空字符串，并返回空列表而不是 NXDOMAIN。

此选项的默认值将来可能会更改为 true。

如果指定了多个要查询的域，则此选项将强制设置为 true。

选项

  • false ← (默认)

  • true

retry_servfail

布尔值

在 community.general 3.6.0 中添加

如果名称服务器返回 SERVFAIL，则重试。

选项

  • false ← (默认)

  • true

tcp

布尔值

自 community.general 7.5.0 版本起添加

使用 TCP 查询 DNS 记录。

选项

  • false ← (默认)

  • true

注释

注意

  • 当关键字参数和位置参数一起使用时，位置参数必须列在关键字参数之前：lookup('community.general.dig', term1, term2, key1=value1, key2=value2) 和 query('community.general.dig', term1, term2, key1=value1, key2=value2)

  • ALL 本身并非一种记录类型，而只是指您可以以字典形式检索到的任何记录结果中都可用的字段。

  • 虽然“dig”查找插件支持 dnspython 原生支持的任何内容，但只有一小部分可以转换为字典。

  • 如果您需要获取 AAAA 记录（IPv6 地址），则必须显式指定记录类型。指定记录类型的语法如下例所示。

  • 大多数示例中结尾的点纯粹是可选的，但出于完整性和正确性的考虑而指定。

示例

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

- name: Lookup multiple names at once
  ansible.builtin.debug:
    msg: "A record found {{ item }}"
  loop: "{{ query('community.general.dig', 'example.org.', 'example.com.', 'gmail.com.') }}"

- name: Lookup multiple names at once (from list variable)
  ansible.builtin.debug:
    msg: "A record found {{ item }}"
  loop: "{{ query('community.general.dig', *hosts) }}"
  vars:
    hosts:
      - example.org.
      - example.com.
      - gmail.com.

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

返回值

键

描述

返回值

列表 / 元素=任意

由字符串或包含键值对的字典组成的列表。如果是字典，则字段显示根据查询类型返回的键。

返回：成功

A

字符串

地址

返回：成功

AAAA

字符串

地址

返回：成功

ALL

字符串

owner、ttl、type

返回：成功

CAA

字符串

自 community.general 6.3.0 版本起添加

标志

标签

值

返回：成功

CNAME

字符串

目标

返回：成功

DNAME

字符串

目标

返回：成功

DNSKEY

字符串

flags、algorithm、protocol、key

返回：成功

DS

字符串

algorithm、digest_type、key_tag、digest

返回：成功

HINFO

字符串

cpu、os

返回：成功

LOC

字符串

latitude、longitude、altitude、size、horizontal_precision、vertical_precision

返回：成功

MX

字符串

preference、exchange

返回：成功

NAPTR

字符串

order、preference、flags、service、regexp、replacement

返回：成功

NS

字符串

目标

返回：成功

NSEC3PARAM

字符串

algorithm、flags、iterations、salt

返回：成功

PTR

字符串

目标

返回：成功

RP

字符串

mbox、txt

返回：成功

SOA

字符串

mname、rname、serial、refresh、retry、expire、minimum

返回：成功

SPF

字符串

字符串

返回：成功

SRV

字符串

priority、weight、port、target

返回：成功

SSHFP

字符串

algorithm、fp_type、fingerprint

返回：成功

TLSA

字符串

usage、selector、mtype、cert

返回：成功

TXT

字符串

字符串

返回：成功

作者

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

提示

每个条目类型的配置项具有从低到高的优先级顺序。例如，列表中较低的变量将覆盖较高的变量。