mirror of
https://github.com/saltstack/salt.git
synced 2025-04-17 10:10:20 +00:00
Add additional examples
This commit is contained in:
twangboy
parent
24df6ec1b7
commit
af5139c2ff
3 changed files with 151 additions and 34 deletions
|
|
@ -20,10 +20,41 @@ 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: - PyWin32
|
||||
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:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
[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
|
||||
'''
|
||||
# When production windows installer is using Python 3, Python 2 code can be removed
|
||||
from __future__ import absolute_import, print_function, unicode_literals
|
||||
|
|
@ -43,7 +74,7 @@ __virtualname__ = 'reg'
|
|||
|
||||
def __virtual__():
|
||||
'''
|
||||
Only works on Windows systems with the PyWin32
|
||||
Only works on Windows systems with PyWin32
|
||||
'''
|
||||
if not salt.utils.platform.is_windows():
|
||||
return (False, 'reg execution module failed to load: '
|
||||
|
|
@ -87,6 +118,10 @@ def 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:
|
||||
bool: True if successful, otherwise False
|
||||
|
||||
|
|
@ -179,7 +214,8 @@ def list_values(hive, key=None, use_32bit_registry=False, include_default=True):
|
|||
|
||||
def read_value(hive, key, vname=None, use_32bit_registry=False):
|
||||
r'''
|
||||
Reads a registry value entry or the default value for a key.
|
||||
Reads a registry value entry or the default value for a key. To read the
|
||||
default value, don't pass ``vname``
|
||||
|
||||
Args:
|
||||
|
||||
|
|
@ -206,17 +242,30 @@ def read_value(hive, key, vname=None, use_32bit_registry=False):
|
|||
dict: 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.
|
||||
- Returns False if key not found.
|
||||
|
||||
CLI Example:
|
||||
|
||||
The following will get the value of the ``version`` value name in the
|
||||
``HKEY_LOCAL_MACHINE\\SOFTWARE\\Salt`` key
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
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
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' reg.read_value HKEY_LOCAL_MACHINE 'SOFTWARE\Salt'
|
||||
'''
|
||||
return __utils__['reg.read_value'](hive=hive,
|
||||
key=key,
|
||||
|
|
@ -232,7 +281,9 @@ def set_value(hive,
|
|||
use_32bit_registry=False,
|
||||
volatile=False):
|
||||
'''
|
||||
Sets a registry value entry or the default value for a key.
|
||||
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
|
||||
|
||||
Args:
|
||||
|
||||
|
|
@ -298,6 +349,9 @@ def set_value(hive,
|
|||
|
||||
CLI Example:
|
||||
|
||||
This will set the version value to 2015.5.2 in the SOFTWARE\\Salt key in
|
||||
the HKEY_LOCAL_MACHINE hive
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'version' '2015.5.2'
|
||||
|
|
@ -334,7 +388,7 @@ def set_value(hive,
|
|||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'list_data' vtype=REG_MULTI_SZ vdata='["a", "b", "c"]'
|
||||
salt '*' reg.set_value HKEY_LOCAL_MACHINE 'SOFTWARE\\Salt' 'list_data' vtype=REG_MULTI_SZ vdata='["Salt", "is", "great"]'
|
||||
'''
|
||||
return __utils__['reg.set_value'](hive=hive,
|
||||
key=key,
|
||||
|
|
@ -349,7 +403,7 @@ def delete_key_recursive(hive, key, use_32bit_registry=False):
|
|||
'''
|
||||
.. versionadded:: 2015.5.4
|
||||
|
||||
Delete a registry key to include all subkeys.
|
||||
Delete a registry key to include all subkeys and value/data pairs.
|
||||
|
||||
Args:
|
||||
|
||||
|
|
@ -375,12 +429,12 @@ def delete_key_recursive(hive, key, use_32bit_registry=False):
|
|||
|
||||
CLI Example:
|
||||
|
||||
The following example will remove ``salt`` and all its subkeys from the
|
||||
The following example will remove ``delete_me`` and all its subkeys from the
|
||||
``SOFTWARE`` key in ``HKEY_LOCAL_MACHINE``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
salt '*' reg.delete_key_recursive HKLM SOFTWARE\\salt
|
||||
salt '*' reg.delete_key_recursive HKLM SOFTWARE\\delete_me
|
||||
'''
|
||||
return __utils__['reg.delete_key_recursive'](hive=hive,
|
||||
key=key,
|
||||
|
|
|
|||
|
|
@ -61,6 +61,8 @@ Value:
|
|||
- `NvBackend`
|
||||
- `BTMTrayAgent`
|
||||
- Each value name has a corresponding value
|
||||
|
||||
:depends: - salt.utils.win_reg
|
||||
'''
|
||||
from __future__ import absolute_import, print_function, unicode_literals
|
||||
|
||||
|
|
@ -77,19 +79,19 @@ def __virtual__():
|
|||
'''
|
||||
if 'reg.read_value' not in __utils__:
|
||||
return (False, 'reg state module failed to load: '
|
||||
'missing module function: reg.read_value')
|
||||
'missing util function: reg.read_value')
|
||||
|
||||
if 'reg.set_value' not in __utils__:
|
||||
return (False, 'reg state module failed to load: '
|
||||
'missing module function: reg.set_value')
|
||||
'missing util function: reg.set_value')
|
||||
|
||||
if 'reg.delete_value' not in __utils__:
|
||||
return (False, 'reg state module failed to load: '
|
||||
'missing module function: reg.delete_value')
|
||||
'missing util function: reg.delete_value')
|
||||
|
||||
if 'reg.delete_key_recursive' not in __utils__:
|
||||
return (False, 'reg state module failed to load: '
|
||||
'missing module function: reg.delete_key_recursive')
|
||||
'missing util function: reg.delete_key_recursive')
|
||||
|
||||
return 'reg'
|
||||
|
||||
|
|
@ -213,6 +215,41 @@ def present(name,
|
|||
- ``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'
|
||||
|
||||
Example:
|
||||
|
||||
Binary data can be set in two ways. The following two examples will set
|
||||
a binary value of ``Salty Test``
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
reg_multi_sz:
|
||||
reg.present:
|
||||
- name: HKLM\SOFTWARE\Salt
|
||||
- vname: reg_multi_sz
|
||||
- vdata:
|
||||
- list item 1
|
||||
- list item 2
|
||||
'''
|
||||
ret = {'name': name,
|
||||
'result': True,
|
||||
|
|
@ -348,8 +385,8 @@ def key_absent(name, use_32bit_registry=False):
|
|||
r'''
|
||||
.. versionadded:: 2015.5.4
|
||||
|
||||
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.
|
||||
Ensure a registry key is removed. This will remove the key, subkeys, and all
|
||||
value entries.
|
||||
|
||||
Args:
|
||||
|
||||
|
|
@ -372,19 +409,19 @@ def key_absent(name, use_32bit_registry=False):
|
|||
|
||||
CLI Example:
|
||||
|
||||
The following example will delete the ``SOFTWARE\Salt`` key and all
|
||||
subkeys under the ``HKEY_CURRENT_USER`` hive.
|
||||
The following example will delete the ``SOFTWARE\DeleteMe`` key in the
|
||||
``HKEY_LOCAL_MACHINE` hive including all its subkeys and value pairs.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
'HKEY_CURRENT_USER\SOFTWARE\Salt':
|
||||
remove_key_demo:
|
||||
reg.key_absent:
|
||||
- force: True
|
||||
- name: HKEY_CURRENT_USER\SOFTWARE\DeleteMe
|
||||
|
||||
In the above example the path is interpreted as follows:
|
||||
|
||||
- ``HKEY_CURRENT_USER`` is the hive
|
||||
- ``SOFTWARE\Salt`` is the key
|
||||
- ``SOFTWARE\DeleteMe`` is the key
|
||||
'''
|
||||
ret = {'name': name,
|
||||
'result': True,
|
||||
|
|
@ -400,10 +437,10 @@ def key_absent(name, use_32bit_registry=False):
|
|||
ret['comment'] = '{0} is already absent'.format(name)
|
||||
return ret
|
||||
|
||||
ret['changes'] = {'reg': {
|
||||
'Removed': {
|
||||
'Key': r'{0}\{1}'.format(hive, key)
|
||||
}}}
|
||||
ret['changes'] = {
|
||||
'reg': {
|
||||
'Removed': {
|
||||
'Key': r'{0}\{1}'.format(hive, key)}}}
|
||||
|
||||
# Check for test option
|
||||
if __opts__['test']:
|
||||
|
|
|
|||
|
|
@ -15,13 +15,14 @@ Hives are the main sections of the registry and all begin with the word HKEY.
|
|||
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)
|
||||
can have a value assigned to them under the (Default) value name
|
||||
|
||||
-----------------
|
||||
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.
|
||||
(Default) value corresponds to the Key itself, the rest are their own name/value
|
||||
pairs.
|
||||
|
||||
:depends: - PyWin32
|
||||
'''
|
||||
|
|
@ -92,7 +93,8 @@ def _to_unicode(vdata):
|
|||
|
||||
class Registry(object): # pylint: disable=R0903
|
||||
'''
|
||||
Delay usage until this module is used
|
||||
This was put in a class to delay usage until this module is actually used
|
||||
This class contains all the lookup dicts for working with the registry
|
||||
'''
|
||||
def __init__(self):
|
||||
self.hkeys = {
|
||||
|
|
@ -201,6 +203,10 @@ def 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:
|
||||
bool: True if successful, otherwise False
|
||||
|
||||
|
|
@ -363,7 +369,8 @@ def list_values(hive, key=None, use_32bit_registry=False, include_default=True):
|
|||
|
||||
def read_value(hive, key, vname=None, use_32bit_registry=False):
|
||||
r'''
|
||||
Reads a registry value entry or the default value for a key.
|
||||
Reads a registry value entry or the default value for a key. To read the
|
||||
default value, don't pass ``vname``
|
||||
|
||||
Args:
|
||||
|
||||
|
|
@ -388,20 +395,34 @@ def read_value(hive, key, vname=None, use_32bit_registry=False):
|
|||
|
||||
Returns:
|
||||
dict: A dictionary containing the passed settings as well as the
|
||||
value_data if successful. If unsuccessful, sets success to False.
|
||||
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.
|
||||
- Returns False if key not found.
|
||||
|
||||
Usage:
|
||||
|
||||
The following will get the value of the ``version`` value name in the
|
||||
``HKEY_LOCAL_MACHINE\\SOFTWARE\\Salt`` key
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import salt.utils.win_reg
|
||||
winreg.read_value(hive='HKLM', key='SOFTWARE\\Salt', vname='version')
|
||||
|
||||
Usage:
|
||||
|
||||
The following will get the default value of the
|
||||
``HKEY_LOCAL_MACHINE\\SOFTWARE\\Salt`` key
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import salt.utils.win_reg
|
||||
winreg.read_value(hive='HKLM', key='SOFTWARE\\Salt')
|
||||
'''
|
||||
# If no name is passed, the default value of the key will be returned
|
||||
# The value name is Default
|
||||
|
|
@ -471,7 +492,9 @@ def set_value(hive,
|
|||
use_32bit_registry=False,
|
||||
volatile=False):
|
||||
'''
|
||||
Sets a registry value entry or the default value for a key.
|
||||
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
|
||||
|
||||
Args:
|
||||
|
||||
|
|
@ -538,6 +561,9 @@ def set_value(hive,
|
|||
|
||||
Usage:
|
||||
|
||||
This will set the version value to 2015.5.2 in the SOFTWARE\\Salt key in
|
||||
the HKEY_LOCAL_MACHINE hive
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import salt.utils.win_reg
|
||||
|
|
@ -678,7 +704,7 @@ def delete_key_recursive(hive, key, use_32bit_registry=False):
|
|||
'''
|
||||
.. versionadded:: 2015.5.4
|
||||
|
||||
Delete a registry key to include all subkeys.
|
||||
Delete a registry key to include all subkeys and value/data pairs.
|
||||
|
||||
Args:
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue