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

注意

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

概述 

此模块由剧本自动调用，以收集有关远程主机的信息，这些信息可用于剧本。它也可以由 /usr/bin/ansible 直接执行，以检查哪些变量可用于主机。Ansible 自动提供有关系统的大量信息。
此模块也支持 Windows 目标。

参数 

参数	注释
fact_path 路径	用于本地 Ansible 信息 (`.fact`) 的路径 - 此目录中的文件将被运行（如果可执行）并且它们的结果将被添加到 `ansible_local` 信息中。如果文件不可执行，则会读取它。文件/结果格式可以是 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）模式之一匹配的信息。空列表基本上意味着“无过滤器”。从 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。）
filter 选项仅过滤 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

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

概述

参数

属性

备注

示例

作者

集合链接

概述 

参数 

属性 

备注 

示例 