ansible.builtin.setup 模块 – 收集远程主机信息

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，您甚至无需指定 集合关键字 就可以使用简短的模块名称 setup。但是，我们建议您使用 完全限定集合名称 (FQCN) ansible.builtin.setup 来方便链接到模块文档，并避免与可能具有相同模块名称的其他集合发生冲突。

概要

• 此模块会由剧本自动调用，以收集有关远程主机的信息，这些信息在剧本中很有用。它也可以由 /usr/bin/ansible 直接执行，以检查哪些变量可用于主机。Ansible 会自动提供有关系统的许多 *事实*。

• 此模块也支持 Windows 目标。

参数

参数	注释
fact_path 路径	用于本地 Ansible 事实 (*.fact) 的路径 - 此目录中的文件将被运行（如果可执行），并将结果添加到 ansible_local 事实中。如果文件不可执行，则会读取文件内容。文件/结果格式可以是 JSON 或 INI 格式。默认 fact_path 可以在 ansible.cfg 中指定，以便在作为 gather_facts 的一部分自动调用 setup 时使用。注意 - 对于 Windows 客户端，结果将添加到以本地文件（不含扩展名后缀）命名的变量中，而不是 ansible_local 中。 自 Ansible 2.1 起，Windows 主机可以使用 fact_path。确保此路径存在于目标主机上。此路径中的文件必须是 PowerShell 脚本 .ps1，该脚本输出一个对象。此对象将由 Ansible 格式化为 json，因此脚本应输出一个原始哈希表、数组或其他基本对象。 默认值： "/etc/ansible/facts.d"
filter 列表 / 元素=字符串	如果提供，则仅返回与 shell 风格（fnmatch）模式之一匹配的事实。空列表基本上表示“无筛选器”。从 Ansible 2.11 起，类型已从字符串更改为列表，默认值已变为空列表。仍然接受简单的字符串，并作为单个模式起作用。Ansible 2.11 之前的行为保持不变。 默认值： []
gather_subset 列表 / 元素=字符串	如果提供，则将收集的额外事实限制为给定的子集。可能的值：all、all_ipv4_addresses、all_ipv6_addresses、apparmor、architecture、caps、chroot、cmdline、date_time、default_ipv4、default_ipv6、devices、distribution、distribution_major_version、distribution_release、distribution_version、dns、effective_group_ids、effective_user_id、env、facter、fips、hardware、interfaces、is_chroot、iscsi、kernel、local、lsb、machine、machine_id、mounts、network、ohai、os_family、pkg_mgr、platform、processor、processor_cores、processor_count、python、python_version、real_user_id、selinux、service_mgr、ssh_host_key_dsa_public、ssh_host_key_ecdsa_public、ssh_host_key_ed25519_public、ssh_host_key_rsa_public、ssh_host_pub_keys、ssh_pub_keys、system、system_capabilities、system_capabilities_enforced、systemd、user、user_dir、user_gecos、user_gid、user_id、user_shell、user_uid、virtual、virtualization_role、virtualization_type。可以指定一个值列表来指定更大的子集。值也可以与初始的 ! 一起使用，以指定不应收集该特定子集。例如：!hardware,!network,!virtual,!ohai,!facter。如果指定了 !all，则仅收集最小子集。要避免收集最小子集，请指定 !all,!min。要仅收集特定事实，请使用 !all,!min，并指定特定事实子集。如果您不想显示某些收集的事实，请使用 filter 参数。 默认值： ["all"]
gather_timeout 整数	设置单个事实收集的默认超时时间（以秒为单位）。 默认值： 10

属性

属性	支持	描述
check_mode	支持： 完全支持	可以在 check_mode 中运行，并在不修改目标的情况下返回已更改状态预测，如果不支持，则操作将被跳过。
diff_mode	支持： 不支持	在 diff 模式下，将返回有关更改内容（或可能需要在 check_mode 中更改的内容）的详细信息。
facts	支持： 完全支持	操作返回一个 ansible_facts 字典，该字典将更新现有主机事实
platform	平台： posix、windows	可以对其执行操作的目标操作系统/系列

备注

注意

• 随着后续版本的发布，将添加更多 Ansible 事实。如果安装了 facter 或 ohai，来自这些程序的变量也将被快照到 JSON 文件中，以便在模板化中使用。这些变量以 facter_ 和 ohai_ 为前缀，因此很容易区分它们的来源。所有变量都会冒泡到调用方。使用 Ansible 事实并选择不安装 facter 和 ohai 意味着您可以避免在远程系统上使用 Ruby 依赖项。（另请参见 community.general.facter 和 community.general.ohai。）

• 过滤器选项仅过滤 ansible_facts 下的第一级子键。

• 如果目标主机是 Windows，您目前将无法使用 filter，因为这是由模块的更简单的实现提供的。

• 此模块应在 BSD 系统上以提升的权限运行以收集诸如 ansible_product_version 之类的信息。

• 有关委托事实的更多信息，请查看 https://docs.ansible.org.cn/ansible/latest/user_guide/playbooks_delegation.html#delegating-facts。

示例

# Display facts from all hosts and store them indexed by `hostname` at `/tmp/facts`.
# ansible all -m ansible.builtin.setup --tree /tmp/facts

# Display only facts regarding memory found by ansible on all hosts and output them.
# ansible all -m ansible.builtin.setup -a 'filter=ansible_*_mb'

# Display only facts returned by facter.
# ansible all -m ansible.builtin.setup -a 'filter=facter_*'

# Collect only facts returned by facter.
# ansible all -m ansible.builtin.setup -a 'gather_subset=!all,facter'

- name: Collect only facts returned by facter
  ansible.builtin.setup:
    gather_subset:
      - '!all'
      - '!<any valid subset>'
      - facter

- name: Filter and return only selected facts
  ansible.builtin.setup:
    filter:
      - 'ansible_distribution'
      - 'ansible_machine_id'
      - 'ansible_*_mb'

# Display only facts about certain interfaces.
# ansible all -m ansible.builtin.setup -a 'filter=ansible_eth[0-2]'

# Restrict additional gathered facts to network and virtual (includes default minimum facts)
# ansible all -m ansible.builtin.setup -a 'gather_subset=network,virtual'

# Collect only network and virtual (excludes default minimum facts)
# ansible all -m ansible.builtin.setup -a 'gather_subset=!all,network,virtual'

# Do not call puppet facter or ohai even if present.
# ansible all -m ansible.builtin.setup -a 'gather_subset=!facter,!ohai'

# Only collect the default minimum amount of facts:
# ansible all -m ansible.builtin.setup -a 'gather_subset=!all'

# Collect no facts, even the default minimum subset of facts:
# ansible all -m ansible.builtin.setup -a 'gather_subset=!all,!min'

# Display facts from Windows hosts with custom facts stored in C:\custom_facts.
# ansible windows -m ansible.builtin.setup -a "fact_path='c:\custom_facts'"

# Gathers facts for the machines in the dbservers group (a.k.a Delegating facts)
- hosts: app_servers
  tasks:
    - name: Gather facts from db servers
      ansible.builtin.setup:
      delegate_to: "{{ item }}"
      delegate_facts: true
      loop: "{{ groups['dbservers'] }}"

作者

• Ansible 核心团队

• Michael DeHaan

集合链接

• 问题跟踪器
• 仓库（源代码）
• 通信