ansible.builtin.stat – Retrieve file or file system status

Note

This module is part of ansible-base and included in all Ansible installations. In most cases, you can use the short module name stat even without specifying the collections: keyword. Despite that, we recommend you use the FQCN for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

New in version 1.3: of ansible.builtin

Synopsis

  • Retrieves facts for a file similar to the Linux/Unix ‘stat’ command.

  • For Windows targets, use the ansible.windows.win_stat module instead.

Parameters

Parameter Choices/Defaults Comments
checksum_algorithm
string
added in 2.0 of ansible.builtin
    Choices:
  • 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
follow
boolean
    Choices:
  • no ←
  • yes
Whether to follow symlinks.
get_attributes
boolean
added in 2.3 of ansible.builtin
    Choices:
  • no
  • yes ←
Get file attributes using lsattr tool if present.

aliases: attr, attributes
get_checksum
boolean
added in 1.8 of ansible.builtin
    Choices:
  • no
  • yes ←
Whether to return a checksum of the file.
get_mime
boolean
added in 2.1 of ansible.builtin
    Choices:
  • 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 Ansible 2.3 this option changed from 'mime' to 'get_mime' and the default changed to 'Yes'.

aliases: mime, mime_type, mime-type
path
path / required
The full path of the file/object to get the facts of.

aliases: dest, name

Notes

Note

  • Supports check_mode.

See Also

See also

ansible.builtin.file

The official documentation on the ansible.builtin.file module.

ansible.windows.win_stat

The official documentation on the ansible.windows.win_stat module.

Examples

# Obtain the stats of /etc/foo.conf, and check that the file still belongs
# to 'root'. Fail otherwise.
- name: Get stats of a file
  ansible.builtin.stat:
    path: /etc/foo.conf
  register: st
- name: Fail if the file does not belong to 'root'
  ansible.builtin.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'
- name: Get stats of the FS object
  ansible.builtin.stat:
    path: /path/to/something
  register: sym

- name: Print a debug message
  ansible.builtin.debug:
    msg: "islnk isn't defined (path doesn't exist)"
  when: sym.stat.islnk is not defined

- name: Print a debug message
  ansible.builtin.debug:
    msg: "islnk is defined (path must exist)"
  when: sym.stat.islnk is defined

- name: Print a debug message
  ansible.builtin.debug:
    msg: "Path exists and is a symlink"
  when: sym.stat.islnk is defined and sym.stat.islnk

- name: Print a debug message
  ansible.builtin.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.
- name: Get stats of the FS object
  ansible.builtin.stat:
    path: /path/to/something
  register: p
- name: Print a debug message
  ansible.builtin.debug:
    msg: "Path exists and is a directory"
  when: p.stat.isdir is defined and p.stat.isdir

- name: Don not do checksum
  ansible.builtin.stat:
    path: /path/to/myhugefile
    get_checksum: no

- name: Use sha256 to calculate checksum
  ansible.builtin.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.
 
atime
float
success, path exists and user can read stats
Time of last access

Sample:
1424348972.575
 
attributes
list / elements=string
added in 2.3 of ansible.builtin
 success, path exists and user can execute the path
list of file attributes

Sample:
['immutable', 'extent']
 
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
 
checksum
string
success, path exists, user can read stats, path supports hashing and supplied checksum algorithm is available
hash of the path

Sample:
50ba294cdf28c0d5bcde25708df53346825a429f
 
ctime
float
success, path exists and user can read stats
Time of last metadata update or creation (depends on OS)

Sample:
1424348972.575
 
dev
integer
success, path exists and user can read stats
Device the inode resides on

Sample:
33
 
executable
boolean
added in 2.2 of ansible.builtin
 success, path exists and user can execute the path
Tells you if the invoking user has execute permission on the path
 
exists
boolean
success
If the destination path actually exists or not

Sample:
True
 
gid
integer
success, path exists and user can read stats
Numeric id representing the group of the owner

Sample:
1003
 
gr_name
string
success, path exists and user can read stats and installed python supports it
Group name of owner

Sample:
www-data
 
inode
integer
success, path exists and user can read stats
Inode number of the path

Sample:
12758
 
isblk
boolean
success, path exists and user can read stats
Tells you if the path is a block device
 
ischr
boolean
success, path exists and user can read stats
Tells you if the path is a character device
 
isdir
boolean
success, path exists and user can read stats
Tells you if the path is a directory
 
isfifo
boolean
success, path exists and user can read stats
Tells you if the path is a named pipe
 
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
 
islnk
boolean
success, path exists and user can read stats
Tells you if the path is a symbolic link
 
isreg
boolean
success, path exists and user can read stats
Tells you if the path is a regular file

Sample:
True
 
issock
boolean
success, path exists and user can read stats
Tells you if the path is a unix domain socket
 
isuid
boolean
success, path exists and user can read stats
Tells you if the invoking user's id matches the owner's 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 of ansible.builtin
 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
 
mimetype
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:
application/pdf; charset=binary
 
mode
string
success, path exists and user can read stats
Unix permissions of the file in octal representation as a string

Sample:
1755
 
mtime
float
success, path exists and user can read stats
Time of last modification

Sample:
1424348972.575
  nlink
integer
success, path exists and user can read stats
Number of links to the inode (hard links)

Sample:
1
 
path
string
success and if path exists
The full path of the file/object to get the facts of

Sample:
/path/to/file
 
pw_name
string
success, path exists and user can read stats and installed python supports it
User name of owner

Sample:
httpd
 
readable
boolean
added in 2.2 of ansible.builtin
 success, path exists and user can read the path
Tells you if the invoking user has the right to read the path
 
rgrp
boolean
success, path exists and user can read stats
Tells you if the owner's group has read permission

Sample:
True
 
roth
boolean
success, path exists and user can read stats
Tells you if others have read permission

Sample:
True
 
rusr
boolean
success, path exists and user can read stats
Tells you if the owner has read permission

Sample:
True
 
size
integer
success, path exists and user can read stats
Size in bytes for a plain file, amount of data for some special files

Sample:
203
 
uid
integer
success, path exists and user can read stats
Numeric id representing the file owner

Sample:
1003
 
wgrp
boolean
success, path exists and user can read stats
Tells you if the owner's group has write permission
 
woth
boolean
success, path exists and user can read stats
Tells you if others have write permission
 
writeable
boolean
added in 2.2 of ansible.builtin
 success, path exists and user can write the path
Tells you if the invoking user has the right to write the path
 
wusr
boolean
success, path exists and user can read stats
Tells you if the owner has write 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
 
xoth
boolean
success, path exists and user can read stats
Tells you if others have execute permission

Sample:
True
 
xusr
boolean
success, path exists and user can read stats
Tells you if the owner has execute permission

Sample:
True


Authors

  • Bruce Pennypacker (@bpennypacker)