stat

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin

Added in version 1.3.

Synopsis

• Retrieves facts for a file similar to the Linux/Unix C(stat) command.
• For Windows targets, use the M(ansible.windows.win_stat) module instead.

Parameters

Parameter	Defaults / Choices	Comments
checksum_algorithm str	Default: sha1 Choices: md5, sha1, sha224, sha256, sha384, sha512	Algorithm to determine checksum of file. Will throw an error if the host is unable to use specified algorithm. The remote host has to support the hashing method specified, V(md5) can be unavailable if the host is FIPS-140 compliant. Version Added: 2.0
follow bool		Whether to follow symlinks.
get_attributes bool	Default: True	Get file attributes using lsattr tool if present. Version Added: 2.3
get_checksum bool	Default: True	Whether to return a checksum of the file. Version Added: 1.8
get_mime bool	Default: True	Use file magic and return data about the nature of the file. This uses the C(file) utility found on most Linux/Unix systems. This will add both RV(stat.mimetype) and RV(stat.charset) fields to the return, if possible. In Ansible 2.3 this option changed from O(mime) to O(get_mime) and the default changed to V(true). Version Added: 2.1
path path required		The full path of the file/object to get the facts of.

Examples

# Obtain the stats of /etc/foo.conf, and check that the file still belongs
# to 'root'. Fail otherwise.
- name: Get stats of a file
  ansible.builtin.stat:
    path: /etc/foo.conf
  register: st
- name: Fail if the file does not belong to 'root'
  ansible.builtin.fail:
    msg: "Whoops! file ownership has changed"
  when: st.stat.pw_name != 'root'

# Determine if a path exists and is a symlink. Note that if the path does
# not exist, and we test sym.stat.islnk, it will fail with an error. So
# therefore, we must test whether it is defined.
# Run this to understand the structure, the skipped ones do not pass the
# check performed by 'when'
- name: Get stats of the FS object
  ansible.builtin.stat:
    path: /path/to/something
  register: sym

- name: Print a debug message
  ansible.builtin.debug:
    msg: "islnk isn't defined (path doesn't exist)"
  when: sym.stat.islnk is not defined

- name: Print a debug message
  ansible.builtin.debug:
    msg: "islnk is defined (path must exist)"
  when: sym.stat.islnk is defined

- name: Print a debug message
  ansible.builtin.debug:
    msg: "Path exists and is a symlink"
  when: sym.stat.islnk is defined and sym.stat.islnk

- name: Print a debug message
  ansible.builtin.debug:
    msg: "Path exists and isn't a symlink"
  when: sym.stat.islnk is defined and sym.stat.islnk == False


# Determine if a path exists and is a directory.  Note that we need to test
# both that p.stat.isdir actually exists, and also that it's set to true.
- name: Get stats of the FS object
  ansible.builtin.stat:
    path: /path/to/something
  register: p
- name: Print a debug message
  ansible.builtin.debug:
    msg: "Path exists and is a directory"
  when: p.stat.isdir is defined and p.stat.isdir

- name: Do not calculate the checksum
  ansible.builtin.stat:
    path: /path/to/myhugefile
    get_checksum: no

- name: Use sha256 to calculate the checksum
  ansible.builtin.stat:
    path: /path/to/something
    checksum_algorithm: sha256

Return Values

Key	Data Type	Description	Returned
stat	dict	Dictionary containing all the stat data, some platforms might add additional fields.	success

Authors

• Bruce Pennypacker (@bpennypacker)