> ## Content Index
> Fetch the complete content index at: https://linuxhandbook.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Ansible Stat Module: Get Detailed Info About Files on Target Hosts
- URL: https://linuxhandbook.com/ansible-stat-module/
- Published: 2024-11-17T13:26:14.000Z
- Updated: 2024-12-10T15:14:21.000Z
- Description: The stat module in Ansible lets you deal with files based on their stats like size, mode and timestamps. Learn some practical examples.
- Author: LHB Community
- Tags: Ansible Modules, Ansible Tutorials, #docs-col

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](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/stat%5Fmodule.html?ref=linuxhandbook.com) functions similarly to the [stat command in Linux](https://linuxhandbook.com/stat-command/), 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](https://linuxhandbook.com/file-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.

✍️

Author: Hitesh Jethwa has more than 15+ years of experience with Linux system administration and DevOps. He likes to explain complicated topics in easy to understand way.