win_stat - returns information about a Windows file
New in version 1.7.
Synopsis
- Returns information about a Windows file.
- For non-Windows targets, use the stat module instead.
Parameters
| Parameter | Choices/Defaults | Comments |
|---|---|---|
| checksum_algorithm
(added in 2.3)
|
|
Algorithm to determine checksum of file. Will throw an error if the host is unable to use specified algorithm.
|
| get_checksum
(added in 2.1)
|
|
Whether to return a checksum of the file (default sha1)
|
| get_md5 |
|
Whether to return the checksum sum of the file. Between Ansible 1.9 and 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=true with checksum_algorithm=md5 to return an md5 hash under the checksum return value.
|
| path
required
|
The full path of the file/object to get the facts of; both forward and back slashes are accepted.
|
Notes
Note
- For non-Windows targets, use the stat module instead.
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
|
|
| exists
boolean
|
success |
If the path exists or not
Sample:
True
|
|
| 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
|
|
| lastwritetime
float
|
success, path exists |
The last modification time of the file represented in seconds since epoch
Sample:
1477984205.15
|
|
| creationtime
float
|
success, path exists |
The create time of the file represented in seconds since epoch
Sample:
1477984205.15
|
|
| lastaccesstime
float
|
success, path exists |
The last access time of the file represented in seconds since epoch
Sample:
1477984205.15
|
|
| nlink
int
|
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
|
|
| isarchive
boolean
|
success, path exists |
If the path is ready for archiving or not
Sample:
True
|
|
| ishidden
boolean
|
success, path exists |
If the path is hidden or not
Sample:
True
|
|
| 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
|
|
| size
int
|
success, path exists, file is not a link |
The size in bytes of a file or folder
Sample:
1024
|
|
| isdir
boolean
|
success, path exists |
If the path is a directory or not
Sample:
True
|
|
| extension
string
|
success, path exists, path is a file |
The extension of the file at path
Sample:
.ps1
|
|
| isreadonly
boolean
|
success, path exists |
If the path is read only or not
Sample:
True
|
|
| sharename
string
|
success, path exists, file is a directory and isshared == True |
The name of share if folder is shared
Sample:
file-share
|
|
| isjunction
boolean
|
success, path exists |
If the path is a junction point or not
Sample:
True
|
|
| filename
string
|
success, path exists, path is a file |
The name of the file (without path)
|
|
| isreg
boolean
|
success, path exists |
If the path is a regular file
Sample:
True
|
|
| 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']
|
|
| 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
|
|
| islnk
boolean
|
success, path exists |
If the path is a symbolic link or not
Sample:
True
|
|
| attributes
string
|
success, path exists |
Attributes of the file at path in raw form
Sample:
Archive, Hidden
|
|
| isshared
boolean
|
success, path exists |
If the path is shared or not
Sample:
True
|
|
| md5
string
|
success, path exist, path is a file, get_md5 == True |
The MD5 checksum of a file (Between Ansible 1.9 and 2.2 this was returned as a SHA1 hash), will be removed in 2.9
Sample:
09cb79e8fc7453c84a07f644e441fd81623b7f98
|
|
Status
This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.
Support
For more information about Red Hat’s support of this module, please refer to this Knowledge Base article
Author
- 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.5/modules/win_stat_module.html