ansible / ansible.builtin / v2.8.15 / module / stat Retrieve file or file system status | "added in version" 1.3 of ansible.builtin" Authors: Bruce Pennypacker (@bpennypacker) stableinterface | supported by coreansible.builtin.stat (v2.8.15) — module
pip
Install with pip install ansible==2.8.15
Retrieves facts for a file similar to the Linux/Unix 'stat' command.
For Windows targets, use the M(win_stat) module instead.
# 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
path: 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_md5: default: false description: - 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 C(yes) to C(no) in Ansible 2.5 and will be removed altogether in Ansible 2.9. - Use C(get_checksum=true) with C(checksum_algorithm=md5) to return an md5 hash under the C(checksum) return value. 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 `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'. 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, C(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 `mime` option was true, will return 'unknown' on error. sample: us-ascii type: str checksum: description: hash of the path 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 the execute 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 and user can read stats 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 md5: description: md5 hash of the path; this will be removed in Ansible 2.9 in favor of the checksum return value returned: success, path exists and user can read stats and path supports hashing and md5 is supported sample: f88fa92d8cf2eeecf4c0a50ccc96d0c0 type: str mimetype: description: file magic data or mime-type returned: success, path exists and user can read stats and installed python supports it and the `mime` option was true, will return '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 and user can read stats 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 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: complex