W3cubDocs

/Ansible

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.
  • 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–2017 Michael DeHaan
© 2017 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/stat_module.html