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

注意

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

概要

• 此模块由 Playbook 自动调用，以收集有关远程主机的有用变量，这些变量可以在 Playbook 中使用。它也可以直接由 /usr/bin/ansible 执行，以检查主机可用的变量。Ansible 自动提供有关系统的许多facts。

• Windows 目标也支持此模块。

参数

参数	注释
fact_path 路径	用于本地 Ansible facts 的路径 (*.fact) - 此目录中的文件将被运行（如果可执行），其结果将被添加到 ansible_local facts 中。如果文件不可执行，则会读取该文件。文件/结果格式可以是 JSON 或 INI 格式。默认的 fact_path 可以在 ansible.cfg 中指定，以便在自动调用 setup 作为 gather_facts 的一部分时使用。注意 - 对于 Windows 客户端，结果将添加到以本地文件（不带扩展名后缀）命名的变量中，而不是 ansible_local。 自 Ansible 2.1 起，Windows 主机可以使用 fact_path。确保此路径存在于目标主机上。此路径中的文件必须是 PowerShell 脚本 .ps1，它输出一个对象。此对象将由 Ansible 格式化为 JSON，因此脚本应输出原始的哈希表、数组或其他原始对象。 默认值： "/etc/ansible/facts.d"
filter 列表 / 元素=字符串	如果提供，则仅返回与 shell 样式 (fnmatch) 模式之一匹配的 facts。空列表基本上表示“无过滤器”。自 Ansible 2.11 起，类型已从字符串更改为列表，默认值已为空列表。仍然接受简单的字符串，并且可以作为单个模式工作。Ansible 2.11 之前的行为保持不变。 默认值： []
gather_subset 列表 / 元素=字符串	如果提供，则将收集的其他 facts 限制为给定的子集。可能的值： 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。要仅收集特定的 facts，请使用 !all,!min，并指定特定的 fact 子集。如果您不想显示某些收集的 facts，请使用 filter 参数。 默认值： ["all"]
gather_timeout 整数	设置单个 fact 收集的默认超时时间（秒）。 默认值： 10

属性

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

注释

注意

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

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

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

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

• 有关委托 facts 的更多信息，请查看 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

集合链接

• 问题跟踪器
• 存储库（源代码）
• 沟通