Introduction
Datadope Discovery’s ansible collection offers a set of modules, roles, actions and playbooks that aim to facilitate the collection of server information using ansible. It offers modules for both UNIX and Windows systems, allowing the extraction of data from packages, processes and installed software, among others, with the simple inclusion of an ansible task.
Requirements
The compatibility requirements are reduced to meet the requirements of ansible 2.9.8 (minimum supported version), there are no additional requirements.
As an additional requirement, in case you want to extract information about Linux virtual machines running on Windows systems under the Hyper-V hypervisor, the package needs to be installed:
linux-cloud-tools-virtual
If unavailable, Hyper-V will not be able to obtain the interfaces of the Linux virtual machines, preventing to obtain their hostname by performing a DNS resolution.
Installation
The installation of the collection is done from its corresponding git repository in github. It can be done either from ansible requirements.txt file or from the command line using the ansible-galaxy command, being necessary in both cases to specify the branch or tag to install.
For the command line installation, it will be executed:
ansible-galaxy collection install git+https://github.com/datadope-io/ansible_collection_discovery.git,v1.1.1
For installation as a dependency, it shall be included in the requirements.txt file:
- name: +https://github.com/datadope-io/ansible_collection_discovery.git type: git version: v1.1.1
Available modules, actions, roles and playbooks
Modules
Linux
- process_facts: Allows the extraction of information about the processes running on the system. It is also compatible with other unix-like systems.Example output:
[ { 'pid': '10', 'ppid': '1', 'user': 'root', 'cmdline': 'the process command line' } ]
- check_connection: Checks if an endpoint exists and responds, and additionally informs about the web protocol used (http/https).Example output:
{ "available": true, "identified_as": "https" }
- file_parser: Reads and compiles files from remote machines, so that if a file includes references to other files (as in some software configuration files) the result is a complete self-contained file.
Windows
- win_process_facts: Like its namesake for Linux systems, extracts information about running processes on Windows systems in the same format.Example output:
[ { "cmdline": "\"C:\\Program Files\\Microsoft SQL Server\\MSSQL14.SQLEXPRESS\\MSSQL\\Binn\\sqlservr.exe", "pid": 1560, "ppid": 444, "user": "NT SERVICE\\MSSQL$SQLEXPRESS" } ]
- win_package_facts: Collects information about the packages installed on the system. It follows the format of the ‘ansible.builtin.package_facts’ module for Linux systems.Example output:
[ { "psqlODBC 13.00.0000": [ { "arch": "AMD64", "authorized_cdf_prefix": null, "comments": "ODBC drivers for PostgreSQL, packaged by EnterpriseDB", "contact": "", "estimated_size": 13676, "help_link": "", "help_telephone": null, "install_date": "20220215", "install_location": "C:\\Program Files\\PostgreSQL\\psqlODBC", "install_source": null, "language": null, "modify_path": null, "name": "psqlODBC 13.00.0000", "no_repair": "1", "publisher": "EnterpriseDB", "readme": null, "size": null, "source": "windows_registry", "system_component": null, "uninstall_string": "\"C:\\Program Files\\PostgreSQL\\psqlODBC\\uninstall-psqlodbc.exe\"", "url_info_about": "", "url_update_info": null, "vendor": null, "version": "13.00.0000-2", "version_major": 13, "version_minor": 0, "windows_installer": null } ] } ]
- win_hyperv_facts: Extracts the information about the virtual machines running on the Windows system on which the module is executed.Example of output:
[ { "creation_time": "ju. oct. 27 19:42:05 2022", "hostname": "vm1.mshome.net", "id": "f3abe0f9-3ba0-49a7-ae48-e2f0808cca9d", "max_memory": 1099511627776, "memory": 2147483648, "min_memory": 536870912, "name": "Ubuntu 18.04 LTS", "network_adapters": [ ], "path": "C:\\ProgramData\\Microsoft\\Windows\\Hyper-V", "processor_count": 4, "serial": "4857-2270-1268-6889-7697-3920-09", "state": 2, "hypervisor": "Hyper-V" } ]
SunOS
- sunos_listen_ports_facts: Gets the information about active listeners on SunOS systems, respecting the form of the counterparts ‘listen_ports_facts’ for Linux, included in ansible, and ‘win_listen_ports_facts’ for Windows, included in the collection ‘community.windows’.Example output (tcp_listen key):
[ { "address": "127.0.0.1", "name": "python", "pid": 816, "port": 150, "protocol": "tcp", "stime": "Thu Nov 15 12:25:29 2018", "user": "root" } ]
Actions:
- software_facts: Providing information about active ports, installed software and running processes, it is able to provide a list of information about running software, performing tasks to expand and organise this information.Example output:
[ { 'name': 'PostgreSQL Database', 'process': { 'pid': '1234', 'ppid': '1', 'cmdline': '/usr/bin/postgres -D /var/lib/postgresql/data', 'listening_ports': [ '5432' ], 'children': [ { 'pid': '1235', 'ppid': '1234', 'cmdline': 'postgres: logger process' }, { 'pid': '1236', 'ppid': '1234', 'cmdline': 'checkpointer process' } ] }, 'listening_ports': [5432], 'packages': [ { 'arch': 'x86_64', 'epoch': None, 'name': 'postgresql10-server', 'release': '1PGDG.rhel7', 'source': 'rpm', 'version': '10.17' } ], 'version': [ { 'number': '10.17', 'type': 'package' } ] } ]
Roles:
- docker_containers: Allows to obtain information about the containers running on a machine using docker. By default it uses the ‘community.docker’ collection, but in case of failure, it is able to use the docker CLI to obtain the information.
- software_discovery: It is in charge of executing the necessary modules to obtain the information required by ‘software_facts’ depending on the operating system, in order to execute it afterwards.
- hyperv_vms: Checks that Hyper-V is enabled and running on the machine to subsequently launch the extraction of information from the virtual machines that are active.
Playbooks:
- software_discovery.yml: In addition to executing the software_discovery role, it offers the possibility of storing the extracted information in the specified location with the given format (yaml/json).
Example of process extraction on a Windows machine
To extract the processes from a Windows machine and have them registered in the ‘processes’ key of the ‘ansible_facts’ of the machine, we only need to add a task that includes the module ‘datadope.discovery.win_process_facts’. For this example, we will also activate the ‘extended_data’ option, which provides us with additional information about each of the processes:
- name: Gather processes facts datadope.discovery.win_process_facts: extended_data: true
Example of complete software extraction on a machine
To perform a complete extraction of the software of a machine, we will make use of the role ‘software_discovery’, which will automatically collect the necessary information for the action ‘software_facts’ according to the operating system, to later invoke it and store this information in the key ‘software’ of the ‘ansible_facts’ of the machine.
This invocation can be done in two different ways; including the role as part of the roles of a playbook, or including the role as part of a task by using the module ‘include_role’.
Example of a playbook including the key ‘roles’:
- hosts: all roles: - role: datadope.discovery.software_discovery
Example of a task that makes use of the role:
- name: Ejecutar el rol software_discovery de Datadope Discovery include_role: name: datadope.discovery.software_discovery
Resources
Ansible Datadope Discovery Collection:
https://github.com/datadope-io/ansible_collection_discovery
Documentation on installing collections on ansible:
https://docs.ansible.com/ansible/latest/collections_guide/collections_installing.html