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