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)

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 '_winreg' usage until this module is used

salt.modules.reg.broadcast_change()¶

Refresh the windows environment.

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) 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 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:	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.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 key (str) -- 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_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 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.
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_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 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 (object) -- The value data to be set. What the type of this paramater should be is determined by the value of the vtype paramater. 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 paramater are indicated above in the description of the vdata paramater. use_32bit_registry (bool) -- Sets the 32bit portion of the registry on 64bit installations. On 32bit machines this is ignored. volatile (bool) -- When this paramater 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 paramater only has an effect when a key is being created and at no other time.
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'

This function is strict about the type of vdata. For instance the 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' '2015.5.2' \
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' '2015.5.2' \
vtype=REG_SZ vdata="'0'"

An example of using vtype REG_BINARY is as follows:

CLI Example:

salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\Salt' 'version' '2015.5.2' \
vtype=REG_BINARY vdata='!!binary d2hhdCdzIHRoZSBwb2ludA=='

An example of using vtype REG_LIST is as follows:

CLI Example:

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