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.
  • For Windows targets, use the module_docs/win_stat module instead.

Options

parameter
required
default
choices
comments
get_checksum
(added in 1.8)
no
yes
  • yes
  • no
Whether to return a checksum of the file (default sha1).
follow
no
no
  • yes
  • no
Whether to follow symlinks.
checksum_algorithm
(added in 2.0)
no
sha1
  • md5
  • sha1
  • sha224
  • sha256
  • sha384
  • sha512
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, md5 can be unavailable if the host is FIPS-140 compliant.

aliases: checksum, checksum_algo
path
yes
The full path of the file/object to get the facts of.
get_mime
(added in 2.1)
no
yes
  • yes
  • no
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
get_md5
no
no
  • yes
  • no
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 yes to no in Ansible 2.5 and will be removed altogether in Ansible 2.9.
Use get_checksum=true with checksum_algorithm=md5 to return an md5 hash under the checksum return value.
get_attributes
(added in 2.3)
no
yes
  • yes
  • no
Get file attributes using lsattr tool if present.

aliases: attr, attributes

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, the following are the fields unique to this {{plugin_type}}:

name
description
returned
type
sample
stat
dictionary containing all the stat data, some platforms might add additional fields
success
complex
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; this will be removed in Ansible 2.9 in favor of the checksum return value
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

Author

  • Bruce Pennypacker (@bpennypacker)

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 support of this module, please refer to this Knowledge Base article

If you want to help with development, please read Community Information & Contributing, Testing Ansible and Developing Modules.