win_stat - Get information about Windows files

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)	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.
get_checksum bool (added in 2.1)	Choices: no yes ←	Whether to return a checksum of the file (default sha1)
get_md5 bool	Choices: no ← yes	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 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.

Maintenance

This module is flagged as core which means that it is maintained by the Ansible Core Team. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Core Team, see here.

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.