def delete_key(hkey, path, key=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
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
Note: This cannot delete a key with subkeys
CLI Example:
.. code-block:: bash
salt '*' reg.delete_key HKEY_CURRENT_USER 'SOFTWARE\\Salt'
'''
if key: # This if statement will be removed in Boron
salt.utils.warn_until(
'Boron', 'Use reg.set_value to set a registry '
'value. This functionality will be '
'removed in Salt Boron')
return delete_value(hive=hkey,
key=path,
vname=key,
reflection=reflection)
registry = Registry()
hive = registry.hkeys[hkey]
key = path
try:
_winreg.DeleteKey(hive, key)
return True
except WindowsError as exc: # pylint: disable=E0602
log.error(exc)
return False
def delete_key_recursive(hive, key, use_32bit_registry=False):
'''
.. versionadded:: 2015.5.4
Delete a registry key to include all subkeys.
:param 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
:param key: The key to remove (looks like a path)
:param bool use_32bit_registry: Deletes the 32bit portion of the registry on
64bit installations. On 32bit machines this is ignored.
:return: A dictionary listing the keys that deleted successfully as well as
those that failed to delete.
:rtype: dict
The following example will remove ``salt`` and all its subkeys from the
``SOFTWARE`` key in ``HKEY_LOCAL_MACHINE``:
CLI Example:
.. code-block:: bash
salt '*' reg.delete_key_recursive HKLM SOFTWARE\\salt
'''
if PY2:
local_hive = _mbcs_to_unicode(hive)
local_key = _unicode_to_mbcs(key)
else:
local_hive = hive
local_key = key
# Instantiate the registry object
registry = Registry()
hkey = registry.hkeys[local_hive]
key_path = local_key
access_mask = registry.registry_32[
use_32bit_registry] | _winreg.KEY_ALL_ACCESS
if not _key_exists(local_hive, local_key, use_32bit_registry):
return False
if (len(key) > 1) and (key.count('\\', 1) <
registry.subkey_slash_check[hkey]):
log.error(
'Hive:{0} Key:{1}; key is too close to root, not safe to remove'.
format(hive, key))
return False
# Functions for traversing the registry tree
def _subkeys(_key):
'''
Enumerate keys
'''
i = 0
while True:
try:
subkey = _winreg.EnumKey(_key, i)
yield subkey
i += 1
except WindowsError: # pylint: disable=E0602
break
def _traverse_registry_tree(_hkey, _keypath, _ret, _access_mask):
'''
Traverse the registry tree i.e. dive into the tree
'''
_key = _winreg.OpenKey(_hkey, _keypath, 0, _access_mask)
for subkeyname in _subkeys(_key):
subkeypath = r'{0}\{1}'.format(_keypath, subkeyname)
_ret = _traverse_registry_tree(_hkey, subkeypath, _ret,
access_mask)
_ret.append('{0}'.format(subkeypath))
return _ret
# Get a reverse list of registry keys to be deleted
key_list = []
key_list = _traverse_registry_tree(hkey, key_path, key_list, access_mask)
# Add the top level key last, all subkeys must be deleted first
key_list.append(r'{0}'.format(key_path))
ret = {'Deleted': [], 'Failed': []}
# Delete all sub_keys
for sub_key_path in key_list:
try:
key_handle = _winreg.OpenKey(hkey, sub_key_path, 0, access_mask)
_winreg.DeleteKey(key_handle, '')
ret['Deleted'].append(r'{0}\{1}'.format(hive, sub_key_path))
except WindowsError as exc: # pylint: disable=E0602
log.error(exc, exc_info=True)
ret['Failed'].append(r'{0}\{1} {2}'.format(hive, sub_key_path,
exc))
broadcast_change()
return ret
def delete_key_recursive(hive, key, use_32bit_registry=False):
'''
.. versionadded:: 2015.5.4
Delete a registry key to include all subkeys.
:param 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
:param key: The key to remove (looks like a path)
:return: A dictionary listing the keys that deleted successfully as well as
those that failed to delete.
:rtype: dict
The following example will remove ``salt`` and all its subkeys from the
``SOFTWARE`` key in ``HKEY_LOCAL_MACHINE``:
CLI Example:
.. code-block:: bash
salt '*' reg.delete_key_recursive HKLM SOFTWARE\\salt
'''
# Instantiate the registry object
registry = Registry()
hkey = registry.hkeys[hive]
key_path = key
access_mask = registry.registry_32[use_32bit_registry]
if not _key_exists(hive, key, use_32bit_registry):
return False
# Functions for traversing the registry tree
def subkeys(key):
i = 0
while True:
try:
subkey = _winreg.EnumKey(key, i)
yield subkey
i += 1
except WindowsError: # pylint: disable=E0602
break
def traverse_registry_tree(hkey, keypath, ret, access_mask):
key = _winreg.OpenKey(hkey, keypath, 0, access_mask)
for subkeyname in subkeys(key):
subkeypath = r'{0}\{1}'.format(keypath, subkeyname)
ret = traverse_registry_tree(hkey, subkeypath, ret, access_mask)
ret.append('{0}'.format(subkeypath))
return ret
# Get a reverse list of registry keys to be deleted
key_list = []
key_list = traverse_registry_tree(hkey, key_path, key_list, access_mask)
# Add the top level key last, all subkeys must be deleted first
key_list.append(r'{0}'.format(key_path))
ret = {'Deleted': [], 'Failed': []}
# Delete all sub_keys
for sub_key_path in key_list:
try:
key_handle = _winreg.OpenKey(hkey, sub_key_path, 0, access_mask)
_winreg.DeleteKey(key_handle, '')
ret['Deleted'].append(r'{0}\{1}'.format(hive, sub_key_path))
except WindowsError as exc: # pylint: disable=E0602
log.error(exc, exc_info=True)
ret['Failed'].append(r'{0}\{1} {2}'.format(hive, sub_key_path,
exc))
return ret
def 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 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:
.. code-block:: bash
salt '*' reg.delete_key HKEY_CURRENT_USER 'SOFTWARE\\Salt'
:param str hkey: (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
:param str path: (will be changed to key) The key (looks like a path) to
remove.
:param str key: (used incorrectly) Will be removed in Boron
:param bool reflection: 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.
:param bool force: 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.
:return: Returns True if successful, False if not. If force=True, the
results of delete_key_recursive are returned.
:rtype: bool
'''
if key: # This if statement will be removed in Boron
salt.utils.warn_until(
'Boron', 'Variable names will be changed to match Windows '
'Registry terminology. These changes will be '
'made in Boron')
return delete_value(hive=hkey,
key=path,
vname=key,
reflection=reflection,
use_32bit_registry=use_32bit_registry)
if force:
return delete_key_recursive(hkey,
path,
use_32bit_registry=use_32bit_registry)
registry = Registry()
hive = registry.hkeys[hkey]
key = path
access_mask = registry.registry_32[use_32bit_registry]
try:
# Can't use delete_value to delete a key
key_handle = _winreg.OpenKey(hive, key, 0, access_mask)
_winreg.DeleteKey(key_handle, '')
_winreg.CloseKey(key_handle)
return True
except WindowsError as exc: # pylint: disable=E0602
log.error(exc, exc_info=True)
return False
def delete_key_recursive(hive, key):
'''
.. versionadded:: 2015.5.4
Delete a registry key to include all subkeys.
:param 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
:param key:
The key to remove (looks like a path)
:return:
A dictionary listing the keys that deleted successfully as well as those
that failed to delete.
:rtype: dict
'''
# Functions for traversing the registry tree
def subkeys(key):
i = 0
while True:
try:
subkey = _winreg.EnumKey(key, i)
yield subkey
i += 1
except WindowsError: # pylint: disable=E0602
break
def traverse_registry_tree(hkey, keypath, ret):
key = _winreg.OpenKey(hkey, keypath, 0, _winreg.KEY_READ)
for subkeyname in subkeys(key):
subkeypath = r'{0}\{1}'.format(keypath, subkeyname)
ret = traverse_registry_tree(hkey, subkeypath, ret)
ret.append('{0}'.format(subkeypath))
return ret
# Instantiate the registry object
registry = Registry()
hkey = registry.hkeys[hive]
keypath = key
# Get a reverse list of registry keys to be deleted
key_list = []
key_list = traverse_registry_tree(hkey, keypath, key_list)
ret = {'Deleted': [], 'Failed': []}
# Delete all subkeys
for keypath in key_list:
try:
_winreg.DeleteKey(hkey, keypath)
ret['Deleted'].append(r'{0}\{1}'.format(hive, keypath))
except WindowsError as exc: # pylint: disable=E0602
log.error(exc)
ret['Failed'].append(r'{0}\{1} {2}'.format(hive, key, exc))
# Delete the key now that all the subkeys are deleted
try:
_winreg.DeleteKey(hkey, key)
ret['Deleted'].append(r'{0}\{1}'.format(hive, key))
except WindowsError as exc: # pylint: disable=E0602
log.error(exc)
ret['Failed'].append(r'{0}\{1} {2}'.format(hive, key, exc))
return ret
