How to Use the Ansible Setup Module to Gather System Facts

Last Updated on 7 hours by Sachin G

When working with Linux server automation, knowing your target host’s details is the first step to smooth deployments. The Ansible setup module Linux facts command is the go-to method for collecting system details like OS version, hardware info, network configuration, and more, all without logging into each server manually.

In this expert guide, we’ll explore how to use the Ansible setup module, discuss real-world applications, compare it to similar modules like gather_facts, and share a real-world scenario from the my experience.

What is the Ansible Setup Module?

The Ansible setup module is an Ansible fact-gathering tool that connects to your Linux hosts and collects data automatically. These ansible_facts variables are then available in your playbooks for decision-making, configuration, or reporting.

• OS version (ansible_facts['distribution'])
• Hostname (ansible_facts['hostname'])
• IP addresses (ansible_facts['default_ipv4']['address'])
• Hardware details (CPU, memory, disks)

This fact gathering is a critical first step before running complex playbooks.

Example Playbook Snippet:

- name: Gather Linux system facts  
  hosts: all  
  tasks:  
    - name: Display OS version  
      debug:  
        var: ansible_facts['distribution']  

How to Use the Ansible Setup Module for Linux Hosts

Using the Ansible setup module in production or development environments is straightforward.

1. Using the Setup Module via Ad-hoc Command

ansible all -m setup

Here:

• all → All hosts in your inventory file.
• -m setup → tells Ansible to use the setup module.

This returns a large JSON output containing OS, network, and hardware details from all hosts in the inventory file.

Example Playbook for Gathering Facts

Instead of running it ad-hoc, you can gather facts inside a playbook:

---
- name: Gather Linux System Facts
  hosts: linux_servers
  tasks:
    - name: Collect facts
      ansible.builtin.setup:

Filtering Facts (ansible setup module filter linux)

By default, Ansible gathers all available facts, which can be overwhelming and slow for large inventories.
You can use filters to limit output:

You can filter results to avoid overwhelming output.

Example:

Get only OS Name, version, and Hardware Details

ansible all -m setup -a 'filter=ansible_distribution*'

This might return:

"ansible_distribution": "AlmaLinux",
"ansible_distribution_version": "8.8"

Below is a command for filtering Hardware information.

ansible linux_hosts -m setup -a 'filter=ansible_*_mb'

Using the Setup Module in Playbooks

Instead of running it ad-hoc, you can gather facts inside a playbook:

- name: Gather Linux system facts
  hosts: linux_hosts
  gather_facts: yes
  tasks:
    - name: Show OS distribution
      debug:
        var: ansible_distribution

Setting gather_facts: yes automatically runs the setup module before tasks.

Using Filters with the Setup Module

You can filter which facts to gather to optimize performance.

- name: Gather only networking facts
  ansible.builtin.setup:
    filter: "ansible_*_interfaces"

Personal Insights and Lessons Learned

From working on multiple Ansible Red Hat facts and Ansible on CentOS facts gathering projects, one key takeaway is:

“Never collect more facts than you need in production — it can slow down playbooks and increase unnecessary data transfer.”

A common mistake for beginners is forgetting that gather_facts runs at the start of every play. For performance-heavy environments, disabling automatic fact gathering and running the setup module only when needed is a best practice.

Advanced Techniques for Custom Fact Gathering

Disable automatic facts with gather_facts: false and collect only what you need:

- hosts: all  
  gather_facts: false  
  tasks:  
    - name: Collect only hostname and IP  
      ansible.builtin.setup:  
        filter:  
          - "ansible_hostname"  
          - "ansible_default_ipv4"  

Handling Challenges

• Performance: Fact gathering can slow down playbooks on large inventories. Mitigate this by:
  • Using fact_caching (e.g., Redis).
  • Limiting facts with filters.
• Permissions: Ensure SSH user has sudo access for certain facts (e.g., ansible_mounts).

Why Use the Ansible Setup Module?

• ✅ Automation with Ansible setup module improves repeatability
• ✅ Configure servers using Ansible setup facts-based logic
• ✅ Lightweight compared to external scripts
• ✅ Enables smart, conditional playbooks

Ansible Setup Module vs gather_facts

You can disable gather_facts: no in playbooks and use setup where and how you need.

These controls help you scale automation intelligently, especially in large infrastructures.

The Ansible setup module is a powerful, flexible tool every DevOps professional should master. Whether you’re using Ansible ad-hoc commands or detailed playbooks, system facts empower you to write intelligent automation workflows.

FAQ Section

What is the difference between Ansible gather_facts and setup module?

Answer: gather_facts automatically calls the setup module at the start of a play, whereas running -m setup lets you gather facts manually when you need them.

How do I gather specific system facts with Ansible?

Answer: Use the filter parameter inside the setup module to gather specific facts, e.g., networking or OS info only.

Can I disable fact gathering in a playbook?

Answer: Yes, set gather_facts: no in your playbook and use the setup module manually when needed.

How does the Ansible setup module help in inventory management?

Answer: By gathering live system facts, you can dynamically tag and group hosts based on conditions like OS version, memory size, or IP range.

Sachin G

I’m Sachin Gupta — a freelance IT support specialist and founder of techtransit.org. I’m certified in Linux, Ansible, OpenShift (Red Hat), cPanel, and ITIL, with over 15 years of hands-on experience. I create beginner-friendly Linux tutorials, help with Ansible automation, and offer IT support on platforms like Upwork, Freelancer, and PeoplePerHour. Follow Tech Transit for practical tips, hosting guides, and real-world Linux expertise!

www.techtransit.org