stat – Retrieve file or file system status
stat – Retrieve file or file system status
Synopsis
- Retrieves facts for a file similar to the Linux/Unix ‘stat’ command.
- For Windows targets, use the win_stat module instead.
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
checksum_algorithm string added in 2.0 |
|
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,
|
follow boolean |
|
Whether to follow symlinks. |
get_attributes boolean added in 2.3 |
|
Get file attributes using lsattr tool if present.
|
get_checksum boolean |
|
Whether to return a checksum of the file. |
get_md5 boolean |
|
Whether to return the md5 sum of the file. Will return None if not a regular file or if we're unable to use md5 (Common for FIPS-140 compliant systems). The default of this option changed from Use |
get_mime boolean added in 2.1 |
|
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 `mime_type` and 'charset' fields to the return, if possible. In Ansible 2.3 this option changed from 'mime' to 'get_mime' and the default changed to 'Yes'.
|
path path / required |
The full path of the file/object to get the facts of. |
See Also
See also
- file – Manage files and file properties
- The official documentation on the file module.
- win_stat – Get information about Windows files
- The official documentation on the win_stat module.
Examples
# Obtain the stats of /etc/foo.conf, and check that the file still belongs
# to 'root'. Fail otherwise.
- stat:
path: /etc/foo.conf
register: st
- 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'
- stat:
path: /path/to/something
register: sym
- debug:
msg: "islnk isn't defined (path doesn't exist)"
when: sym.stat.islnk is not defined
- debug:
msg: "islnk is defined (path must exist)"
when: sym.stat.islnk is defined
- debug:
msg: "Path exists and is a symlink"
when: sym.stat.islnk is defined and sym.stat.islnk
- 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.
- stat:
path: /path/to/something
register: p
- debug:
msg: "Path exists and is a directory"
when: p.stat.isdir is defined and p.stat.isdir
# Don't do checksum
- stat:
path: /path/to/myhugefile
get_checksum: no
# Use sha256 to calculate checksum
- 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 | Returned | Description | |
---|---|---|---|
stat complex |
success |
dictionary containing all the stat data, some platforms might add additional fields
| |
atime float |
success, path exists and user can read stats |
Time of last access
Sample: 1424348972.575 | |
attributes list added in 2.3 |
success, path exists and user can execute the path |
list of file attributes
Sample: ['immutable', 'extent'] | |
charset string |
success, path exists and user can read stats and installed python supports it and the `mime` option was true, will return 'unknown' on error. |
file character set or encoding
Sample: us-ascii | |
checksum string |
success, path exists, user can read stats, path supports hashing and supplied checksum algorithm is available |
hash of the path
Sample: 50ba294cdf28c0d5bcde25708df53346825a429f | |
ctime float |
success, path exists and user can read stats |
Time of last metadata update or creation (depends on OS)
Sample: 1424348972.575 | |
dev integer |
success, path exists and user can read stats |
Device the inode resides on
Sample: 33 | |
executable boolean added in 2.2 |
success, path exists and user can execute the path |
Tells you if the invoking user has the execute the path
| |
exists boolean |
success |
If the destination path actually exists or not
Sample: True | |
gid integer |
success, path exists and user can read stats |
Numeric id representing the group of the owner
Sample: 1003 | |
gr_name string |
success, path exists and user can read stats and installed python supports it |
Group name of owner
Sample: www-data | |
inode integer |
success, path exists and user can read stats |
Inode number of the path
Sample: 12758 | |
isblk boolean |
success, path exists and user can read stats |
Tells you if the path is a block device
| |
ischr boolean |
success, path exists and user can read stats |
Tells you if the path is a character device
| |
isdir boolean |
success, path exists and user can read stats |
Tells you if the path is a directory
| |
isfifo boolean |
success, path exists and user can read stats |
Tells you if the path is a named pipe
| |
isgid boolean |
success, path exists and user can read stats |
Tells you if the invoking user's group id matches the owner's group id
| |
islnk boolean |
success, path exists and user can read stats |
Tells you if the path is a symbolic link
| |
isreg boolean |
success, path exists and user can read stats |
Tells you if the path is a regular file
Sample: True | |
issock boolean |
success, path exists and user can read stats |
Tells you if the path is a unix domain socket
| |
isuid boolean |
success, path exists and user can read stats |
Tells you if the invoking user's id matches the owner's id
| |
lnk_source string |
success, path exists and user can read stats and the path is a symbolic link |
Target of the symlink normalized for the remote filesystem
Sample: /home/foobar/21102015-1445431274-908472971 | |
lnk_target string added in 2.4 |
success, path exists and user can read stats and the path is a symbolic link |
Target of the symlink. Note that relative paths remain relative
Sample: ../foobar/21102015-1445431274-908472971 | |
md5 string |
success, path exists and user can read stats and path supports hashing and md5 is supported |
md5 hash of the path; this will be removed in Ansible 2.9 in favor of the checksum return value
Sample: f88fa92d8cf2eeecf4c0a50ccc96d0c0 | |
mimetype string |
success, path exists and user can read stats and installed python supports it and the `mime` option was true, will return 'unknown' on error. |
file magic data or mime-type
Sample: application/pdf; charset=binary | |
mode string |
success, path exists and user can read stats |
Unix permissions of the file in octal representation as a string
Sample: 1755 | |
mtime float |
success, path exists and user can read stats |
Time of last modification
Sample: 1424348972.575 | |
nlink integer |
success, path exists and user can read stats |
Number of links to the inode (hard links)
Sample: 1 | |
path string |
success and if path exists |
The full path of the file/object to get the facts of
Sample: /path/to/file | |
pw_name string |
success, path exists and user can read stats and installed python supports it |
User name of owner
Sample: httpd | |
readable boolean added in 2.2 |
success, path exists and user can read the path |
Tells you if the invoking user has the right to read the path
| |
rgrp boolean |
success, path exists and user can read stats |
Tells you if the owner's group has read permission
Sample: True | |
roth boolean |
success, path exists and user can read stats |
Tells you if others have read permission
Sample: True | |
rusr boolean |
success, path exists and user can read stats |
Tells you if the owner has read permission
Sample: True | |
size integer |
success, path exists and user can read stats |
Size in bytes for a plain file, amount of data for some special files
Sample: 203 | |
uid integer |
success, path exists and user can read stats |
Numeric id representing the file owner
Sample: 1003 | |
wgrp boolean |
success, path exists and user can read stats |
Tells you if the owner's group has write permission
| |
woth boolean |
success, path exists and user can read stats |
Tells you if others have write permission
| |
writeable boolean added in 2.2 |
success, path exists and user can write the path |
Tells you if the invoking user has the right to write the path
| |
wusr boolean |
success, path exists and user can read stats |
Tells you if the owner has write permission
Sample: True | |
xgrp boolean |
success, path exists and user can read stats |
Tells you if the owner's group has execute permission
Sample: True | |
xoth boolean |
success, path exists and user can read stats |
Tells you if others have execute permission
Sample: True | |
xusr boolean |
success, path exists and user can read stats |
Tells you if the owner has execute permission
Sample: True |
Status
- This module is guaranteed to have no backward incompatible interface changes going forward. [stableinterface]
- This module is maintained by the Ansible Core Team. [core]
Red Hat Support
More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.
Authors
- Bruce Pennypacker (@bpennypacker)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/stat_module.html