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.