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.
Parameters
| Parameter | Choices/Defaults | Comments |
|---|---|---|
| checksum_algorithm
(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,
md5 can be unavailable if the host is FIPS-140 compliant.
aliases: checksum, checksum_algo |
| follow
bool
|
|
Whether to follow symlinks.
|
| get_attributes
bool
(added in 2.3)
|
|
Get file attributes using lsattr tool if present.
aliases: attr, attributes |
| get_checksum
bool
(added in 1.8)
|
|
Whether to return a checksum of the file (default sha1).
|
| get_md5
bool
|
|
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_mime
bool
(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 2.3 this option changed from 'mime' to 'get_mime' and the default changed to 'Yes'.
aliases: mime, mime_type, mime-type |
| path
required
|
The full path of the file/object to get the facts of.
|
Notes
Note
- For Windows targets, use the win_stat module instead.
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 module:
| Key | Returned | Description | |
|---|---|---|---|
| stat
complex
|
success |
dictionary containing all the stat data, some platforms might add additional fields
|
|
| exists
boolean
|
success |
if the destination path actually exists or not
Sample:
True
|
|
| path
string
|
success and if path exists |
The full path of the file/object to get the facts of
Sample:
/path/to/file
|
|
| mode
octal
|
success, path exists and user can read stats |
Unix permissions of the file in octal
Sample:
1755
|
|
| isdir
boolean
|
success, path exists and user can read stats |
Tells you if the path is a directory
|
|
| ischr
boolean
|
success, path exists and user can read stats |
Tells you if the path is a character device
|
|
| isblk
boolean
|
success, path exists and user can read stats |
Tells you if the path is a block device
|
|
| isreg
boolean
|
success, path exists and user can read stats |
Tells you if the path is a regular file
Sample:
True
|
|
| isfifo
boolean
|
success, path exists and user can read stats |
Tells you if the path is a named pipe
|
|
| islnk
boolean
|
success, path exists and user can read stats |
Tells you if the path is a symbolic link
|
|
| issock
boolean
|
success, path exists and user can read stats |
Tells you if the path is a unix domain socket
|
|
| uid
int
|
success, path exists and user can read stats |
Numeric id representing the file owner
Sample:
1003
|
|
| gid
int
|
success, path exists and user can read stats |
Numeric id representing the group of the owner
Sample:
1003
|
|
| size
int
|
success, path exists and user can read stats |
Size in bytes for a plain file, amount of data for some special files
Sample:
203
|
|
| inode
int
|
success, path exists and user can read stats |
Inode number of the path
Sample:
12758
|
|
| dev
int
|
success, path exists and user can read stats |
Device the inode resides on
Sample:
33
|
|
| nlink
int
|
success, path exists and user can read stats |
Number of links to the inode (hard links)
Sample:
1
|
|
| atime
float
|
success, path exists and user can read stats |
Time of last access
Sample:
1424348972.575
|
|
| mtime
float
|
success, path exists and user can read stats |
Time of last modification
Sample:
1424348972.575
|
|
| ctime
float
|
success, path exists and user can read stats |
Time of last metadata update or creation (depends on OS)
Sample:
1424348972.575
|
|
| wusr
boolean
|
success, path exists and user can read stats |
Tells you if the owner has write permission
Sample:
True
|
|
| rusr
boolean
|
success, path exists and user can read stats |
Tells you if the owner has read permission
Sample:
True
|
|
| xusr
boolean
|
success, path exists and user can read stats |
Tells you if the owner has execute permission
Sample:
True
|
|
| wgrp
boolean
|
success, path exists and user can read stats |
Tells you if the owner's group has write permission
|
|
| rgrp
boolean
|
success, path exists and user can read stats |
Tells you if the owner's group has read 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
|
|
| woth
boolean
|
success, path exists and user can read stats |
Tells you if others have write permission
|
|
| roth
boolean
|
success, path exists and user can read stats |
Tells you if others have read permission
Sample:
True
|
|
| xoth
boolean
|
success, path exists and user can read stats |
Tells you if others have execute permission
Sample:
True
|
|
| isuid
boolean
|
success, path exists and user can read stats |
Tells you if the invoking user's id matches the owner's id
|
|
| 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
|
|
| 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
|
|
| checksum
string
|
success, path exists, user can read stats, path supports hashing and supplied checksum algorithm is available |
hash of the path
Sample:
50ba294cdf28c0d5bcde25708df53346825a429f
|
|
| pw_name
string
|
success, path exists and user can read stats and installed python supports it |
User name of owner
Sample:
httpd
|
|
| gr_name
string
|
success, path exists and user can read stats and installed python supports it |
Group name of owner
Sample:
www-data
|
|
| mime_type
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:
PDF document, version 1.2
|
|
| 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
|
|
| 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
|
|
| 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
|
|
| 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
|
|
| attributes
list
(added in 2.3)
|
success, path exists and user can execute the path |
list of file attributes
Sample:
['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.
Maintenance
This module is flagged as core which means that it is maintained by the Ansible Core Team. See Module Maintenance & Support for more info.
For a list of other modules that are also maintained by the Ansible Core Team, see here.
Support
For more information about Red Hat’s support of this module, please refer to this Knowledge Base article
Author
- Bruce Pennypacker (@bpennypacker)
Hint
If you notice any issues in this documentation you can edit this document to improve it.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.6/modules/stat_module.html