win_reg_stat – Get information about Windows registry keys

Synopsis

  • Like win_file, win_reg_stat will return whether the key/property exists.

  • It also returns the sub keys and properties of the key specified.

  • If specifying a property name through property, it will return the information specific for that property.

Parameters

Parameter Choices/Defaults Comments
name
string
The registry property name to get information for, the return json will not include the sub_keys and properties entries for the key specified.
Set to an empty string to target the registry key's (Default) property value.

aliases: entry, value, property
path
string / required
The full registry key path including the hive to search for.

aliases: key

Notes

Note

  • The properties return value will contain an empty string key "" that refers to the key’s Default value. If the value has not been set then this key is not returned.

See Also

See also

win_regedit – Add, change, or remove registry keys and values

The official documentation on the win_regedit module.

win_regmerge – Merges the contents of a registry file into the Windows registry

The official documentation on the win_regmerge module.

Examples

- name: Obtain information about a registry key using short form
  win_reg_stat:
    path: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
  register: current_version

- name: Obtain information about a registry key property
  win_reg_stat:
    path: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
    name: CommonFilesDir
  register: common_files_dir

- name: Obtain the registry key's (Default) property
  win_reg_stat:
    path: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
    name: ''
  register: current_version_default

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
exists
boolean
success and path/property exists
States whether the registry key/property exists.

Sample:
True
properties
dictionary
success, path exists and property not specified
A dictionary containing all the properties and their values in the registry key.

Sample:
{'': {'raw_value': '', 'type': 'REG_SZ', 'value': ''}, 'binary_property': {'raw_value': ['0x01', '0x16'], 'type': 'REG_BINARY', 'value': [1, 22]}, 'multi_string_property': {'raw_value': ['a', 'b'], 'type': 'REG_MULTI_SZ', 'value': ['a', 'b']}}
raw_value
string
success, path/property exists and property specified
Returns the raw value of the registry property, REG_EXPAND_SZ has no string expansion, REG_BINARY or REG_NONE is in hex 0x format. REG_NONE, this value is a hex string in the 0x format.

Sample:
%ProgramDir%\\Common Files
sub_keys
list
success, path exists and property not specified
A list of all the sub keys of the key specified.

Sample:
['AppHost', 'Casting', 'DateTime']
type
string
success, path/property exists and property specified
The property type.

Sample:
REG_EXPAND_SZ
value
string
success, path/property exists and property specified
The value of the property.

Sample:
C:\\Program Files\\Common Files


Status

Authors

  • Jordan Borean (@jborean93)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.