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
    Choices:
  • md5
  • sha1 ←
  • sha256
  • sha384
  • sha512
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
    Choices:
  • no ←
  • yes
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
    Choices:
  • no
  • yes ←
Whether to return a checksum of the file (default sha1)
get_md5
boolean
    Choices:
  • no ←
  • yes
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

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.