salt.states.reg
Manage the Windows registry
Many python developers think of registry keys as if they were python keys in a dictionary which is not the case. The windows registry is broken down into the following components:
Hives
This is the top level of the registry. They all begin with HKEY.
HKEY_CLASSES_ROOT (HKCR)
HKEY_CURRENT_USER(HKCU)
HKEY_LOCAL MACHINE (HKLM)
HKEY_USER (HKU)
HKEY_CURRENT_CONFIG
Keys
Hives contain keys. These are basically the folders beneath the hives. They can contain any number of subkeys.
When passing the hivekey values they must be quoted correctly depending on the backslashes being used (\
vs \\
). The way backslashes are handled in the state file is different from the way they are handled when working on the CLI. The following are valid methods of passing the hivekey:
- Using single backslashes:
-
HKLMSOFTWAREPython 'HKLMSOFTWAREPython'
- Using double backslashes:
-
"HKLM\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 taken 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
, andBTMTrayAgent
Each value name has a corresponding value
-
Ensure a registry value is removed. To remove a key use key_absent.
- Parameters
-
-
name (str) --
A string value representing the full path of the key to include the HIVE, Key, and all Subkeys. For example:
HKEY_LOCAL_MACHINE\\SOFTWARE\\Salt
Valid hive values include:
HKEY_CURRENT_USER or HKCU
HKEY_LOCAL_MACHINE or HKLM
HKEY_USERS or HKU
vname (str) -- The name of the value you'd like to create beneath the Key. If this parameter is not passed it will assume you want to set the
(Default)
valueuse_32bit_registry (bool) -- Use the 32bit portion of the registry. Applies only to 64bit windows. 32bit Windows will ignore this parameter. Default is False.
-
- Returns
-
A dictionary showing the results of the registry operation.
- Return type
CLI Example:
'HKEY_CURRENT_USER\\SOFTWARE\\Salt': reg.absent - vname: version
In the above example the value named
version
will be removed from the SOFTWARE\Salt key in the HKEY_CURRENT_USER hive. Ifvname
was not passed, the(Default)
value would be deleted.
salt.states.reg.absent(name, vname=None, use_32bit_registry=False)
-
New in version 2015.5.4.
Ensure a registry key is removed. This will remove the key, subkeys, and all value entries.
- Parameters
-
-
name (str) --
A string representing the full path to the key to be removed to include the hive and the keypath. The hive can be any of the following:
HKEY_LOCAL_MACHINE or HKLM
HKEY_CURRENT_USER or HKCU
HKEY_USER or HKU
use_32bit_registry (bool) -- Use the 32bit portion of the registry. Applies only to 64bit windows. 32bit Windows will ignore this parameter. Default is False.
-
- Returns
-
A dictionary showing the results of the registry operation.
- Return type
CLI Example:
The following example will delete the
SOFTWARE\DeleteMe
key in theHKEY_LOCAL_MACHINE
hive including all its subkeys and value pairs.remove_key_demo: reg.key_absent: - name: HKEY_CURRENT_USER\SOFTWARE\DeleteMe
In the above example the path is interpreted as follows:
HKEY_CURRENT_USER
is the hiveSOFTWARE\DeleteMe
is the key
salt.states.reg.key_absent(name, use_32bit_registry=False)
-
Ensure a registry key or value is present.
- Parameters
-
-
name (str) --
A string value representing the full path of the key to include the HIVE, Key, and all Subkeys. For example:
HKEY_LOCAL_MACHINE\\SOFTWARE\\Salt
Valid hive values include:
HKEY_CURRENT_USER or HKCU
HKEY_LOCAL_MACHINE or HKLM
HKEY_USERS or HKU
vname (str) -- The name of the value you'd like to create beneath the Key. If this parameter is not passed it will assume you want to set the
(Default)
value-
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 automatically. To pass binary data, use the built-in yaml tag
!!binary
to denote the actual binary characters. For example, the following lines will both set the same data in the registry:vdata: Salty Test
vdata: !!binary U2FsdHkgVGVzdA==\n
For more information about the
!!binary
tag see hereNote
The type for the
(Default)
value is always REG_SZ and cannot be changed. This parameter is optional. If not passed, the Key will be created with no associated item/value pairs. -
vtype (str) --
The value type for the data you wish to store in the registry. Valid values are:
REG_BINARY
REG_DWORD
REG_EXPAND_SZ
REG_MULTI_SZ
REG_QWORD
REG_SZ (Default)
use_32bit_registry (bool) -- Use the 32bit portion of the registry. Applies only to 64bit windows. 32bit Windows will ignore this parameter. Default is False.
-
win_owner (str) --
The owner of the registry key. If this is not passed, the account under which Salt is running will be used.
Note
Owner is set for the key that contains the value/data pair. You cannot set ownership on value/data pairs themselves.
New in version 2019.2.0.
-
win_perms (dict) --
A dictionary containing permissions to grant and their propagation. If not passed the 'Grant` permissions will not be modified.
Note
Permissions are set for the key that contains the value/data pair. You cannot set permissions on value/data pairs themselves.
For each user specify the account name, with a sub dict for the permissions to grant and the 'Applies to' setting. For example:
{'Administrators': {'perms': 'full_control', 'applies_to': 'this_key_subkeys'}}
.perms
must be specified.Registry permissions are specified using the
perms
key. You can specify a single basic permission or a list of advanced perms. The following are valid perms:- Basic (passed as a string):
-
full_control
read
write
- Advanced (passed as a list):
-
delete
query_value
set_value
create_subkey
enum_subkeys
notify
create_link
read_control
write_dac
write_owner
The 'Applies to' setting is optional. It is specified using the
applies_to
key. If not specifiedthis_key_subkeys
is used. Valid options are:- Applies to settings:
-
this_key_only
this_key_subkeys
subkeys_only
New in version 2019.2.0.
-
win_deny_perms (dict) --
A dictionary containing permissions to deny and their propagation. If not passed the Deny permissions will not be modified.
Note
Permissions are set for the key that contains the value/data pair. You cannot set permissions on value/data pairs themselves.
Valid options are the same as those specified in
win_perms
Note
- 'Deny' permissions always take precedence over 'grant'
-
permissions.
New in version 2019.2.0.
-
win_inheritance (bool) --
True
to inherit permissions from the parent key.False
to disable inheritance. Default isTrue
.Note
Inheritance is set for the key that contains the value/data pair. You cannot set inheritance on value/data pairs themselves.
New in version 2019.2.0.
-
win_perms_reset (bool) --
If
True
the existing DACL will be cleared and replaced with the settings defined in this function. IfFalse
, new entries will be appended to the existing DACL. Default isFalse
Note
Perms are reset for the key that contains the value/data pair. You cannot set permissions on value/data pairs themselves.
New in version 2019.2.0.
-
- Returns
-
A dictionary showing the results of the registry operation.
- Return type
Example:
The following example will set the
(Default)
value for theSOFTWARE\\Salt
key in theHKEY_CURRENT_USER
hive to2016.3.1
:HKEY_CURRENT_USER\\SOFTWARE\\Salt: reg.present: - vdata: 2016.3.1
Example:
The following example will set the value for the
version
entry under theSOFTWARE\\Salt
key in theHKEY_CURRENT_USER
hive to2016.3.1
. The value will be reflected inWow6432Node
:HKEY_CURRENT_USER\\SOFTWARE\\Salt: reg.present: - vname: version - vdata: 2016.3.1
In the above example the path is interpreted as follows:
HKEY_CURRENT_USER
is the hiveSOFTWARE\\Salt
is the keyvname
is the value name ('version') that will be created under the keyvdata
is the data that will be assigned to 'version'
Example:
Binary data can be set in two ways. The following two examples will set a binary value of
Salty Test
no_conversion: reg.present: - name: HKLM\SOFTWARE\SaltTesting - vname: test_reg_binary_state - vdata: Salty Test - vtype: REG_BINARY conversion: reg.present: - name: HKLM\SOFTWARE\SaltTesting - vname: test_reg_binary_state_with_tag - vdata: !!binary U2FsdHkgVGVzdA==\n - vtype: REG_BINARY
Example:
To set a
REG_MULTI_SZ
value:reg_multi_sz: reg.present: - name: HKLM\SOFTWARE\Salt - vname: reg_multi_sz - vdata: - list item 1 - list item 2
Example:
To ensure a key is present and has permissions:
set_key_permissions: reg.present: - name: HKLM\SOFTWARE\Salt - vname: version - vdata: 2016.3.1 - win_owner: Administrators - win_perms: jsnuffy: perms: full_control sjones: perms: - read_control - enum_subkeys - query_value applies_to: - this_key_only - win_deny_perms: bsimpson: perms: full_control applies_to: this_key_subkeys - win_inheritance: True - win_perms_reset: True
salt.states.reg.present(name, vname=None, vdata=None, vtype='REG_SZ', use_32bit_registry=False, win_owner=None, win_perms=None, win_deny_perms=None, win_inheritance=True, win_perms_reset=False)
© 2021 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltproject.io/en/latest/ref/states/all/salt.states.reg.html