How to Use the Ansible Setup Module to Gather System Facts

Last Updated on 14 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 like below screenshot or in text block.

"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 Linux system facts
  hosts: all
  tasks:
    - 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.

When working with Ansible in large-scale environments, speed and efficiency are crucial. The Ansible setup module is incredibly useful for collecting Linux system facts—including OS details, CPU, memory, and network interfaces—but running it unnecessarily can slow down your playbooks.

Why Disable the Ansible Setup Module?

• Performance boost – Skips the time spent on fact gathering.

• Reduced network traffic – Less data sent between control and managed nodes.

• Cleaner output – Avoids cluttered logs with unnecessary system details.

• Better scalability – Improves execution speed across large inventories.

How to Disable Fact Gathering

You can disable the Ansible setup module at the playbook level:

Example: Disabling gather_facts

- name: Deploy configuration without fact gathering
  hosts: linux_hosts
  gather_facts: no
  tasks:
    - name: Copy configuration file
      copy:
        src: config.cfg
        dest: /etc/config.cfg

This ensures no Ansible setup module command is run at the start of the playbook.

When to Disable Fact Gathering

• Static configurations that don’t require OS or hardware checks.

• Service restarts that don’t depend on facts.

• Bulk file copies where hardware and network data aren’t relevant.

• Optimized cloud workflows where metadata is gathered elsewhere.

Gathering Only Network Facts

If you disable fact gathering globally but still need network interface details, you can run the setup module with filters.

Example: Collect Only Network Facts

ansible linux_hosts -m setup -a 'filter=ansible_default_ipv4,ansible_all_ipv4_addresses,ansible_all_ipv6_addresses'

This retrieves:

• Default IPv4 address
• All IPv4 and IPv6 addresses
• MAC addresses (if requested)

Using the Setup Module in Playbooks for Network Facts

- name: Gather only network facts
  hosts: linux_hosts
  gather_facts: no
  tasks:
    - name: Run setup module for network details
      setup:
        filter: ansible_*_ipv4

This is faster than gathering all system facts and keeps your automation targeted.

From experience managing Ansible Red Hat facts and Ansible on CentOS facts gathering, here’s what I’ve learned:

“Always balance the trade-off between performance and information. In a cluster with hundreds of hosts, disabling full fact gathering and targeting only what’s needed can cut execution time by up to 50%.”

One challenge beginners face is forgetting that disabling gather_facts removes all default fact variables unless the setup module is called explicitly. This can cause tasks relying on variables like ansible_hostname to fail.

Disabling the Ansible setup module by default and gathering only the network facts you need is a best practice for speeding up playbooks. This approach reduces execution time, optimizes resource usage, and keeps your automation focused.

FAQ Section

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.

Want to learn more about Ansible?
Please explore our complete Ansible Tutorials for Beginners to master automation step-by-step.
You can also check out our Recommended Ansible Courses for expert-led training and practical projects to boost your skills.

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