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)

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 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 or Entries are the name/data pairs beneath the keys and subkeys. All keys have a default name/data pair. The name is (Default) with a displayed value of (value not set). The actual value is Null.

Example

The following example is an export from the Windows startup portion of the registry:

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run]
"RTHDVCPL"="\"C:\\Program Files\\Realtek\\Audio\\HDA\\RtkNGUI64.exe\" -s"
"NvBackend"="\"C:\\Program Files (x86)\\NVIDIA Corporation\\Update Core\\NvBackend.exe\""
"BTMTrayAgent"="rundll32.exe \"C:\\Program Files (x86)\\Intel\\Bluetooth\\btmshellex.dll\",TrayApp"

In this example these are the values for each:

Hive:

HKEY_LOCAL_MACHINE

Key and subkeys:

SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Run

Value:

There are 3 value names:
- RTHDVCPL
- NvBackend
- BTMTrayAgent
Each value name has a corresponding value

depends:

salt.utils.win_reg

salt.modules.reg.broadcast_change()¶

Refresh the windows environment.

Note

This will only effect new processes and windows. Services will not see the change until the system restarts.

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 and value/data pairs.

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

CLI Example:

The following example will remove delete_me and all its subkeys from the SOFTWARE key in HKEY_LOCAL_MACHINE:
salt '*' reg.delete_key_recursive HKLM SOFTWARE\\delete_me

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.import_file(source, use_32bit_registry=False)¶

Import registry settings from a Windows REG file by invoking REG.EXE.

New in version 2018.3.0.

Parameters:

source (str) -- The full path of the REG file. This can be either a local file path or a URL type supported by salt (e.g. salt://salt_master_path)
use_32bit_registry (bool) -- If the value of this parameter is True then the REG file will be imported into the Windows 32 bit registry. Otherwise the Windows 64 bit registry will be used.

Returns:

True if successful, otherwise an error is raised

Return type:

bool

Raises:

ValueError -- If the value of source is an invalid path or otherwise causes cp.cache_file to return False
CommandExecutionError -- If reg.exe exits with a non-0 exit code

CLI Example:

salt machine1 reg.import_file salt://win/printer_config/110_Canon/postinstall_config.reg

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 exists, otherwise False

Return type:

bool

CLI Example:

salt '*' reg.key_exists HKLM SOFTWARE\Microsoft

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'

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

Enumerates the values in a registry key or hive.

Note

The (Default) value will only be returned if it is set, otherwise it will not be returned in the list of values.

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

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. To read the default value, don't pass vname

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.

bool: Returns False if the key is not found

If vname is not passed:

Returns the first unnamed value (Default) as a string.

Returns none if first unnamed value is empty.

Return type:

dict

CLI Example:

The following will get the value of the version value name in the HKEY_LOCAL_MACHINE\\SOFTWARE\\Salt key
salt '*' reg.read_value HKEY_LOCAL_MACHINE 'SOFTWARE\Salt' 'version'

CLI Example:

The following will get the default value of the HKEY_LOCAL_MACHINE\\SOFTWARE\\Salt key
salt '*' reg.read_value HKEY_LOCAL_MACHINE 'SOFTWARE\Salt'

salt.modules.reg.set_value(hive, key, vname=None, vdata=None, vtype='REG_SZ', use_32bit_registry=False, volatile=False)¶

Sets a value in the registry. If vname is passed, it will be the value for that value name, otherwise it will be the default value for the specified 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 (str, int, list, bytes) --
The value you'd like to set. If a value name (vname) is passed, this will be the data for that value name. If not, this will be the (Default) value for the key.

The type of data this parameter expects is determined by the value type specified in vtype. The correspondence is as follows:
- REG_BINARY: Binary data (str in Py2, bytes in Py3)
- REG_DWORD: int
- REG_EXPAND_SZ: str
- REG_MULTI_SZ: list of str
- REG_QWORD: int
- REG_SZ: str
Note

When setting REG_BINARY, string data will be converted to binary.
Note

The type for the (Default) value is always REG_SZ and cannot be changed.

Note

This parameter is optional. If vdata is not passed, the Key will be created with no associated item/value pairs.
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:

This will set the version value to 2015.5.2 in the SOFTWARESalt key in the HKEY_LOCAL_MACHINE hive
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\Salt' 'version' '2015.5.2'

CLI Example:

This function is strict about the type of vdata. For instance this example will fail because vtype has a value of REG_SZ and vdata has a type of int (as opposed to str as expected).
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\Salt' 'str_data' 1.2

CLI Example:

In this next example vdata is properly quoted and should succeed.
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\Salt' 'str_data' vtype=REG_SZ vdata="'1.2'"

CLI Example:

This is an example of using vtype REG_BINARY.

salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\Salt' 'bin_data' vtype=REG_BINARY vdata='Salty Data'

CLI Example:

An example of using vtype REG_MULTI_SZ is as follows:

salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\Salt' 'list_data' vtype=REG_MULTI_SZ vdata='["Salt", "is", "great"]'

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

Check that the value/data pair is found in the registry.

New in version 3000.

Parameters:

hive (str) -- The hive to connect to
key (str) -- The key to check in
vname (str) -- The name of the value/data pair you're checking
use_32bit_registry (bool) -- Look in the 32bit portion of the registry

Returns:

True if exists, otherwise False

Return type:

bool

CLI Example:

salt '*' reg.value_exists HKLM SOFTWARE\Microsoft\Windows\CurrentVersion CommonFilesDir