ansible / ansible.builtin / v2.15.10 / module / stat Retrieve file or file system status | "added in version" 1.3 of ansible.builtin" Authors: Bruce Pennypacker (@bpennypacker)ansible.builtin.stat (v2.15.10) — module
pip
Install with pip install ansible-core==2.15.10
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 C(mimetype) and C(charset) fields to the return, if possible. - In Ansible 2.3 this option changed from I(mime) to I(get_mime) and the default changed to C(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, 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 I(get_mime) option was true, will return C(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 md5: description: md5 hash of the file; 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 I(get_mime) option was true, will return C(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: complex