1#!/usr/bin/python 2# -*- coding: utf-8 -*- 3 4# (c) 2012, Michael DeHaan <michael.dehaan@gmail.com> 5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) 6 7from __future__ import absolute_import, division, print_function 8__metaclass__ = type 9 10 11ANSIBLE_METADATA = {'metadata_version': '1.1', 12 'status': ['stableinterface'], 13 'supported_by': 'core'} 14 15 16DOCUMENTATION = ''' 17--- 18module: setup 19version_added: historical 20short_description: Gathers facts about remote hosts 21options: 22 gather_subset: 23 version_added: "2.1" 24 description: 25 - "If supplied, restrict the additional facts collected to the given subset. 26 Possible values: C(all), C(min), C(hardware), C(network), C(virtual), C(ohai), and 27 C(facter). Can specify a list of values to specify a larger subset. 28 Values can also be used with an initial C(!) to specify that 29 that specific subset should not be collected. For instance: 30 C(!hardware,!network,!virtual,!ohai,!facter). If C(!all) is specified 31 then only the min subset is collected. To avoid collecting even the 32 min subset, specify C(!all,!min). To collect only specific facts, 33 use C(!all,!min), and specify the particular fact subsets. 34 Use the filter parameter if you do not want to display some collected 35 facts." 36 required: false 37 default: "all" 38 gather_timeout: 39 version_added: "2.2" 40 description: 41 - Set the default timeout in seconds for individual fact gathering. 42 required: false 43 default: 10 44 filter: 45 version_added: "1.1" 46 description: 47 - If supplied, only return facts that match this shell-style (fnmatch) wildcard. 48 required: false 49 default: "*" 50 fact_path: 51 version_added: "1.3" 52 description: 53 - Path used for local ansible facts (C(*.fact)) - files in this dir 54 will be run (if executable) and their results be added to C(ansible_local) facts 55 if a file is not executable it is read. Check notes for Windows options. (from 2.1 on) 56 File/results format can be JSON or INI-format. The default C(fact_path) can be 57 specified in C(ansible.cfg) for when setup is automatically called as part of 58 C(gather_facts). 59 required: false 60 default: /usr/local/etc/ansible/facts.d 61description: 62 - This module is automatically called by playbooks to gather useful 63 variables about remote hosts that can be used in playbooks. It can also be 64 executed directly by C(/usr/bin/ansible) to check what variables are 65 available to a host. Ansible provides many I(facts) about the system, 66 automatically. 67 - This module is also supported for Windows targets. 68notes: 69 - More ansible facts will be added with successive releases. If I(facter) or 70 I(ohai) are installed, variables from these programs will also be snapshotted 71 into the JSON file for usage in templating. These variables are prefixed 72 with C(facter_) and C(ohai_) so it's easy to tell their source. All variables are 73 bubbled up to the caller. Using the ansible facts and choosing to not 74 install I(facter) and I(ohai) means you can avoid Ruby-dependencies on your 75 remote systems. (See also M(facter) and M(ohai).) 76 - The filter option filters only the first level subkey below ansible_facts. 77 - If the target host is Windows, you will not currently have the ability to use 78 C(filter) as this is provided by a simpler implementation of the module. 79 - If the target host is Windows you can now use C(fact_path). Make sure that this path 80 exists on the target host. Files in this path MUST be PowerShell scripts (``*.ps1``) and 81 their output must be formattable in JSON (Ansible will take care of this). Test the 82 output of your scripts. 83 This option was added in Ansible 2.1. 84 - This module is also supported for Windows targets. 85 - This module should be run with elevated privileges on BSD systems to gather facts like ansible_product_version. 86author: 87 - "Ansible Core Team" 88 - "Michael DeHaan" 89''' 90 91EXAMPLES = """ 92# Display facts from all hosts and store them indexed by I(hostname) at C(/tmp/facts). 93# ansible all -m setup --tree /tmp/facts 94 95# Display only facts regarding memory found by ansible on all hosts and output them. 96# ansible all -m setup -a 'filter=ansible_*_mb' 97 98# Display only facts returned by facter. 99# ansible all -m setup -a 'filter=facter_*' 100 101# Collect only facts returned by facter. 102# ansible all -m setup -a 'gather_subset=!all,!any,facter' 103 104- name: Collect only facts returned by facter 105 setup: 106 gather_subset: 107 - '!all' 108 - '!any' 109 - facter 110 111# Display only facts about certain interfaces. 112# ansible all -m setup -a 'filter=ansible_eth[0-2]' 113 114# Restrict additional gathered facts to network and virtual (includes default minimum facts) 115# ansible all -m setup -a 'gather_subset=network,virtual' 116 117# Collect only network and virtual (excludes default minimum facts) 118# ansible all -m setup -a 'gather_subset=!all,!any,network,virtual' 119 120# Do not call puppet facter or ohai even if present. 121# ansible all -m setup -a 'gather_subset=!facter,!ohai' 122 123# Only collect the default minimum amount of facts: 124# ansible all -m setup -a 'gather_subset=!all' 125 126# Collect no facts, even the default minimum subset of facts: 127# ansible all -m setup -a 'gather_subset=!all,!min' 128 129# Display facts from Windows hosts with custom facts stored in C(C:\\custom_facts). 130# ansible windows -m setup -a "fact_path='c:\\custom_facts'" 131""" 132 133# import module snippets 134from ...module_utils.basic import AnsibleModule 135 136from ansible.module_utils.facts.namespace import PrefixFactNamespace 137from ansible.module_utils.facts import ansible_collector 138 139from ansible.module_utils.facts import default_collectors 140 141 142def main(): 143 module = AnsibleModule( 144 argument_spec=dict( 145 gather_subset=dict(default=["all"], required=False, type='list'), 146 gather_timeout=dict(default=10, required=False, type='int'), 147 filter=dict(default="*", required=False), 148 fact_path=dict(default='/usr/local/etc/ansible/facts.d', required=False, type='path'), 149 ), 150 supports_check_mode=True, 151 ) 152 153 gather_subset = module.params['gather_subset'] 154 gather_timeout = module.params['gather_timeout'] 155 filter_spec = module.params['filter'] 156 157 # TODO: this mimics existing behavior where gather_subset=["!all"] actually means 158 # to collect nothing except for the below list 159 # TODO: decide what '!all' means, I lean towards making it mean none, but likely needs 160 # some tweaking on how gather_subset operations are performed 161 minimal_gather_subset = frozenset(['apparmor', 'caps', 'cmdline', 'date_time', 162 'distribution', 'dns', 'env', 'fips', 'local', 163 'lsb', 'pkg_mgr', 'platform', 'python', 'selinux', 164 'service_mgr', 'ssh_pub_keys', 'user']) 165 166 all_collector_classes = default_collectors.collectors 167 168 # rename namespace_name to root_key? 169 namespace = PrefixFactNamespace(namespace_name='ansible', 170 prefix='ansible_') 171 172 fact_collector = \ 173 ansible_collector.get_ansible_collector(all_collector_classes=all_collector_classes, 174 namespace=namespace, 175 filter_spec=filter_spec, 176 gather_subset=gather_subset, 177 gather_timeout=gather_timeout, 178 minimal_gather_subset=minimal_gather_subset) 179 180 facts_dict = fact_collector.collect(module=module) 181 182 module.exit_json(ansible_facts=facts_dict) 183 184 185if __name__ == '__main__': 186 main() 187