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:
  • winreg Python module
class salt.modules.reg.Registry

Delay '_winreg' usage until this module is used

salt.modules.reg.broadcast_change()

Refresh the windows environment.

Returns (bool): True if successful, otherwise False

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.

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_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 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:

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]'