How to use Ansible Stat module to gather file information

Introduction

Ansible, a powerful open-source automation tool, offers a wide range of modules to streamline various IT tasks. In this tutorial, we will explore the Ansible Stat module, which provides a versatile way to gather detailed information about files and directories on your managed hosts. By the end of this guide, you'll be equipped with the knowledge to effectively leverage the Stat module and apply it to your Ansible-driven workflows.

Skills Graph

Introduction to Ansible Stat Module

Ansible is a powerful open-source automation tool that simplifies the process of managing and configuring infrastructure. One of the key modules in Ansible is the stat module, which allows you to gather information about files and directories on the target hosts.

The Ansible stat module is used to retrieve information about a file or directory, such as its permissions, ownership, size, and modification time. This information can be used in various automation tasks, such as:

• Verifying the existence and properties of a file or directory
• Comparing the properties of a file or directory across different hosts
• Conditionally executing tasks based on the properties of a file or directory

To use the stat module, you need to provide the path to the file or directory you want to gather information about. The module will then return a dictionary of information about the specified file or directory, which you can use in your Ansible playbooks or tasks.

Here's an example of how to use the stat module in an Ansible playbook:

- name: Get information about a file
  stat:
    path: /path/to/file.txt
  register: file_info

- name: Print file information
  debug:
    var: file_info

In this example, the stat module is used to gather information about the file located at /path/to/file.txt. The gathered information is stored in the file_info variable, which can then be used in subsequent tasks or output for debugging purposes.

Gathering File Information with Ansible Stat

Syntax and Parameters

The basic syntax for using the stat module in Ansible is as follows:

- stat:
    path: /path/to/file_or_directory
    follow: yes|no
    get_checksum: yes|no
    checksum_algorithm: md5|sha1|sha256|sha384|sha512
    get_mime: yes|no
    get_attributes: yes|no
  register: file_info

Here's a brief explanation of the available parameters:

• path: The path to the file or directory you want to gather information about.
• follow: Whether to follow symbolic links (default is no).
• get_checksum: Whether to calculate the checksum of the file (default is no).
• checksum_algorithm: The algorithm to use for calculating the checksum (default is sha1).
• get_mime: Whether to retrieve the MIME type of the file (default is no).
• get_attributes: Whether to retrieve the file attributes (default is no).

The gathered information is stored in the file_info variable, which you can then use in your Ansible playbooks or tasks.

Accessing File Information

Once you have the file_info variable, you can access the various properties of the file or directory using dot notation. For example:

- name: Print file information
  debug:
    var:
      - file_info.stat.size
      - file_info.stat.mode
      - file_info.stat.owner
      - file_info.stat.group
      - file_info.stat.mtime
      - file_info.stat.checksum

This will output the size, mode (permissions), owner, group, modification time, and checksum (if requested) of the file or directory.

Conditional Execution

You can also use the stat module to conditionally execute tasks based on the properties of a file or directory. For example:

- name: Check if a file exists
  stat:
    path: /path/to/file.txt
  register: file_stat

- name: Print a message if the file exists
  debug:
    msg: "The file exists!"
  when: file_stat.stat.exists

In this example, the stat module is used to check if the file /path/to/file.txt exists. If the file exists, the when condition will be true, and the debug task will be executed.

Practical Use Cases of Ansible Stat

The stat module in Ansible has a wide range of practical use cases, from simple file existence checks to more complex file management tasks. Here are a few examples:

Verifying File Existence and Properties

One of the most common use cases for the stat module is to verify the existence and properties of a file or directory. This can be useful for ensuring that a required file or directory is present on the target hosts before executing other tasks. For example:

- name: Check if a configuration file exists
  stat:
    path: /etc/myapp/config.yml
  register: config_file

- name: Fail if the configuration file is missing
  fail:
    msg: "The configuration file is missing!"
  when: not config_file.stat.exists

In this example, the stat module is used to check if the /etc/myapp/config.yml file exists. If the file does not exist, the task will fail with an error message.

Comparing File Properties Across Hosts

The stat module can also be used to compare the properties of a file or directory across different hosts. This can be useful for ensuring consistency in your infrastructure or for identifying differences between environments. For example:

- name: Get information about a log file
  stat:
    path: /var/log/myapp.log
  register: log_file_info
  delegate_to: app_server

- name: Get information about the same log file on another host
  stat:
    path: /var/log/myapp.log
  register: log_file_info_backup
  delegate_to: backup_server

- name: Compare log file properties
  debug:
    msg: >
      Log file properties differ between app_server and backup_server.
      app_server: {{ log_file_info.stat.size }} bytes, {{ log_file_info.stat.mtime }}
      backup_server: {{ log_file_info_backup.stat.size }} bytes, {{ log_file_info_backup.stat.mtime }}
  when: log_file_info.stat.size != log_file_info_backup.stat.size or
    log_file_info.stat.mtime != log_file_info_backup.stat.mtime

In this example, the stat module is used to gather information about a log file on two different hosts (app_server and backup_server). The gathered information is then compared, and a debug message is printed if the file properties differ.

Conditional Execution Based on File Properties

The stat module can also be used to conditionally execute tasks based on the properties of a file or directory. This can be useful for automating various file management tasks, such as creating backups or triggering alerts. For example:

- name: Check if a log file is too large
  stat:
    path: /var/log/myapp.log
  register: log_file_info

- name: Create a backup of the log file
  copy:
    src: /var/log/myapp.log
    dest: /var/backups/myapp.log.{{ ansible_date_time.iso8601 }}
  when: log_file_info.stat.size > 1024 * 1024 * 10 ## 10 MB

In this example, the stat module is used to check the size of the /var/log/myapp.log file. If the file size exceeds 10 MB, a backup of the file is created in the /var/backups directory.

These are just a few examples of the practical use cases for the Ansible stat module. By understanding how to effectively use this module, you can streamline your infrastructure management and automate a wide range of file-related tasks.

Summary

The Ansible Stat module is a valuable tool for system administrators and DevOps professionals, enabling them to gather comprehensive file information and make informed decisions. By mastering the Stat module, you can automate file-related tasks, monitor file changes, and integrate file data into your broader Ansible-powered infrastructure. This tutorial has provided a comprehensive overview of the Stat module's capabilities, practical use cases, and how to effectively leverage it in your Ansible-driven workflows.