Documentation

setup - Gathers facts about remote hosts

Synopsis

This module is automatically called by playbooks to gather useful variables about remote hosts that can be used in playbooks. It can also be executed directly by /usr/bin/ansible to check what variables are available to a host. Ansible provides many facts about the system, automatically.

Options

parameter required default choices comments
fact_path
(added in 1.3)
 no /etc/ansible/facts.d
    path used for local ansible facts (*.fact) - files in this dir will be run (if executable) and their results be added to ansible_local facts if a file is not executable it is read. Check notes for Windows options. (from 2.1 on) File/results format can be json or ini-format
    filter
    		 no *
      if supplied, only return facts that match this shell-style (fnmatch) wildcard.
      gather_subset
      (added in 2.1)
      		 no all
        if supplied, restrict the additional facts collected to the given subset. Possible values: all, hardware, network, virtual, ohai, and facter Can specify a list of values to specify a larger subset. Values can also be used with an initial ! to specify that that specific subset should not be collected. For instance: !hardware, !network, !virtual, !ohai, !facter. Note that a few facts are always collected. Use the filter parameter if you do not want to display those.

        Examples

        # Display facts from all hosts and store them indexed by I(hostname) at C(/tmp/facts).
ansible all -m setup --tree /tmp/facts

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

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

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

# Restrict additional gathered facts to network and virtual.
ansible all -m setup -a 'gather_subset=network,virtual'

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

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

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

        Notes

        Note

        More ansible facts will be added with successive releases. If facter or ohai are installed, variables from these programs will also be snapshotted into the JSON file for usage in templating. These variables are prefixed with facter_ and ohai_ so it’s easy to tell their source. All variables are bubbled up to the caller. Using the ansible facts and choosing to not install facter and ohai means you can avoid Ruby-dependencies on your remote systems. (See also facter and ohai.)

        Note

        The filter option filters only the first level subkey below ansible_facts.

        Note

        If the target host is Windows, you will not currently have the ability to use filter as this is provided by a simpler implementation of the module.

        Note

        If the target host is Windows you can now use fact_path. Make sure that this path exists on the target host. Files in this path MUST be PowerShell scripts (*.ps1) and their output must be formattable in JSON (Ansible will take care of this). Test the output of your scripts. This option was added in Ansible 2.1.

        This is a Core Module

        For more information on what this means please read Core Modules

        For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.