SALT.MODULES.REG
MANAGE THE WINDOWS REGISTRY
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: |
|
---|
-
class
-
Delay usage until this module is used
salt.modules.reg.
Registry
-
Refresh the windows environment.
Returns (bool): True if successful, otherwise False
CLI Example:
salt.modules.reg.
broadcast_change
(
)
-
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: The following example will remove
salt
and all its subkeys from theSOFTWARE
key inHKEY_LOCAL_MACHINE
:CLI Example:
- hive --
salt.modules.reg.
delete_key_recursive
(
hive,
key,
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: CLI Example:
- hive (str) --
salt.modules.reg.
delete_value
(
hive,
key,
vname=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: CLI Example:
- hive (str) --
salt.modules.reg.
list_keys
(
hive,
key=None,
use_32bit_registry=False
)
-
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: CLI Example:
- hive (str) --
salt.modules.reg.
list_values
(
hive,
key=None,
use_32bit_registry=False,
include_default=True
)
-
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: 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:
- hive (str) --
salt.modules.reg.
read_value
(
hive,
key,
vname=None,
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 (object) --
The value data to be set. What the type of 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: Returns True if successful, False if not
Return type: CLI Example:
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:
However, this next example where vdata is properly quoted should succeed.
CLI Example:
An example of using vtype REG_BINARY is as follows:
CLI Example:
An example of using vtype REG_LIST is as follows:
CLI Example:
- hive (str) --
salt.modules.reg.
set_value
(
hive,
key,
vname=None,
vdata=None,
vtype=u'REG_SZ',
use_32bit_registry=False,
volatile=False
)