salt.modules.reg

Manage the Windows registry

The read_key and set_key functions will be updated in Boron 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.create_key(hkey, path, key=None, value=None, reflection=True)

* Incorrect Usage * The name of this function is misleading and will be changed to reflect proper usage in the Boron 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 Boron 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)

* Incorrect Usage * The name of this function is misleading and will be changed to reflect proper usage in the Boron 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 Boron 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 Boron
  • 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 Boron.

  • 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)

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)

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.
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.read_key(hkey, path, key=None)

* Incorrect Usage * The name of this function is misleading and will be changed to reflect proper usage in the Boron 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 Boron 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)

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
Returns:

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

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.
Return type:

dict

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)

* Incorrect Usage * The name of this function is misleading and will be changed to reflect proper usage in the Boron 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 Boron 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)

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.
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'

You are viewing docs for the previous stable release, 2015.5.11. Switch to docs for the latest stable release, 2016.3.2, or to a recent doc build from the develop branch.


saltstack.com