Try SpotterRetrieve file or file system status
| "added in version" 1.3 of ansible.builtin"
Authors: Bruce Pennypacker (@bpennypacker)
pipInstall with pip install ansible-core==2.16.5
Retrieves facts for a file similar to the Linux/Unix 'stat' command.
For Windows targets, use the M(ansible.windows.win_stat) module instead.
# 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: Do not calculate the checksum
ansible.builtin.stat:
path: /path/to/myhugefile
get_checksum: no
- name: Use sha256 to calculate the checksum
ansible.builtin.stat:
path: /path/to/something
checksum_algorithm: sha256
path:
aliases:
- dest
- name
description:
- The full path of the file/object to get the facts of.
required: true
type: path
follow:
default: false
description:
- Whether to follow symlinks.
type: bool
get_mime:
aliases:
- mime
- mime_type
- mime-type
default: true
description:
- 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 RV(stat.mimetype) and RV(stat.charset) fields to the return,
if possible.
- In Ansible 2.3 this option changed from O(mime) to O(get_mime) and the default changed
to V(true).
type: bool
version_added: '2.1'
version_added_collection: ansible.builtin
get_checksum:
default: true
description:
- Whether to return a checksum of the file.
type: bool
version_added: '1.8'
version_added_collection: ansible.builtin
get_attributes:
aliases:
- attr
- attributes
default: true
description:
- Get file attributes using lsattr tool if present.
type: bool
version_added: '2.3'
version_added_collection: ansible.builtin
checksum_algorithm:
aliases:
- checksum
- checksum_algo
choices:
- md5
- sha1
- sha224
- sha256
- sha384
- sha512
default: sha1
description:
- 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, V(md5) can be unavailable
if the host is FIPS-140 compliant.
type: str
version_added: '2.0'
version_added_collection: ansible.builtin
stat:
contains:
atime:
description: Time of last access
returned: success, path exists and user can read stats
sample: 1424348972.575
type: float
attributes:
description: list of file attributes
returned: success, path exists and user can execute the path
sample:
- immutable
- extent
type: list
version_added: 2.3
version_added_collection: ansible.builtin
charset:
description: file character set or encoding
returned: success, path exists and user can read stats and installed python
supports it and the O(get_mime) option was V(true), will return V(unknown)
on error.
sample: us-ascii
type: str
checksum:
description: hash of the file
returned: success, path exists, user can read stats, path supports hashing and
supplied checksum algorithm is available
sample: 50ba294cdf28c0d5bcde25708df53346825a429f
type: str
ctime:
description: Time of last metadata update or creation (depends on OS)
returned: success, path exists and user can read stats
sample: 1424348972.575
type: float
dev:
description: Device the inode resides on
returned: success, path exists and user can read stats
sample: 33
type: int
executable:
description: Tells you if the invoking user has execute permission on the path
returned: success, path exists and user can execute the path
sample: false
type: bool
version_added: 2.2
version_added_collection: ansible.builtin
exists:
description: If the destination path actually exists or not
returned: success
sample: true
type: bool
gid:
description: Numeric id representing the group of the owner
returned: success, path exists and user can read stats
sample: 1003
type: int
gr_name:
description: Group name of owner
returned: success, path exists, user can read stats, owner group can be looked
up and installed python supports it
sample: www-data
type: str
inode:
description: Inode number of the path
returned: success, path exists and user can read stats
sample: 12758
type: int
isblk:
description: Tells you if the path is a block device
returned: success, path exists and user can read stats
sample: false
type: bool
ischr:
description: Tells you if the path is a character device
returned: success, path exists and user can read stats
sample: false
type: bool
isdir:
description: Tells you if the path is a directory
returned: success, path exists and user can read stats
sample: false
type: bool
isfifo:
description: Tells you if the path is a named pipe
returned: success, path exists and user can read stats
sample: false
type: bool
isgid:
description: Tells you if the invoking user's group id matches the owner's group
id
returned: success, path exists and user can read stats
sample: false
type: bool
islnk:
description: Tells you if the path is a symbolic link
returned: success, path exists and user can read stats
sample: false
type: bool
isreg:
description: Tells you if the path is a regular file
returned: success, path exists and user can read stats
sample: true
type: bool
issock:
description: Tells you if the path is a unix domain socket
returned: success, path exists and user can read stats
sample: false
type: bool
isuid:
description: Tells you if the invoking user's id matches the owner's id
returned: success, path exists and user can read stats
sample: false
type: bool
lnk_source:
description: Target of the symlink normalized for the remote filesystem
returned: success, path exists and user can read stats and the path is a symbolic
link
sample: /home/foobar/21102015-1445431274-908472971
type: str
lnk_target:
description: Target of the symlink. Note that relative paths remain relative
returned: success, path exists and user can read stats and the path is a symbolic
link
sample: ../foobar/21102015-1445431274-908472971
type: str
version_added: 2.4
version_added_collection: ansible.builtin
mimetype:
description: file magic data or mime-type
returned: success, path exists and user can read stats and installed python
supports it and the O(get_mime) option was V(true), will return V(unknown)
on error.
sample: application/pdf; charset=binary
type: str
mode:
description: Unix permissions of the file in octal representation as a string
returned: success, path exists and user can read stats
sample: 1755
type: str
mtime:
description: Time of last modification
returned: success, path exists and user can read stats
sample: 1424348972.575
type: float
nlink:
description: Number of links to the inode (hard links)
returned: success, path exists and user can read stats
sample: 1
type: int
path:
description: The full path of the file/object to get the facts of
returned: success and if path exists
sample: /path/to/file
type: str
pw_name:
description: User name of owner
returned: success, path exists, user can read stats, owner name can be looked
up and installed python supports it
sample: httpd
type: str
readable:
description: Tells you if the invoking user has the right to read the path
returned: success, path exists and user can read the path
sample: false
type: bool
version_added: 2.2
version_added_collection: ansible.builtin
rgrp:
description: Tells you if the owner's group has read permission
returned: success, path exists and user can read stats
sample: true
type: bool
roth:
description: Tells you if others have read permission
returned: success, path exists and user can read stats
sample: true
type: bool
rusr:
description: Tells you if the owner has read permission
returned: success, path exists and user can read stats
sample: true
type: bool
size:
description: Size in bytes for a plain file, amount of data for some special
files
returned: success, path exists and user can read stats
sample: 203
type: int
uid:
description: Numeric id representing the file owner
returned: success, path exists and user can read stats
sample: 1003
type: int
version:
description: The version/generation attribute of a file according to the filesystem
returned: success, path exists, user can execute the path, lsattr is available
and filesystem supports
sample: '381700746'
type: str
version_added: 2.3
version_added_collection: ansible.builtin
wgrp:
description: Tells you if the owner's group has write permission
returned: success, path exists and user can read stats
sample: false
type: bool
woth:
description: Tells you if others have write permission
returned: success, path exists and user can read stats
sample: false
type: bool
writeable:
description: Tells you if the invoking user has the right to write the path
returned: success, path exists and user can write the path
sample: false
type: bool
version_added: 2.2
version_added_collection: ansible.builtin
wusr:
description: Tells you if the owner has write permission
returned: success, path exists and user can read stats
sample: true
type: bool
xgrp:
description: Tells you if the owner's group has execute permission
returned: success, path exists and user can read stats
sample: true
type: bool
xoth:
description: Tells you if others have execute permission
returned: success, path exists and user can read stats
sample: true
type: bool
xusr:
description: Tells you if the owner has execute permission
returned: success, path exists and user can read stats
sample: true
type: bool
description: Dictionary containing all the stat data, some platforms might add additional
fields.
returned: success
type: dict