salt.modules.reg

Manage the Windows registry

The read_key and set_key functions will be updated in Carbon to reflect proper registry usage. The registry has three main components. Hives, Keys, and Values.

Hives

Hives are the main sections of the registry and all begin with the word HKEY. - HKEY_LOCAL_MACHINE - HKEY_CURRENT_USER - HKEY_USER

Keys

Keys are the folders in the registry. Keys can have many nested subkeys. Keys can have a value assigned to them under the (Default)

Values or Entries

Values/Entries are name/data pairs. There can be many values in a key. The (Default) value corresponds to the Key, the rest are their own value pairs.

depends:
  • winreg Python module
class salt.modules.reg.Registry

Delay '_winreg' usage until this module is used

salt.modules.reg.broadcast_change()

Refresh the windows environment. :return:

salt.modules.reg.create_key(hkey, path, key=None, value=None, reflection=True, use_32bit_registry=False)

Important

The name of this function is misleading and will be changed to reflect proper usage in the Carbon release of Salt. The path option will be removed and the key will be the actual key. See the following issue:

https://github.com/saltstack/salt/issues/25618

In order to not break existing state files this function will call the set_value function if key is passed. Key will be passed as the value name. If key is not passed, this function will return the default value for the key.

In the Carbon release path will be removed and key will be the path. You will not pass value.

Create a registry key

CLI Example:

salt '*' reg.create_key HKEY_CURRENT_USER 'SOFTWARE\Salt' 'version' '0.97'
salt.modules.reg.delete_key(hkey, path, key=None, reflection=True, force=False, use_32bit_registry=False)

Important

The name of this function is misleading and will be changed to reflect proper usage in the Carbon release of Salt. The path option will be removed and the key will be the actual key. See the following issue:

https://github.com/saltstack/salt/issues/25618

In order to not break existing state files this function will call the delete_value function if a key is passed. Key will be passed as the value name. If key is not passed, this function will return the default value for the key.

In the Carbon release path will be removed and key will be the path. reflection will also be removed.

Delete a registry key

CLI Example:

salt '*' reg.delete_key HKEY_CURRENT_USER 'SOFTWARE\Salt'
Parameters:
  • hkey (str) --

    (will be changed to hive) The name of the hive. Can be one of the following

    • HKEY_LOCAL_MACHINE or HKLM
    • HKEY_CURRENT_USER or HKCU
    • HKEY_USER or HKU
  • path (str) -- (will be changed to key) The key (looks like a path) to remove.
  • key (str) -- (used incorrectly) Will be removed in Carbon
  • reflection (bool) --

    A boolean value indicating that the value should also be removed from the Wow6432Node portion of the registry. Only applies to 64 bit Windows. This setting is ignored for 32 bit Windows.

    Only applies to delete value. If the key parameter is passed, this function calls delete_value instead. Will be changed in Carbon.

  • force (bool) -- A boolean value indicating that all subkeys should be removed as well. If this is set to False (default) and there are subkeys, the delete_key function will fail.
Returns:

Returns True if successful, False if not. If force=True, the results of delete_key_recursive are returned.

Return type:

bool

salt.modules.reg.delete_key_recursive(hive, key, use_32bit_registry=False)

New in version 2015.5.4.

Delete a registry key to include all subkeys.

Parameters:
  • hive --

    The name of the hive. Can be one of the following

    • HKEY_LOCAL_MACHINE or HKLM
    • HKEY_CURRENT_USER or HKCU
    • HKEY_USER or HKU
  • key -- The key to remove (looks like a path)
Returns:

A dictionary listing the keys that deleted successfully as well as

those that failed to delete.

Return type:dict

The following example will remove salt and all its subkeys from the SOFTWARE key in HKEY_LOCAL_MACHINE:

CLI Example:

salt '*' reg.delete_key_recursive HKLM SOFTWARE\salt
salt.modules.reg.delete_value(hive, key, vname=None, reflection=True, use_32bit_registry=False)

Delete a registry value entry or the default value for a key.

Parameters:
  • hive (str) --

    The name of the hive. Can be one of the following

    • HKEY_LOCAL_MACHINE or HKLM
    • HKEY_CURRENT_USER or HKCU
    • HKEY_USER or HKU
  • key (str) -- The key (looks like a path) to the value name.
  • vname (str) -- The value name. These are the individual name/data pairs under the key. If not passed, the key (Default) value will be deleted.
  • reflection (bool) -- A boolean value indicating that the value should also be set in the Wow6432Node portion of the registry. Only applies to 64 bit Windows. This setting is ignored for 32 bit Windows.

Deprecated since version 2015.8.2: Use use_32bit_registry instead. The parameter seems to have no effect since Windows 7 / Windows 2008R2 removed support for reflection. This parameter will be removed in Carbon.

Returns:Returns True if successful, False if not
Return type:bool

