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 传递给查找调用，或者使用 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) }}"

返回值

键

描述

返回值

列表 / elements=any

带有键和值的组合字符串或字典的列表。如果是字典，则字段显示根据查询类型返回的键

返回: 成功

A

字符串

地址

返回: 成功

AAAA

字符串

地址

返回: 成功

ALL

字符串

所有者, ttl, 类型

返回: 成功

CAA

字符串

在 community.general 6.3.0 中添加

标志

标签

值

返回: 成功

CNAME

字符串

目标

返回: 成功

DNAME

字符串

目标

返回: 成功

DNSKEY

字符串

标志, 算法, 协议, 密钥

返回: 成功

DS

字符串

算法, 摘要类型, 密钥标签, 摘要

返回: 成功

HINFO

字符串

cpu, os

返回: 成功

LOC

字符串

纬度, 经度, 海拔, 大小, 水平精度, 垂直精度

返回: 成功

MX

字符串

优先级, 交换

返回: 成功

NAPTR

字符串

顺序, 优先级, 标志, 服务, 正则表达式, 替换

返回: 成功

NS

字符串

目标

返回: 成功

NSEC3PARAM

字符串

算法, 标志, 迭代次数, 盐值

返回: 成功

PTR

字符串

目标

返回: 成功

RP

字符串

mbox, txt

返回: 成功

SOA

字符串

mname, rname, 序列号, 刷新, 重试, 过期, 最小值

返回: 成功

SPF

字符串

字符串

返回: 成功

SRV

字符串

优先级, 权重, 端口, 目标

返回: 成功

SSHFP

字符串

算法, 指纹类型, 指纹

返回: 成功

TLSA

字符串

用法, 选择器, mtype, 证书

返回: 成功

TXT

字符串

字符串

返回: 成功

作者

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

提示

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