Documentation

stat - retrieve file or file system status

New in version 1.3.

Synopsis

  • Retrieves facts for a file similar to the linux/unix ‘stat’ command.

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_algo, checksum
follow
no
Whether to follow symlinks
get_attributes
(added in 2.3)
no True
Get file attributes using lsattr tool if present.

aliases: attributes, attr
get_checksum
(added in 1.8)
no True
Whether to return a checksum of the file (default sha1)
get_md5
no True
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 True
  • True
  • False
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
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 Original path 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 boolean ['immutable', 'extent']


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.

Support

This module is maintained by those with core commit privileges

For more information on what this means please read Module Support

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