ansible.builtin.stat module – Retrieve file or file system status
Note
This module is part of ansible-core
and included in all Ansible
installations. In most cases, you can use the short
module name
stat
even without specifying the collections:
keyword.
However, we recommend you use the FQCN for easy linking to the
module documentation and to avoid conflicting with other collections that may have
the same module name.
Synopsis
Retrieves facts for a file similar to the Linux/Unix ‘stat’ command.
For Windows targets, use the ansible.windows.win_stat module instead.
Parameters
Parameter |
Comments |
---|---|
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, Choices:
|
|
Whether to follow symlinks. Choices:
|
|
Get file attributes using lsattr tool if present. Choices:
|
|
Whether to return a checksum of the file. Choices:
|
|
Use file magic and return data about the nature of the file. this uses the ‘file’ utility found on most Linux/Unix systems. This will add both In Ansible 2.3 this option changed from mime to get_mime and the default changed to Choices:
|
|
The full path of the file/object to get the facts of. |
Attributes
Attribute |
Support |
Description |
---|---|---|
Support: full |
Can run in check_mode and return changed status prediction without modifying target |
|
Support: none |
Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode |
|
Platform: posix |
Target OS/families that can be operated against |
See Also
See also
- ansible.builtin.file
Manage files and file properties.
- ansible.windows.win_stat
Get information about Windows files.
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
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
Dictionary containing all the stat data, some platforms might add additional fields. Returned: success |
|
Time of last access Returned: success, path exists and user can read stats Sample: |
|
list of file attributes Returned: success, path exists and user can execute the path Sample: |
|
file character set or encoding Returned: success, path exists and user can read stats and installed python supports it and the mime option was true, will return Sample: |
|
hash of the file Returned: success, path exists, user can read stats, path supports hashing and supplied checksum algorithm is available Sample: |
|
Time of last metadata update or creation (depends on OS) Returned: success, path exists and user can read stats Sample: |
|
Device the inode resides on Returned: success, path exists and user can read stats Sample: |
|
Tells you if the invoking user has execute permission on the path Returned: success, path exists and user can execute the path Sample: |
|
If the destination path actually exists or not Returned: success Sample: |
|
Numeric id representing the group of the owner Returned: success, path exists and user can read stats Sample: |
|
Group name of owner Returned: success, path exists, user can read stats, owner group can be looked up and installed python supports it Sample: |
|
Inode number of the path Returned: success, path exists and user can read stats Sample: |
|
Tells you if the path is a block device Returned: success, path exists and user can read stats Sample: |
|
Tells you if the path is a character device Returned: success, path exists and user can read stats Sample: |
|
Tells you if the path is a directory Returned: success, path exists and user can read stats Sample: |
|
Tells you if the path is a named pipe Returned: success, path exists and user can read stats Sample: |
|
Tells you if the invoking user’s group id matches the owner’s group id Returned: success, path exists and user can read stats Sample: |
|
Tells you if the path is a symbolic link Returned: success, path exists and user can read stats Sample: |
|
Tells you if the path is a regular file Returned: success, path exists and user can read stats Sample: |
|
Tells you if the path is a unix domain socket Returned: success, path exists and user can read stats Sample: |
|
Tells you if the invoking user’s id matches the owner’s id Returned: success, path exists and user can read stats Sample: |
|
Target of the symlink normalized for the remote filesystem Returned: success, path exists and user can read stats and the path is a symbolic link Sample: |
|
Target of the symlink. Note that relative paths remain relative Returned: success, path exists and user can read stats and the path is a symbolic link Sample: |
|
md5 hash of the file; this will be removed in Ansible 2.9 in favor of the checksum return value Returned: success, path exists and user can read stats and path supports hashing and md5 is supported Sample: |
|
file magic data or mime-type Returned: success, path exists and user can read stats and installed python supports it and the mime option was true, will return Sample: |
|
Unix permissions of the file in octal representation as a string Returned: success, path exists and user can read stats Sample: |
|
Time of last modification Returned: success, path exists and user can read stats Sample: |
|
Number of links to the inode (hard links) Returned: success, path exists and user can read stats Sample: |
|
The full path of the file/object to get the facts of Returned: success and if path exists Sample: |
|
User name of owner Returned: success, path exists, user can read stats, owner name can be looked up and installed python supports it Sample: |
|
Tells you if the invoking user has the right to read the path Returned: success, path exists and user can read the path Sample: |
|
Tells you if the owner’s group has read permission Returned: success, path exists and user can read stats Sample: |
|
Tells you if others have read permission Returned: success, path exists and user can read stats Sample: |
|
Tells you if the owner has read permission Returned: success, path exists and user can read stats Sample: |
|
Size in bytes for a plain file, amount of data for some special files Returned: success, path exists and user can read stats Sample: |
|
Numeric id representing the file owner Returned: success, path exists and user can read stats Sample: |
|
The version/generation attribute of a file according to the filesystem Returned: success, path exists, user can execute the path, lsattr is available and filesystem supports Sample: |
|
Tells you if the owner’s group has write permission Returned: success, path exists and user can read stats Sample: |
|
Tells you if others have write permission Returned: success, path exists and user can read stats Sample: |
|
Tells you if the invoking user has the right to write the path Returned: success, path exists and user can write the path Sample: |
|
Tells you if the owner has write permission Returned: success, path exists and user can read stats Sample: |
|
Tells you if the owner’s group has execute permission Returned: success, path exists and user can read stats Sample: |
|
Tells you if others have execute permission Returned: success, path exists and user can read stats Sample: |
|
Tells you if the owner has execute permission Returned: success, path exists and user can read stats Sample: |