stat - Retrieve file or file system status

New in version 1.3.

Synopsis
Options
Examples
Return Values
Notes
- Status
- Maintenance Info

Synopsis

Retrieves facts for a file similar to the linux/unix ‘stat’ command.
For Windows targets, use the win_stat module instead.

Options

parameter	required	default	choices	comments
checksum_algorithm (added in 2.0)	no	sha1	sha1 sha224 sha256 sha384 sha512	Algorithm to determine checksum of file. Will throw an error if the host is unable to use specified algorithm. aliases: checksum, checksum_algo
follow	no	no	no yes	Whether to follow symlinks.
get_attributes (added in 2.3)	no	yes	no yes	Get file attributes using lsattr tool if present. aliases: attr, attributes
get_checksum (added in 1.8)	no	yes	no yes	Whether to return a checksum of the file (default sha1).
get_md5	no	yes	no yes	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).
get_mime (added in 2.1)	no	yes	no yes	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 2.3 this option changed from 'mime' to 'get_mime' and the default changed to 'Yes'. aliases: mime, mime_type, mime-type
path	yes			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.
- 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 md5 checksum
- stat:
    path: /path/to/myhugefile
    get_md5: no

# Use sha256 to calculate checksum
- stat:
    path: /path/to/something
    checksum_algorithm: sha256

Return Values

Common return values are documented here Return Values, the following are the fields unique to this module:

name

description

returned

type

sample

stat

dictionary containing all the stat data, some platforms might add additional fields

success

complex

contains:

name	description	returned	type	sample
isuid	Tells you if the invoking user's id matches the owner's id	success, path exists and user can read stats	boolean	False
uid	Numeric id representing the file owner	success, path exists and user can read stats	int	1003
exists	if the destination path actually exists or not	success	boolean	True
lnk_target	Target of the symlink. Note that relative paths remain relative	success, path exists and user can read stats and the path is a symbolic link	string	../foobar/21102015-1445431274-908472971
woth	Tells you if others have write permission	success, path exists and user can read stats	boolean	False
mtime	Time of last modification	success, path exists and user can read stats	float	1424348972.58
inode	Inode number of the path	success, path exists and user can read stats	int	12758
isgid	Tells you if the invoking user's group id matches the owner's group id	success, path exists and user can read stats	boolean	False
size	Size in bytes for a plain file, amount of data for some special files	success, path exists and user can read stats	int	203
wgrp	Tells you if the owner's group has write permission	success, path exists and user can read stats	boolean	False
executable	Tells you if the invoking user has the execute the path	success, path exists and user can execute the path	boolean	False
charset	file character set or encoding	success, path exists and user can read stats and installed python supports it and the `mime` option was true, will return 'unknown' on error.	string	us-ascii
readable	Tells you if the invoking user has the right to read the path	success, path exists and user can read the path	boolean	False
isreg	Tells you if the path is a regular file	success, path exists and user can read stats	boolean	True
pw_name	User name of owner	success, path exists and user can read stats and installed python supports it	string	httpd
gid	Numeric id representing the group of the owner	success, path exists and user can read stats	int	1003
ischr	Tells you if the path is a character device	success, path exists and user can read stats	boolean	False
mime_type	file magic data or mime-type	success, path exists and user can read stats and installed python supports it and the `mime` option was true, will return 'unknown' on error.	string	PDF document, version 1.2
wusr	Tells you if the owner has write permission	success, path exists and user can read stats	boolean	True
writeable	Tells you if the invoking user has the right to write the path	success, path exists and user can write the path	boolean	False
xoth	Tells you if others have execute permission	success, path exists and user can read stats	boolean	True
rusr	Tells you if the owner has read permission	success, path exists and user can read stats	boolean	True
nlink	Number of links to the inode (hard links)	success, path exists and user can read stats	int	1
issock	Tells you if the path is a unix domain socket	success, path exists and user can read stats	boolean	False
rgrp	Tells you if the owner's group has read permission	success, path exists and user can read stats	boolean	True
gr_name	Group name of owner	success, path exists and user can read stats and installed python supports it	string	www-data
path	The full path of the file/object to get the facts of	success and if path exists	string	/path/to/file
xusr	Tells you if the owner has execute permission	success, path exists and user can read stats	boolean	True
atime	Time of last access	success, path exists and user can read stats	float	1424348972.58
lnk_source	Target of the symlink normalized for the remote filesystem	success, path exists and user can read stats and the path is a symbolic link	string	/home/foobar/21102015-1445431274-908472971
md5	md5 hash of the path	success, path exists and user can read stats and path supports hashing and md5 is supported	string	f88fa92d8cf2eeecf4c0a50ccc96d0c0
isdir	Tells you if the path is a directory	success, path exists and user can read stats	boolean	False
ctime	Time of last metadata update or creation (depends on OS)	success, path exists and user can read stats	float	1424348972.58
isblk	Tells you if the path is a block device	success, path exists and user can read stats	boolean	False
xgrp	Tells you if the owner's group has execute permission	success, path exists and user can read stats	boolean	True
dev	Device the inode resides on	success, path exists and user can read stats	int	33
roth	Tells you if others have read permission	success, path exists and user can read stats	boolean	True
isfifo	Tells you if the path is a named pipe	success, path exists and user can read stats	boolean	False
mode	Unix permissions of the file in octal	success, path exists and user can read stats	octal	1755
checksum	hash of the path	success, path exists, user can read stats, path supports hashing and supplied checksum algorithm is available	string	50ba294cdf28c0d5bcde25708df53346825a429f
islnk	Tells you if the path is a symbolic link	success, path exists and user can read stats	boolean	False
attributes	list of file attributes	success, path exists and user can execute the path	list	['immutable', 'extent']

Notes

Note

For Windows targets, use the win_stat module instead.

Status

This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.

Maintenance Info

For more information about Red Hat’s this support of this module, please refer to this knowledge base article<https://access.redhat.com/articles/rhel-top-support-policies>

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/stat_module.html