win_stat – Get information about Windows files
Synopsis
- Returns information about a Windows file.
- For non-Windows targets, use the stat module instead.
Parameters
| Parameter | Choices/Defaults | Comments |
|---|---|---|
| checksum_algorithm string added in 2.3 |
| Algorithm to determine checksum of file. Will throw an error if the host is unable to use specified algorithm. |
| follow boolean added in 2.8 |
| Whether to follow symlinks or junction points. In the case of path pointing to another link, then that will be followed until no more links are found. |
| get_checksum boolean added in 2.1 |
| Whether to return a checksum of the file (default sha1) |
| get_md5 boolean |
| Whether to return the checksum sum of the file. Between Ansible 1.9 and Ansible 2.2 this is no longer an MD5, but a SHA1 instead. As of Ansible 2.3 this is back to an MD5. Will return None if host is unable to use specified algorithm. 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=yes with checksum_algorithm=md5 to return an md5 hash under the checksum return value. |
| path path / required | The full path of the file/object to get the facts of; both forward and back slashes are accepted. aliases: dest, name |
See Also
See also
- stat – Retrieve file or file system status
- The official documentation on the stat module.
- win_acl – Set file/directory/registry permissions for a system user or group
- The official documentation on the win_acl module.
- win_file – Creates, touches or removes files or directories
- The official documentation on the win_file module.
- win_owner – Set owner
- The official documentation on the win_owner module.
Examples
- name: Obtain information about a file
win_stat:
path: C:\foo.ini
register: file_info
- name: Obtain information about a folder
win_stat:
path: C:\bar
register: folder_info
- name: Get MD5 checksum of a file
win_stat:
path: C:\foo.ini
get_checksum: yes
checksum_algorithm: md5
register: md5_checksum
- debug:
var: md5_checksum.stat.checksum
- name: Get SHA1 checksum of file
win_stat:
path: C:\foo.ini
get_checksum: yes
register: sha1_checksum
- debug:
var: sha1_checksum.stat.checksum
- name: Get SHA256 checksum of file
win_stat:
path: C:\foo.ini
get_checksum: yes
checksum_algorithm: sha256
register: sha256_checksum
- debug:
var: sha256_checksum.stat.checksum
Return Values
Common return values are documented here, the following are the fields unique to this module:
| Key | Returned | Description | |
|---|---|---|---|
| changed boolean | always | Whether anything was changed Sample: True | |
| stat complex | success | dictionary containing all the stat data | |
| attributes string | success, path exists | Attributes of the file at path in raw form. Sample: Archive, Hidden | |
| checksum string | success, path exist, path is a file, get_checksum == True checksum_algorithm specified is supported | The checksum of a file based on checksum_algorithm specified. Sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98 | |
| creationtime float | success, path exists | The create time of the file represented in seconds since epoch. Sample: 1477984205.15 | |
| exists boolean | success | If the path exists or not. Sample: True | |
| extension string | success, path exists, path is a file | The extension of the file at path. Sample: .ps1 | |
| filename string | success, path exists, path is a file | The name of the file (without path). Sample: foo.ini | |
| hlnk_targets list | success, path exists | List of other files pointing to the same file (hard links), excludes the current file. Sample: ['C:\\temp\\file.txt', 'C:\\Windows\\update.log'] | |
| isarchive boolean | success, path exists | If the path is ready for archiving or not. Sample: True | |
| isdir boolean | success, path exists | If the path is a directory or not. Sample: True | |
| ishidden boolean | success, path exists | If the path is hidden or not. Sample: True | |
| isjunction boolean | success, path exists | If the path is a junction point or not. Sample: True | |
| islnk boolean | success, path exists | If the path is a symbolic link or not. Sample: True | |
| isreadonly boolean | success, path exists | If the path is read only or not. Sample: True | |
| isreg boolean | success, path exists | If the path is a regular file. Sample: True | |
| isshared boolean | success, path exists | If the path is shared or not. Sample: True | |
| lastaccesstime float | success, path exists | The last access time of the file represented in seconds since epoch. Sample: 1477984205.15 | |
| lastwritetime float | success, path exists | The last modification time of the file represented in seconds since epoch. Sample: 1477984205.15 | |
| lnk_source string | success, path exists and the path is a symbolic link or junction point | Target of the symlink normalized for the remote filesystem. Sample: C:\temp\link | |
| lnk_target string | success, path exists and the path is a symbolic link or junction point | Target of the symlink. Note that relative paths remain relative. Sample: ..\link | |
| md5 string | success, path exist, path is a file, get_md5 == True | The MD5 checksum of a file (Between Ansible 1.9 and Ansible 2.2 this was returned as a SHA1 hash), will be removed in Ansible 2.9. Sample: 09cb79e8fc7453c84a07f644e441fd81623b7f98 | |
| nlink integer | success, path exists | Number of links to the file (hard links). Sample: 1 | |
| owner string | success, path exists | The owner of the file. Sample: BUILTIN\Administrators | |
| path string | success, path exists, file exists | The full absolute path to the file. Sample: C:\foo.ini | |
| sharename string | success, path exists, file is a directory and isshared == True | The name of share if folder is shared. Sample: file-share | |
| size integer | success, path exists, file is not a link | The size in bytes of a file or folder. Sample: 1024 | |
Status
- This module is guaranteed to have no backward incompatible interface changes going forward. [stableinterface]
- This module is maintained by the Ansible Core Team. [core]
Red Hat Support
More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.
Authors
- Chris Church (@cchurch)
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/win_stat_module.html