Current File : //lib/python2.7/site-packages/salt/states/reg.pyc
�
���^c
@@ s� d Z d d l m Z m Z m Z d d l Z d d l Z e j e � Z
d � Z d � Z e
e
d e e
e
e
e e d � Z e
e d � Z e d � Z d S(
u�
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 hive\key 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 hive\key:
Using single backslashes:
HKLM\SOFTWARE\Python
'HKLM\SOFTWARE\Python'
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:
.. code-block:: text
[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``, and ``BTMTrayAgent``
- Each value name has a corresponding value
i ( t absolute_importt print_functiont unicode_literalsNc C@ s\ d t k r t d f Sd t k r, t d f Sd t k rB t d f Sd t k rX t d f Sd S(
u2
Load this state if the reg module exists
u reg.read_valueuF reg state module failed to load: missing util function: reg.read_valueu
reg.set_valueuE reg state module failed to load: missing util function: reg.set_valueu reg.delete_valueuH reg state module failed to load: missing util function: reg.delete_valueu reg.delete_key_recursiveuP reg state module failed to load: missing util function: reg.delete_key_recursiveu reg( t __utils__t False( ( ( s3 /usr/lib/python2.7/site-packages/salt/states/reg.pyt __virtual__Q s
c C@ s7 | j d � } | j d � } d j | � } | | f S( u%
split the hive from the key
u \i ( t splitt popt join( t keyt spltt hive( ( s3 /usr/lib/python2.7/site-packages/salt/states/reg.pyt
_parse_keyh s u REG_SZc
C@ s� i | d 6t d 6i d 6i d 6d d 6}
t | � \ } } t d d | d | d
| d | � }
| |
d k ow |
d
rd j | r� t j j j | d � n d t j j j | d � � |
d <t d d d j | | g � d | r� d n d d |
d | d | d | d | d | � Sn t d d | d | � } i d j | | � d! 6d" j | rlt j j j | d � n d � d# 6| d$ 6| d% 6i | d& 6| d' 6d( 6| d) 6} t d* r�t
|
d <i i | d+ 6d, 6|
d <|
Sn t d- d | d | d
| d | d | d | � |
d <|
d r<i |
d <d. j | | | � |
d <n1 i i | d/ 6d, 6|
d <d0 j | | | � |
d <|
d r�t d d d j | | g � d | r�d n d d |
d | d | d | d | d | � }
n |
S(1 u�"
Ensure a registry key or value is present.
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``
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
`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.
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.
.. versionadded:: 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 specified ``this_key_subkeys`` is used.
Valid options are:
Applies to settings:
- this_key_only
- this_key_subkeys
- subkeys_only
.. versionadded:: 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.
.. versionadded:: 2019.2.0
win_inheritance (bool):
``True`` to inherit permissions from the parent key. ``False`` to
disable inheritance. Default is ``True``.
.. note::
Inheritance is set for the key that contains the value/data
pair. You cannot set inheritance on value/data pairs themselves.
.. versionadded:: 2019.2.0
win_perms_reset (bool):
If ``True`` the existing DACL will be cleared and replaced with the
settings defined in this function. If ``False``, new entries will be
appended to the existing DACL. Default is ``False``
.. note::
Perms are reset for the key that contains the value/data pair.
You cannot set permissions on value/data pairs themselves.
.. versionadded:: 2019.2.0
Returns:
dict: A dictionary showing the results of the registry operation.
Example:
The following example will set the ``(Default)`` value for the
``SOFTWARE\\Salt`` key in the ``HKEY_CURRENT_USER`` hive to
``2016.3.1``:
.. code-block:: yaml
HKEY_CURRENT_USER\\SOFTWARE\\Salt:
reg.present:
- vdata: 2016.3.1
Example:
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``:
.. code-block:: yaml
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'
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
Example:
To ensure a key is present and has permissions:
.. code-block:: yaml
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
u nameu resultu changesu pchangesu u commentu reg.read_valueR R t vnamet use_32bit_registryu vdatau successu {0} in {1} is already presentu utf-8u (Default)u dacl.check_permst obj_nameu \t obj_typeu
registry32u registryt rett ownert grant_permst
deny_permst inheritancet resetu reg.cast_vdatat vdatat vtypeu {0}\{1}u Keyu {0}u Entryu Valueu Owneru Grantu Denyu Permsu Inheritanceu testu Will addu regu
reg.set_valueu Failed to add {0} to {1}\{2}u Addedu Added {0} to {1}\{2}( t TrueR R t formatt saltt utilst stringutilst
to_unicodeR t __opts__t None( t nameR
R R R t win_ownert win_permst win_deny_permst win_inheritancet win_perms_resetR R R t reg_currentt
vdata_decodedt
add_change( ( s3 /usr/lib/python2.7/site-packages/salt/states/reg.pyt presentr st �
!
.
c
C@ sx i | d 6t d 6i d 6d d 6} t | � \ } } t d d | d | d | d
| � } | d st | d d
k r� d j | � | d <| Si d j | | � d 6d j | r� | n d � d 6} t d r� d | d <i i | d 6d 6| d <| St d d | d | d | d
| � | d <| d sFi | d <d j | | � | d <n. i i | d 6d 6| d <d j | | � | d <| S( u&
Ensure a registry value is removed. To remove a key use key_absent.
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``
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
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.
CLI Example:
.. code-block:: yaml
'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.
u nameu resultu changesu u commentu reg.read_valueR R R
R u successu vdatau (value not set)u {0} is already absentu {0}\{1}u Keyu {0}u (Default)u Entryu testu Will removeu regu reg.delete_valueu Failed to remove {0} from {1}u Removedu Removed {0} from {1}N( R R R R R R ( R! R
R R R R t reg_checkt
remove_change( ( s3 /usr/lib/python2.7/site-packages/salt/states/reg.pyt absent� s8 )
c C@ s i | d 6t d 6i d 6d d 6} t | � \ } } t d d | d | d | � d
sn d j | � | d <| Si i i d j | | � d
6d 6d 6| d <t d r� d | d <| St d d | d | d | � t d d | d | d | � d
rt | d <i | d <d j | � | d <n | S( u�
.. versionadded:: 2015.5.4
Ensure a registry key is removed. This will remove the key, subkeys, and all
value entries.
Args:
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:
dict: A dictionary showing the results of the registry operation.
CLI Example:
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
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 hive
- ``SOFTWARE\DeleteMe`` is the key
u nameu resultu changesu u commentu reg.read_valueR R R u successu {0} is already absentu {0}\{1}u Keyu Removedu regu testu reg.delete_key_recursiveu! Failed to remove registry key {0}N( R R R R R R R ( R! R R R R ( ( s3 /usr/lib/python2.7/site-packages/salt/states/reg.pyt
key_absent s6 *
"
( t __doc__t
__future__R R R t loggingt salt.utils.stringutilsR t getLoggert __name__t logR R R R R R* R- R. ( ( ( s3 /usr/lib/python2.7/site-packages/salt/states/reg.pyt <module>G s$ � TQ
Mini Shell