saltstack/salt
1
0
Fork 0
mirror of https://github.com/saltstack/salt.git synced 2025-04-17 10:10:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Update reg docs, fix formatting issues

Browse source
This commit is contained in:
twangboy 2018-04-20 14:27:57 -06:00
parent c160fe36ce
commit ff46b27a60
No known key found for this signature in database
GPG key ID: 93FF3BDEB278C9EB
3 changed files with 584 additions and 425 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

384
salt/modules/reg.py
View file

@ -6,9 +6,10 @@ 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
- HKEY_LOCAL_MACHINE
- HKEY_CURRENT_USER
- HKEY_USER
----
Keys
@ -60,12 +61,22 @@ def 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.
:param str hive: The hive to connect to.
:param str key: The key to check
:param bool use_32bit_registry: Look in the 32bit portion of the registry
Args:
:return: Returns True if found, False if not found
:rtype: bool
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:
bool: True if exists, otherwise False
CLI Example:
.. code-block::
salt '*' reg.key_exists HKLM SOFTWARE\Microsoft
'''
return __utils__['reg.key_exists'](hive=hive,
key=key,
@ -76,13 +87,14 @@ def broadcast_change():
'''
Refresh the windows environment.
Returns (bool): True if successful, otherwise False
Returns:
bool: True if successful, otherwise False
CLI Example:
.. code-block:: bash
.. code-block:: bash
salt '*' reg.broadcast_change
salt '*' reg.broadcast_change
'''
return salt.utils.win_functions.broadcast_setting_change('Environment')
@ -91,28 +103,33 @@ def list_keys(hive, key=None, use_32bit_registry=False):
'''
Enumerates the subkeys in a registry key or hive.
:param str hive: The name of the hive. Can be one of the following
Args:
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
hive (str):
The name of the hive. Can be one of the following:
:param str key: The key (looks like a path) to the value name. If a key is
not passed, the keys under the hive will be returned.
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
:param bool use_32bit_registry: Accesses the 32bit portion of the registry
on 64 bit installations. On 32bit machines this is ignored.
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.
:return: A list of keys/subkeys under the hive or key.
:rtype: list
use_32bit_registry (bool):
Accesses the 32bit portion of the registry on 64 bit installations.
On 32bit machines this is ignored.
Returns:
list: A list of keys/subkeys under the hive or key.
CLI Example:
.. code-block:: bash
.. code-block:: bash
salt '*' reg.list_keys HKLM 'SOFTWARE'
salt '*' reg.list_keys HKLM 'SOFTWARE'
'''
return __utils__['reg.list_keys'](hive=hive,
key=key,
@ -123,30 +140,36 @@ def list_values(hive, key=None, use_32bit_registry=False, include_default=True):
'''
Enumerates the values in a registry key or hive.
:param str hive: The name of the hive. Can be one of the following
Args:
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
hive (str):
The name of the hive. Can be one of the following:
:param str key: The key (looks like a path) to the value name. If a key is
not passed, the values under the hive will be returned.
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
:param bool use_32bit_registry: Accesses the 32bit portion of the registry
on 64 bit installations. On 32bit machines this is ignored.
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.
:param bool include_default: Toggle whether to include the '(Default)' value.
use_32bit_registry (bool):
Accesses the 32bit portion of the registry on 64 bit installations.
On 32bit machines this is ignored.
:return: A list of values under the hive or key.
:rtype: list
include_default (bool):
Toggle whether to include the '(Default)' value.
Returns:
list: A list of values under the hive or key.
CLI Example:
.. code-block:: bash
.. code-block:: bash
salt '*' reg.list_values HKLM 'SYSTEM\\CurrentControlSet\\Services\\Tcpip'
salt '*' reg.list_values HKLM 'SYSTEM\\CurrentControlSet\\Services\\Tcpip'
'''
return __utils__['reg.list_values'](hive=hive,
key=key,
@ -158,38 +181,42 @@ def read_value(hive, key, vname=None, use_32bit_registry=False):
r'''
Reads a registry value entry or the default value for a key.
:param str hive: The name of the hive. Can be one of the following
Args:
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
hive (str): The name of the hive. Can be one of the following:
:param str key: The key (looks like a path) to the value name.
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
:param str vname: The value name. These are the individual name/data pairs
under the key. If not passed, the key (Default) value will be returned
key (str):
The key (looks like a path) to the value name.
:param bool use_32bit_registry: Accesses the 32bit portion of the registry
on 64bit installations. On 32bit machines this is ignored.
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.
:return: A dictionary containing the passed settings as well as the
value_data if successful. If unsuccessful, sets success to False.
use_32bit_registry (bool):
Accesses the 32bit portion of the registry on 64bit installations.
On 32bit machines this is ignored.
:rtype: dict
Returns:
dict: A dictionary containing the passed settings as well as the
value_data if successful. If unsuccessful, sets success to False.
If vname is not passed:
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.
- 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:
.. code-block:: bash
.. code-block:: bash
salt '*' reg.read_value HKEY_LOCAL_MACHINE 'SOFTWARE\Salt' 'version'
salt '*' reg.read_value HKEY_LOCAL_MACHINE 'SOFTWARE\Salt' 'version'
'''
return __utils__['reg.read_value'](hive=hive,
key=key,
@ -207,96 +234,104 @@ def set_value(hive,
'''
Sets a registry value entry or the default value for a key.
:param str hive: The name of the hive. Can be one of the following
Args:
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
hive (str):
The name of the hive. Can be one of the following
:param str key: The key (looks like a path) to the value name.
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
:param str vname: The value name. These are the individual name/data pairs
under the key. If not passed, the key (Default) value will be set.
key (str):
The key (looks like a path) to the value name.
:param object vdata: 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:
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.
.. glossary::
vdata (str, int, list):
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.
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
The type of data this parameter expects is determined by the value
type specified in ``vtype``. The correspondence is as follows:
:param str vtype: The value type.
The possible values of the vtype parameter are indicated
above in the description of the vdata parameter.
- 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
:param bool use_32bit_registry: Sets the 32bit portion of the registry on
64bit installations. On 32bit machines this is ignored.
.. note::
When setting REG_BINARY, string data will be converted to
binary.
:param bool volatile: 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.
.. note::
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.
:return: Returns True if successful, False if not
:rtype: bool
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:
bool: True if successful, otherwise False
CLI Example:
.. code-block:: bash
.. code-block:: bash
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).
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'version' '2015.5.2'
CLI Example:
.. code-block:: bash
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' 'version' '2015.5.2' \\
vtype=REG_SZ vdata=0
.. code-block:: bash
However, this next example where vdata is properly quoted should succeed.
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'str_data' 1.2
CLI Example:
.. code-block:: bash
In this next example vdata is properly quoted and should succeed.
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'version' '2015.5.2' \\
vtype=REG_SZ vdata="'0'"
.. code-block:: bash
An example of using vtype REG_BINARY is as follows:
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'str_data' vtype=REG_SZ vdata="'1.2'"
CLI Example:
.. code-block:: bash
This is an example of using vtype REG_BINARY.
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'version' '2015.5.2' \\
vtype=REG_BINARY vdata='!!binary d2hhdCdzIHRoZSBwb2ludA=='
.. code-block:: bash
An example of using vtype REG_LIST is as follows:
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'bin_data' vtype=REG_BINARY vdata='!!binary d2hhdCdzIHRoZSBwb2ludA=='
CLI Example:
.. code-block:: bash
An example of using vtype REG_MULTI_SZ is as follows:
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'version' '2015.5.2' \\
vtype=REG_LIST vdata='[a,b,c]'
.. code-block:: bash
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'list_data' vtype=REG_MULTI_SZ vdata='["a", "b", "c"]'
'''
return __utils__['reg.set_value'](hive=hive,
key=key,
@ -313,31 +348,36 @@ def delete_key_recursive(hive, key, use_32bit_registry=False):
Delete a registry key to include all subkeys.
:param hive: The name of the hive. Can be one of the following
Args:
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
hive (str):
The name of the hive. Can be one of the following
:param key: The key to remove (looks like a path)
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
:param bool use_32bit_registry: Deletes the 32bit portion of the registry on
64bit installations. On 32bit machines this is ignored.
key (str):
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
use_32bit_registry (bool):
Deletes the 32bit portion of the registry on 64bit
installations. On 32bit machines this is ignored.
The following example will remove ``salt`` and all its subkeys from the
``SOFTWARE`` key in ``HKEY_LOCAL_MACHINE``:
Returns:
dict: A dictionary listing the keys that deleted successfully as well as
those that failed to delete.
CLI Example:
.. code-block:: bash
The following example will remove ``salt`` and all its subkeys from the
``SOFTWARE`` key in ``HKEY_LOCAL_MACHINE``:
salt '*' reg.delete_key_recursive HKLM SOFTWARE\\salt
.. code-block:: bash
salt '*' reg.delete_key_recursive HKLM SOFTWARE\\salt
'''
return __utils__['reg.delete_key_recursive'](hive=hive,
key=key,
@ -348,30 +388,36 @@ def delete_value(hive, key, vname=None, use_32bit_registry=False):
'''
Delete a registry value entry or the default value for a key.
:param str hive: The name of the hive. Can be one of the following
Args:
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
hive (str):
The name of the hive. Can be one of the following
:param str key: The key (looks like a path) to the value name.
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
:param str vname: The value name. These are the individual name/data pairs
under the key. If not passed, the key (Default) value will be deleted.
key (str):
The key (looks like a path) to the value name.
:param bool use_32bit_registry: Deletes the 32bit portion of the registry on
64bit installations. On 32bit machines this is ignored.
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.
:return: Returns True if successful, False if not
:rtype: bool
use_32bit_registry (bool):
Deletes the 32bit portion of the registry on 64bit installations. On
32bit machines this is ignored.
Return:
bool: True if successful, otherwise False
CLI Example:
.. code-block:: bash
.. code-block:: bash
salt '*' reg.delete_value HKEY_CURRENT_USER 'SOFTWARE\\Salt' 'version'
salt '*' reg.delete_value HKEY_CURRENT_USER 'SOFTWARE\\Salt' 'version'
'''
return __utils__['reg.delete_value'](hive=hive,
key=key,
@ -385,32 +431,30 @@ def import_file(source, use_32bit_registry=False):
.. versionadded:: 2018.3.0
Usage:
Args:
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:
bool: True if successful, otherwise an error is raised
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:
.. code-block:: bash
.. code-block:: bash
salt machine1 reg.import_file salt://win/printer_config/110_Canon/postinstall_config.reg
:param str source: 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``).
:param bool use_32bit_registry: 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.
:return: If the value of ``source`` is an invalid path or otherwise
causes ``cp.cache_file`` to return ``False`` then
the function will not return and
a ``ValueError`` exception will be raised.
If ``reg.exe`` exits with a non-0 exit code, then
a ``CommandExecutionError`` exception will be
raised. On success this function will return
``True``.
:rtype: bool
salt machine1 reg.import_file salt://win/printer_config/110_Canon/postinstall_config.reg
'''
cache_path = __salt__['cp.cache_file'](source)

232
salt/states/reg.py
View file

@ -12,11 +12,12 @@ 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
- HKEY_CLASSES_ROOT (HKCR)
- HKEY_CURRENT_USER(HKCU)
- HKEY_LOCAL MACHINE (HKLM)
- HKEY_USER (HKU)
- HKEY_CURRENT_CONFIG
----
Keys
@ -105,73 +106,107 @@ def present(name,
'''
Ensure a registry key or value is present.
:param str name: A string value representing the full path of the key to
include the HIVE, Key, and all Subkeys. For example:
Args:
``HKEY_LOCAL_MACHINE\\SOFTWARE\\Salt``
name (str):
A string value representing the full path of the key to include the
HIVE, Key, and all Subkeys. For example:
Valid hive values include:
- HKEY_CURRENT_USER or HKCU
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_USERS or HKU
``HKEY_LOCAL_MACHINE\\SOFTWARE\\Salt``
:param str vname: 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
Valid hive values include:
:param str vdata: 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.
- HKEY_CURRENT_USER or HKCU
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_USERS or HKU
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.
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
:param str vtype: The value type for the data you wish to store in the
registry. Valid values are:
vdata (str, int, list):
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.
- REG_BINARY
- REG_DWORD
- REG_EXPAND_SZ
- REG_MULTI_SZ
- REG_SZ (Default)
The type of data this parameter expects is determined by the value
type specified in ``vtype``. The correspondence is as follows:
:param bool use_32bit_registry: Use the 32bit portion of the registry.
Applies only to 64bit windows. 32bit Windows will ignore this parameter.
Default is False.
- 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
:return: Returns a dictionary showing the results of the registry operation.
:rtype: dict
.. 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:
The following example will set the ``(Default)`` value for the
``SOFTWARE\\Salt`` key in the ``HKEY_CURRENT_USER`` hive to ``2016.3.1``:
- ``vdata: Salty Test``
- ``vdata: !!binary U2FsdHkgVGVzdA==\n``
For more information about the ``!!binary`` tag see
`here <http://yaml.org/type/binary.html>`_
.. note::
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.
Returns:
dict: A dictionary showing the results of the registry operation.
Example:
.. code-block:: yaml
The following example will set the ``(Default)`` value for the
``SOFTWARE\\Salt`` key in the ``HKEY_CURRENT_USER`` hive to
``2016.3.1``:
HKEY_CURRENT_USER\\SOFTWARE\\Salt:
reg.present:
- vdata: 2016.3.1
.. code-block:: yaml
The following example will set the value for the ``version`` entry under the
``SOFTWARE\\Salt`` key in the ``HKEY_CURRENT_USER`` hive to ``2016.3.1``. The
value will be reflected in ``Wow6432Node``:
HKEY_CURRENT_USER\\SOFTWARE\\Salt:
reg.present:
- vdata: 2016.3.1
Example:
.. code-block:: yaml
The following example will set the value for the ``version`` entry under
the ``SOFTWARE\\Salt`` key in the ``HKEY_CURRENT_USER`` hive to
``2016.3.1``. The value will be reflected in ``Wow6432Node``:
HKEY_CURRENT_USER\\SOFTWARE\\Salt:
reg.present:
- vname: version
- vdata: 2016.3.1
.. code-block:: yaml
In the above example the path is interpreted as follows:
- ``HKEY_CURRENT_USER`` is the hive
- ``SOFTWARE\\Salt`` is the key
- ``vname`` is the value name ('version') that will be created under the key
- ``vdata`` is the data that will be assigned to 'version'
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 hive
- ``SOFTWARE\\Salt`` is the key
- ``vname`` is the value name ('version') that will be created under the key
- ``vdata`` is the data that will be assigned to 'version'
'''
ret = {'name': name,
'result': True,
@ -226,39 +261,42 @@ def absent(name, vname=None, use_32bit_registry=False):
'''
Ensure a registry value is removed. To remove a key use key_absent.
:param str name: A string value representing the full path of the key to
include the HIVE, Key, and all Subkeys. For example:
Args:
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``
``HKEY_LOCAL_MACHINE\\SOFTWARE\\Salt``
Valid hive values include:
Valid hive values include:
- HKEY_CURRENT_USER or HKCU
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_USERS or HKU
- HKEY_CURRENT_USER or HKCU
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_USERS or HKU
:param str vname: 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
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
:param bool use_32bit_registry: Use the 32bit portion of the registry.
Applies only to 64bit windows. 32bit Windows will ignore this parameter.
Default is False.
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.
:return: Returns a dictionary showing the results of the registry operation.
:rtype: dict
Returns:
dict: A dictionary showing the results of the registry operation.
CLI Example:
.. code-block:: yaml
.. code-block:: yaml
'HKEY_CURRENT_USER\\SOFTWARE\\Salt':
reg.absent
- vname: version
'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. If ``vname`` was not
passed, the (Default) value would be deleted.
In the above example the value named ``version`` will be removed from
the SOFTWARE\\Salt key in the HKEY_CURRENT_USER hive. If ``vname`` was
not passed, the (Default) value would be deleted.
'''
ret = {'name': name,
'result': True,
@ -307,36 +345,40 @@ def key_absent(name, use_32bit_registry=False):
Ensure a registry key is removed. This will remove a key and all value
entries it contains. It will fail if the key contains subkeys.
:param str name: 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:
Args:
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
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:
:param bool use_32bit_registry: Use the 32bit portion of the registry.
Applies only to 64bit windows. 32bit Windows will ignore this parameter.
Default is False.
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
:return: Returns a dictionary showing the results of the registry operation.
:rtype: dict
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.
The following example will delete the ``SOFTWARE\Salt`` key and all subkeys
under the ``HKEY_CURRENT_USER`` hive.
Returns:
dict: A dictionary showing the results of the registry operation.
Example:
.. code-block:: yaml
CLI Example:
'HKEY_CURRENT_USER\SOFTWARE\Salt':
reg.key_absent:
- force: True
The following example will delete the ``SOFTWARE\Salt`` key and all
subkeys under the ``HKEY_CURRENT_USER`` hive.
In the above example the path is interpreted as follows:
.. code-block:: yaml
- ``HKEY_CURRENT_USER`` is the hive
- ``SOFTWARE\Salt`` is the key
'HKEY_CURRENT_USER\SOFTWARE\Salt':
reg.key_absent:
- force: True
In the above example the path is interpreted as follows:
- ``HKEY_CURRENT_USER`` is the hive
- ``SOFTWARE\Salt`` is the key
'''
ret = {'name': name,
'result': True,

393
salt/utils/win_reg.py
View file

@ -6,9 +6,10 @@ 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
- HKEY_LOCAL_MACHINE
- HKEY_CURRENT_USER
- HKEY_USER
----
Keys
@ -157,14 +158,26 @@ class Registry(object): # pylint: disable=R0903
def key_exists(hive, key, use_32bit_registry=False):
'''
Check that the key is found in the registry
Check that the key is found in the registry. This refers to keys and not
value/data pairs.
:param str hive: The hive to connect to.
:param str key: The key to check
:param bool use_32bit_registry: Look in the 32bit portion of the registry
Args:
:return: Returns True if found, False if not found
:rtype: bool
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:
bool: True if exists, otherwise False
Usage:
.. code-block::
import salt.utils.win_reg
winreg.key_exists(hive='HKLM', key='SOFTWARE\\Microsoft')
'''
local_hive = _to_unicode(hive)
local_key = _to_unicode(key)
@ -188,13 +201,15 @@ def broadcast_change():
'''
Refresh the windows environment.
Returns (bool): True if successful, otherwise False
Returns:
bool: True if successful, otherwise False
CLI Example:
Usage:
.. code-block:: bash
.. code-block::
salt '*' reg.broadcast_change
import salt.utils.win_reg
winreg.broadcast_change()
'''
# https://msdn.microsoft.com/en-us/library/windows/desktop/ms644952(v=vs.85).aspx
_, res = win32gui.SendMessageTimeout(
@ -207,28 +222,34 @@ def list_keys(hive, key=None, use_32bit_registry=False):
'''
Enumerates the subkeys in a registry key or hive.
:param str hive: The name of the hive. Can be one of the following
Args:
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
hive (str):
The name of the hive. Can be one of the following:
:param str key: The key (looks like a path) to the value name. If a key is
not passed, the keys under the hive will be returned.
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
:param bool use_32bit_registry: Accesses the 32bit portion of the registry
on 64 bit installations. On 32bit machines this is ignored.
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.
:return: A list of keys/subkeys under the hive or key.
:rtype: list
use_32bit_registry (bool):
Accesses the 32bit portion of the registry on 64 bit installations.
On 32bit machines this is ignored.
CLI Example:
Returns:
list: A list of keys/subkeys under the hive or key.
.. code-block:: bash
Usage:
salt '*' reg.list_keys HKLM 'SOFTWARE'
.. code-block::
import salt.utils.win_reg
winreg.list_keys(hive='HKLM', key='SOFTWARE\\Microsoft')
'''
local_hive = _to_unicode(hive)
@ -265,30 +286,37 @@ def list_values(hive, key=None, use_32bit_registry=False, include_default=True):
'''
Enumerates the values in a registry key or hive.
:param str hive: The name of the hive. Can be one of the following
Args:
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
hive (str):
The name of the hive. Can be one of the following:
:param str key: The key (looks like a path) to the value name. If a key is
not passed, the values under the hive will be returned.
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
:param bool use_32bit_registry: Accesses the 32bit portion of the registry
on 64 bit installations. On 32bit machines this is ignored.
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.
:param bool include_default: Toggle whether to include the '(Default)' value.
use_32bit_registry (bool):
Accesses the 32bit portion of the registry on 64 bit installations.
On 32bit machines this is ignored.
:return: A list of values under the hive or key.
:rtype: list
include_default (bool):
Toggle whether to include the '(Default)' value.
CLI Example:
Returns:
list: A list of values under the hive or key.
.. code-block:: bash
Usage:
salt '*' reg.list_values HKLM 'SYSTEM\\CurrentControlSet\\Services\\Tcpip'
.. code-block::
import salt.utils.win_reg
winreg.list_values(hive='HKLM', key='SYSTEM\\CurrentControlSet\\Services\\Tcpip')
'''
local_hive = _to_unicode(hive)
local_key = _to_unicode(key)
@ -337,38 +365,43 @@ def read_value(hive, key, vname=None, use_32bit_registry=False):
r'''
Reads a registry value entry or the default value for a key.
:param str hive: The name of the hive. Can be one of the following
Args:
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
hive (str): The name of the hive. Can be one of the following:
:param str key: The key (looks like a path) to the value name.
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
:param str vname: The value name. These are the individual name/data pairs
under the key. If not passed, the key (Default) value will be returned
key (str):
The key (looks like a path) to the value name.
:param bool use_32bit_registry: Accesses the 32bit portion of the registry
on 64bit installations. On 32bit machines this is ignored.
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.
:return: A dictionary containing the passed settings as well as the
value_data if successful. If unsuccessful, sets success to False.
use_32bit_registry (bool):
Accesses the 32bit portion of the registry on 64bit installations.
On 32bit machines this is ignored.
:rtype: dict
Returns:
dict: A dictionary containing the passed settings as well as the
value_data if successful. If unsuccessful, sets success to False.
If vname is not passed:
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.
- 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:
Usage:
.. code-block:: bash
.. code-block::
salt '*' reg.read_value HKEY_LOCAL_MACHINE 'SOFTWARE\Salt' 'version'
import salt.utils.win_reg
winreg.read_value(hive='HKLM', key='SOFTWARE\\Salt', vname='version')
'''
# If no name is passed, the default value of the key will be returned
# The value name is Default
@ -440,96 +473,115 @@ def set_value(hive,
'''
Sets a registry value entry or the default value for a key.
:param str hive: The name of the hive. Can be one of the following
Args:
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
hive (str):
The name of the hive. Can be one of the following
:param str key: The key (looks like a path) to the value name.
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
:param str vname: The value name. These are the individual name/data pairs
under the key. If not passed, the key (Default) value will be set.
key (str):
The key (looks like a path) to the value name.
:param object vdata: 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:
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.
.. glossary::
vdata (str, int, list):
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.
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
The type of data this parameter expects is determined by the value
type specified in ``vtype``. The correspondence is as follows:
:param str vtype: The value type.
The possible values of the vtype parameter are indicated
above in the description of the vdata parameter.
- 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
:param bool use_32bit_registry: Sets the 32bit portion of the registry on
64bit installations. On 32bit machines this is ignored.
.. note::
When setting REG_BINARY, string data will be converted to
binary. You can pass base64 encoded using the ``binascii``
built-in module. Use ``binascii.b2a_base64('your data')``
:param bool volatile: 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.
.. note::
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.
:return: Returns True if successful, False if not
:rtype: bool
vtype (str):
The value type. The possible values of the vtype parameter are
indicated above in the description of the vdata parameter.
CLI Example:
use_32bit_registry (bool):
Sets the 32bit portion of the registry on 64bit installations. On
32bit machines this is ignored.
.. code-block:: bash
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.
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'version' '2015.5.2'
Returns:
bool: True if successful, otherwise False
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).
Usage:
CLI Example:
.. code-block:: python
.. code-block:: bash
import salt.utils.win_reg
winreg.set_value(hive='HKLM', key='SOFTWARE\\Salt', vname='version', vdata='2015.5.2')
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'version' '2015.5.2' \\
vtype=REG_SZ vdata=0
Usage:
However, this next example where vdata is properly quoted should succeed.
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).
CLI Example:
.. code-block:: python
.. code-block:: bash
import salt.utils.win_reg
winreg.set_value(hive='HKLM', key='SOFTWARE\\Salt', vname='str_data', vdata=1.2)
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'version' '2015.5.2' \\
vtype=REG_SZ vdata="'0'"
Usage:
An example of using vtype REG_BINARY is as follows:
In this next example vdata is properly quoted and should succeed.
CLI Example:
.. code-block:: python
.. code-block:: bash
import salt.utils.win_reg
winreg.set_value(hive='HKLM', key='SOFTWARE\\Salt', vname='str_data', vdata='1.2')
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'version' '2015.5.2' \\
vtype=REG_BINARY vdata='!!binary d2hhdCdzIHRoZSBwb2ludA=='
Usage:
An example of using vtype REG_LIST is as follows:
This is an example of using vtype REG_BINARY. Both ``set_value``
commands will set the same value ``Salty Test``
CLI Example:
.. code-block:: python
.. code-block:: bash
import salt.utils.win_reg
winreg.set_value(hive='HKLM', key='SOFTWARE\\Salt', vname='bin_data', vdata='Salty Test', vtype='REG_BINARY')
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'version' '2015.5.2' \\
vtype=REG_LIST vdata='[a,b,c]'
import binascii
bin_data = binascii.b2a_base64('Salty Test')
winreg.set_value(hive='HKLM', key='SOFTWARE\\Salt', vname='bin_data_encoded', vdata=bin_data, vtype='REG_BINARY')
Usage:
An example using vtype REG_MULTI_SZ is as follows:
.. code-block:: python
import salt.utils.win_reg
winreg.set_value(hive='HKLM', key='SOFTWARE\\Salt', vname='list_data', vdata=['Salt', 'is', 'great'], vtype='REG_MULTI_SZ')
'''
local_hive = _to_unicode(hive)
local_key = _to_unicode(key)
@ -576,15 +628,24 @@ def cast_vdata(vdata=None, vtype='REG_SZ'):
vtype (str):
The type of data to be written to the registry. Must be one of the
following:
- REG_BINARY
- REG_DWORD
- REG_EXPAND_SZ
- REG_MULTI_SZ
- REG_QWORD
- REG_SZ
Returns:
The vdata cast to the appropriate type. Will be unicode string, binary,
list of unicode strings, or int
Usage:
.. code-block:: python
import salt.utils.win_reg
winreg.cast_vdata(vdata='This is the string', vtype='REG_SZ')
'''
# Check data type and cast to expected type
# int will automatically become long on 64bit numbers
@ -616,31 +677,37 @@ def delete_key_recursive(hive, key, use_32bit_registry=False):
Delete a registry key to include all subkeys.
:param hive: The name of the hive. Can be one of the following
Args:
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
hive (str):
The name of the hive. Can be one of the following
:param key: The key to remove (looks like a path)
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
:param bool use_32bit_registry: Deletes the 32bit portion of the registry on
64bit installations. On 32bit machines this is ignored.
key (str):
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
use_32bit_registry (bool):
Deletes the 32bit portion of the registry on 64bit
installations. On 32bit machines this is ignored.
The following example will remove ``salt`` and all its subkeys from the
``SOFTWARE`` key in ``HKEY_LOCAL_MACHINE``:
Returns:
dict: A dictionary listing the keys that deleted successfully as well as
those that failed to delete.
CLI Example:
Usage:
.. code-block:: bash
The following example will remove ``salt`` and all its subkeys from the
``SOFTWARE`` key in ``HKEY_LOCAL_MACHINE``:
salt '*' reg.delete_key_recursive HKLM SOFTWARE\\salt
.. code-block:: python
import salt.utils.win_reg
winreg.delete_key_recursive(hive='HKLM', key='SOFTWARE\\DeleteMe')
'''
local_hive = _to_unicode(hive)
@ -718,31 +785,37 @@ def delete_value(hive, key, vname=None, use_32bit_registry=False):
'''
Delete a registry value entry or the default value for a key.
:param str hive: The name of the hive. Can be one of the following
Args:
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
hive (str):
The name of the hive. Can be one of the following
:param str key: The key (looks like a path) to the value name.
- HKEY_LOCAL_MACHINE or HKLM
- HKEY_CURRENT_USER or HKCU
- HKEY_USER or HKU
- HKEY_CLASSES_ROOT or HKCR
- HKEY_CURRENT_CONFIG or HKCC
:param str vname: The value name. These are the individual name/data pairs
under the key. If not passed, the key (Default) value will be deleted.
key (str):
The key (looks like a path) to the value name.
:param bool use_32bit_registry: Deletes the 32bit portion of the registry on
64bit installations. On 32bit machines this is ignored.
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.
:return: Returns True if successful, None if the value didn't exist, and
False if unsuccessful
:rtype: bool
use_32bit_registry (bool):
Deletes the 32bit portion of the registry on 64bit installations. On
32bit machines this is ignored.
CLI Example:
Return:
bool: True if successful, otherwise False
.. code-block:: bash
Usage:
salt '*' reg.delete_value HKEY_CURRENT_USER 'SOFTWARE\\Salt' 'version'
.. code-block:: python
import salt.utils.win_reg
winreg.delete_value(hive='HKLM', key='SOFTWARE\\SaltTest', vname='version')
'''
local_hive = _to_unicode(hive)
local_key = _to_unicode(key)