stat – Retrieve file or file system status

From Get docs
Ansible/docs/2.8/modules/stat module


stat – Retrieve file or file system status

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

string

added in 2.0

  • 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

  • no

  • yes

Whether to follow symlinks.

get_attributes

boolean

added in 2.3

  • no
  • yes

Get file attributes using lsattr tool if present.


aliases: attr, attributes

get_checksum

boolean

  • no
  • yes

Whether to return a checksum of the file.

get_md5

boolean

  • 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).

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

boolean

added in 2.1

  • 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.



See Also

See also

file – Manage files and file properties
The official documentation on the file module.
win_stat – Get information about Windows files
The official documentation on the win_stat module.


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 checksum
- stat:
    path: /path/to/myhugefile
    get_checksum: 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


atime

float

success, path exists and user can read stats

Time of last access


Sample:

1424348972.575

attributes

list

added in 2.3

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

success, path exists and user can execute the path

Tells you if the invoking user has the execute 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

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

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

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




Status

Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

Authors

  • 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.8/modules/stat_module.html