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

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
• Parameters
• Notes
• See Also
• Examples
• Return Values

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	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	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_mime boolean	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

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

---