salt.modules.reg¶

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)

When passing a key on the CLI it must be quoted correctly depending on the backslashes being used (\ vs \\). The following are valid methods of passing the the key on the CLI:

Using single backslashes:

"SOFTWARE\Python" 'SOFTWARE\Python' (will not work on a Windows Master)

Using double backslashes:

SOFTWARE\\Python

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.

class salt.modules.reg.Registry¶

Delay usage until this module is used

salt.modules.reg.broadcast_change()¶

Refresh the windows environment.

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

CLI Example:

salt '*' reg.broadcast_change

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 (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 HKEY_CLASSES_ROOT or HKCR HKEY_CURRENT_CONFIG or HKCC key (str) -- The key to remove (looks like a path) use_32bit_registry (bool) -- Deletes the 32bit portion of the registry on 64bit installations. On 32bit machines this is ignored.
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, 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 HKEY_CLASSES_ROOT or HKCR HKEY_CURRENT_CONFIG or HKCC 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. use_32bit_registry (bool) -- Deletes the 32bit portion of the registry on 64bit installations. On 32bit machines this is ignored.
Returns:	True if successful, otherwise False
Return type:	bool

CLI Example:

salt '*' reg.delete_value HKEY_CURRENT_USER "SOFTWARE\Salt" version

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

Check that the key is found in the registry. This refers to keys and not value/data pairs.

Parameters:	hive (str) -- The hive to connect to key (str) -- The key to check use_32bit_registry (bool) -- Look in the 32bit portion of the registry
Returns:	True if found, otherwise False
Return type:	bool

CLI Example

salt '*' reg.key_exists HKLM "SYSTEM\CurrentControlSet\Services\Tcpip"

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 HKEY_CLASSES_ROOT or HKCR HKEY_CURRENT_CONFIG or HKCC 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\Python

salt.modules.reg.list_values(hive, key=None, use_32bit_registry=False, include_default=True)¶

Enumerates the values 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 HKEY_CLASSES_ROOT or HKCR HKEY_CURRENT_CONFIG or HKCC key -- The key (looks like a path) to the value name. If a key is not passed, the values 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. include_default (bool) -- Toggle whether to include the '(Default)' value.
Returns:	A list of values under the hive or key.
Return type:	list

CLI Example:

salt '*' reg.list_values HKLM "SYSTEM\CurrentControlSet\Services\Tcpip"

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 HKEY_CLASSES_ROOT or HKCR HKEY_CURRENT_CONFIG or HKCC 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 64bit 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. 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_value(hive, key, vname=None, vdata=None, vtype=u'REG_SZ', use_32bit_registry=False, volatile=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 HKEY_CLASSES_ROOT or HKCR HKEY_CURRENT_CONFIG or HKCC 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 (bin, int, str, list) -- The value data to be set. Which type this parameter should be is determined by the value of the vtype parameter. The correspondence is as follows: REG_BINARY binary data (i.e. str in python version < 3 and bytes in version >=3) REG_DWORD int REG_EXPAND_SZ str REG_MULTI_SZ list of objects of type str REG_SZ str vtype (str) -- The value type. The possible values of the vtype parameter are indicated above in the description of the vdata parameter. use_32bit_registry (bool) -- Sets the 32bit portion of the registry on 64bit installations. On 32bit machines this is ignored. volatile (bool) -- When this parameter has a value of True, the registry key will be made volatile (i.e. it will not persist beyond a system reset or shutdown). This parameter only has an effect when a key is being created and at no other time.
Returns:	True if successful, otherwise False
Return type:	bool

CLI Example:

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

This function is strict about the type of vdata. For instance the next example will fail because vtype has a value of REG_SZ and vdata has a type of int (as opposed to str as expected).

CLI Example:

salt '*' reg.set_value HKEY_LOCAL_MACHINE "SOFTWARE\Salt" version \\
    vtype=REG_SZ vdata=0

However, this next example where vdata is properly quoted should succeed.

CLI Example:

salt '*' reg.set_value HKEY_LOCAL_MACHINE "SOFTWARE\Salt" version \\
    vtype=REG_SZ vdata="'0'"

An example of using vtype REG_BINARY is as follows:

CLI Example:

On a Linux master, the `!!binary` needs to be single quoted
On a Windows master, the `!!binary` to be double quoted
salt '*' reg.set_value HKEY_LOCAL_MACHINE "SOFTWARE\Salt" version vtype=REG_BINARY vdata='!!binary d2hhdCdzIHRoZSBwb2ludA=='

An example of using vtype REG_MULTI_SZ is as follows:

CLI Example:

salt '*' reg.set_value HKEY_LOCAL_MACHINE "SOFTWARE\Salt" version vtype=REG_MULTI_SZ vdata="[a,b,c]"