Ansible Stat Module: Get Detailed Info About Files on Target Hosts

The Ansible Stat module is a built-in tool that helps you gather detailed information about files and directories on target hosts. It’s particularly useful when you need to check the status or properties of a file or directory before performing any action on it.

For example, you might want to copy a file only if it exists or create a backup of a file if it’s older than a certain date.

In this guide, we’ll explore the Ansible Stat module with practical examples.

Understanding the Ansible Stat Module

The Ansible Stat module functions similarly to the stat command in Linux, which is used to display file or file system status. The module gathers information like:

• File existence (exists)
• File size (size)
• File permissions (mode)
• Owner and group
• Access, modification, and change timestamps (atime, mtime, ctime)

You can use this information to make your playbooks more dynamic and responsive based on the current state of files or directories on the managed hosts.

Basic syntax of the Ansible Stat Module

Let’s look at the basic syntax of the Ansible Stat module:

- name: Basic Syntax of Ansible Stat Module
  hosts: all
  tasks:
    - name: Get file status
      ansible.builtin.stat:
        path: /path/to/your/file
      register: file_status

Let's breakdown each parameter:

• ansible.builtin.stat: The module used to gather file or directory information.
• path: Specifies the path of the file or directory you want to check.
• register: Stores the output of the Stat module in a variable file_status, which can be used in subsequent tasks.

Example 1: Check if a file exists

One of the primary use cases of the Stat module is to determine if a file exists before performing further actions. This can prevent errors and make your playbooks more robust.

Here is an example playbook.

---
- name: Check File Existence Using Ansible Stat Module
  hosts: all
  tasks:
    - name: Gather file information
      ansible.builtin.stat:
        path: /tmp/sample.txt
      register: file_info

    - name: Display if the file exists
      debug:
        msg: "The file exists."
      when: file_info.stat.exists

    - name: Display if the file does not exist
      debug:
        msg: "The file does not exist."
      when: not file_info.stat.exists

This playbook checks for the existence of a specific file /tmp/sample.txt on all target hosts using the stat module. It first gathers information about the file and stores it in a variable named file_info. The playbook then uses conditional statements to display messages based on whether the file exists: if the file is present, it shows The file exists, and if it is absent, it displays The file does not exist.

Example 2: Gather file metadata

The Stat module can retrieve detailed metadata about a file, such as its size, permissions, owner, and timestamps. This information can be used to make informed decisions in your playbooks.

Here is an example playbook:

---
- name: Retrieve File Metadata Using Stat Module
  hosts: all
  tasks:
    - name: Gather metadata of the file
      ansible.builtin.stat:
        path: /etc/hosts
      register: file_metadata

    - name: Display file size
      debug:
        msg: "The file size is {{ file_metadata.stat.size }} bytes."

    - name: Display file permissions
      debug:
        msg: "File permissions: {{ file_metadata.stat.mode | format('%o') }}"

    - name: Display file owner
      debug:
        msg: "The file is owned by {{ file_metadata.stat.pw_name }}."

This playbook retrieves metadata about the /etc/hosts file on all target hosts using Ansible's stat module and stores it in the file_metadata variable. It then uses debug tasks to display specific details of the file: its size in bytes, permissions, and the owner's username. This playbook provides a quick way to gather and display essential file information from multiple hosts.

Example 3: Verify and create a directory

You can use the Stat module to check if a directory exists before creating it. This ensures idempotency in your playbooks.

Here is an example playbook.

---
- name: Ensure a Directory Exists
  hosts: all
  tasks:
    - name: Check if the directory exists
      ansible.builtin.stat:
        path: /tmp/backup
      register: dir_info

    - name: Create directory if it does not exist
      file:
        path: /tmp/backup
        state: directory
      when: not dir_info.stat.exists

This Ansible playbook checks if the directory /tmp/backup exists on all target hosts using the stat module. It registers the result as dir_info. If the directory does not exist (not dir_info.stat.exists), the playbook creates it using the file module with state: directory. This ensures that the specified directory is present on all target hosts.

Example 4: Perform conditional tasks based on file timestamps

You can use the file’s modification time to decide whether to take action. For example, copying a file only if it was modified before a specific date.

Here is the playbook:

---
- name: Copy File If Modified Before a Certain Date
  hosts: all
  tasks:
    - name: Get file information
      ansible.builtin.stat:
        path: /tmp/important.log
      register: file_stat

    - name: Copy the file if it is older than the specified timestamp
      copy:
        src: /tmp/newfile.log
        dest: /tmp/important.log
      when: file_stat.stat.mtime < 1699795200

This playbook checks the modification time of the file /tmp/important.log on all target hosts using the stat module and stores the result in file_stat. It then compares the file's modification time against a specified timestamp. If the file was last modified before this timestamp, the playbook copies newfile.log to replace important.log using the copy module.

Example 5: Checking directory permissions

This playbook checks the permissions of a directory and changes them if they are not as expected.

---
- name: Ensure Directory Has Correct Permissions
  hosts: all
  tasks:
    - name: Get directory permissions
      ansible.builtin.stat:
        path: /var/www/html
      register: dir_stat

    - name: Set correct permissions if needed
      file:
        path: /var/www/html
        mode: '0755'
      when: dir_stat.stat.mode != '0755'

This playbook checks the permissions of the /var/www/html directory on all target hosts using the stat module and saves the result in the dir_stat variable. If the current permissions do not match 0755, it updates the directory's permissions using the file module.

Conclusion

The Ansible Stat module is an essential tool in your automation toolkit. It allows you to make informed decisions based on file and directory attributes, enhancing the robustness and flexibility of your playbooks.