CLI Example:

salt '*' reg.delete_value HKEY_CURRENT_USER 'SOFTWARE\Salt' 'version'
salt.modules.reg.list_keys(hive, key=None, use_32bit_registry=False)

Enumerates the subkeys in a registry key or hive.

Parameters:
  • hive (str) --

    The name of the hive. Can be one of the following

    • HKEY_LOCAL_MACHINE or HKLM
    • HKEY_CURRENT_USER or HKCU
    • HKEY_USER or HKU
  • key (str) -- The key (looks like a path) to the value name. If a key is not passed, the keys under the hive will be returned.
  • use_32bit_registry (bool) -- Accesses the 32bit portion of the registry on 64 bit installations. On 32bit machines this is ignored.
Returns:

A list of keys/subkeys under the hive or key.

Return type:

list

CLI Example:

salt '*' reg.list_keys HKLM 'SOFTWARE'
salt.modules.reg.read_key(hkey, path, key=None, use_32bit_registry=False)

Important

The name of this function is misleading and will be changed to reflect proper usage in the Carbon release of Salt. The path option will be removed and the key will be the actual key. See the following issue:

https://github.com/saltstack/salt/issues/25618

In order to not break existing state files this function will call the read_value function if a key is passed. Key will be passed as the value name. If key is not passed, this function will return the default value for the key.

In the Carbon release this function will be removed in favor of read_value.

Read registry key value

Returns the first unnamed value (Default) as a string. Returns none if first unnamed value is empty. Returns False if key not found.

CLI Example:

salt '*' reg.read_key HKEY_LOCAL_MACHINE 'SOFTWARE\Salt' 'version'
salt.modules.reg.read_value(hive, key, vname=None, use_32bit_registry=False)

Reads a registry value entry or the default value for a key.

Parameters:
  • hive (str) --

    The name of the hive. Can be one of the following

    • HKEY_LOCAL_MACHINE or HKLM
    • HKEY_CURRENT_USER or HKCU
    • HKEY_USER or HKU
  • key (str) -- The key (looks like a path) to the value name.
  • vname (str) -- The value name. These are the individual name/data pairs under the key. If not passed, the key (Default) value will be returned
  • use_32bit_registry (bool) -- Accesses the 32bit portion of the registry on 64 bit installations. On 32bit machines this is ignored.
Returns:

A dictionary containing the passed settings as well as the value_data if successful. If unsuccessful, sets success to False

Return type:

dict

If vname is not passed:

  • Returns the first unnamed value (Default) as a string.
  • Returns none if first unnamed value is empty.
  • Returns False if key not found.

CLI Example:

salt '*' reg.read_value HKEY_LOCAL_MACHINE 'SOFTWARE\Salt' 'version'
salt.modules.reg.set_key(hkey, path, value, key=None, vtype='REG_DWORD', reflection=True, use_32bit_registry=False)

Important

The name of this function is misleading and will be changed to reflect proper usage in the Carbon release of Salt. The path option will be removed and the key will be the actual key. See the following issue:

https://github.com/saltstack/salt/issues/25618

In order to not break existing state files this function will call the set_value function if a key is passed. Key will be passed as the value name. If key is not passed, this function will return the default value for the key.

In the Carbon release this function will be removed in favor of set_value.

Set a registry key

vtype: http://docs.python.org/2/library/_winreg.html#value-types

CLI Example:

salt '*' reg.set_key HKEY_CURRENT_USER 'SOFTWARE\Salt' 'version' '0.97' REG_DWORD
salt.modules.reg.set_value(hive, key, vname=None, vdata=None, vtype='REG_SZ', reflection=True, use_32bit_registry=False)

Sets a registry value entry or the default value for a key.

Parameters:
  • hive (str) --

    The name of the hive. Can be one of the following

    • HKEY_LOCAL_MACHINE or HKLM
    • HKEY_CURRENT_USER or HKCU
    • HKEY_USER or HKU
  • key (str) -- The key (looks like a path) to the value name.
  • vname (str) -- The value name. These are the individual name/data pairs under the key. If not passed, the key (Default) value will be set.
  • vdata (str) -- The value data to be set.
  • vtype (str) --

    The value type. Can be one of the following:

    • REG_BINARY
    • REG_DWORD
    • REG_EXPAND_SZ
    • REG_MULTI_SZ
    • REG_SZ
  • reflection (bool) -- A boolean value indicating that the value should also be set in the Wow6432Node portion of the registry. Only applies to 64 bit Windows. This setting is ignored for 32 bit Windows.

Deprecated since version 2015.8.2: Use use_32bit_registry instead. The parameter seems to have no effect since Windows 7 / Windows 2008R2 removed support for reflection. The parameter will be removed in Carbon.

Returns:Returns True if successful, False if not
Return type:bool

CLI Example:

salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\Salt' 'version' '2015.5.2'