salt.modules.win_lgpo_reg

LGPO - Registry.pol

New in version 3006.0.

A module for working with registry based policies in Windows Local Group Policy (LGPO). This module contains functions for working with the Registry.pol file. The Registry.pol file is the source of truth for registry settings and LGPO.

Group Policy is refreshed every 90 seconds by default. During that refresh the contents of the Registry.pol file are applied to the Registry. If the setting is changed outside of Group Policy to something other than what is contained in the Registry.pol file, it will be changed back during the next refresh.

In the Group Policy Editor (gpedit.msc) these policies can be set to three states:

  • Not Configured

  • Enabled

  • Disabled

A policy that is "Not Configured" does not have an entry in the Registry.pol file. A Group Policy refresh will not make any changes to key/value pairs in the registry that are not specified in the Registry.pol file.

An "Enabled" policy will have an entry in the Registry.pol files that contains its key path, value name, value type, value size, and value data. When Group Policy is refreshed, existing values will be overwritten with those contained in the Registry.pol file.

A "Disabled" policy will have an entry in the Registry.pol file with the key path and the value name, but the value name will be prepended with **del.. When Group Policy is refreshed the key/value will be deleted from the registry. If the key contains no values, it will also be deleted.

Working with LGPO Reg

The easiest way to figure out the values needed for this module is to set the policy using the Group Policy Editor (gpedit.msc) and then run the lgpo_reg.read_reg_pol function. This function will display a dictionary of all registry-based policies in the Registry.pol file. From its return you can get the key, v_name, v_type, and v_data required to "enable" that policy. Use those values to set/disable/delete policies using this module. The same values can also be used to create states for setting these policies.

Note

Not all policies in the Group Policy Editor (gpedit.msc) that write to the registry make that change in the Registry.pol file. Those policies could still be enforced via the Registry.pol file... theoretically. But you will have to find the values needed to set them with this module using a different method.

salt.modules.win_lgpo_reg.delete_value(key, v_name, policy_class='Machine')

Delete a key/value pair from the Registry.pol file. This bypasses the admx/adml style policies. This is the equivalent of setting the policy to Not Configured.

Parameters:

  • key (str) -- The registry key path

  • v_name (str) -- The registry value name within the key

  • policy_class (str) --

    The registry class to write to. Can be one of the following:

    • Computer

    • Machine

    • User

    Default is Machine

Raises:
Returns:

True if successful, otherwise False None: Key/value not present

Return type:

bool

CLI Example:

# Delete all values under a key
salt '*' lgpo_reg.delete_value "SOFTWARE\MyKey" "MyValue"
salt.modules.win_lgpo_reg.disable_value(key, v_name, policy_class='machine')

Mark a registry value for deletion in the registry.pol file. This bypasses the admx/adml style policies. This is the equivalent of setting the policy to Disabled in the Group Policy editor (gpedit.msc)

Parameters:

  • key (str) -- The registry key path

  • v_name (str) -- The registry value name within the key

  • policy_class (str) --

    The registry class to write to. Can be one of the following:

    • Computer

    • Machine

    • User

    Default is Machine

Raises:
Returns:

True if successful, otherwise False None: If already disabled

Return type:

bool

CLI Example:

# Delete a value
salt '*' lgpo_reg.delete_value "SOFTWARE\MyKey" "MyValue"
salt.modules.win_lgpo_reg.get_key(key, policy_class='Machine')

Get all the values set in a key in the Registry.pol file.

Parameters:

  • key (str) -- The registry key where the values reside

  • policy_class (str) -- The registry class to read from. Can be one of the following:

Raises:

SaltInvocationError -- Invalid policy class

Returns:

A dictionary containing the value data and the value type

Return type:

dict

CLI Example:

# Get all values from a key
salt '*' lgpo_reg.get_key "SOFTWARE\MyKey"
salt.modules.win_lgpo_reg.get_value(key, v_name, policy_class='Machine')

Get the value of a single value pair as set in the Registry.pol file.

Parameters:

  • key (str) -- The registry key where the value name resides

  • v_name (str) -- The value name to retrieve

  • policy_class (str) -- The registry class to read from. Can be one of the following:

Raises:

SaltInvocationError -- Invalid policy class

Returns:

A dictionary containing the value data and the value type found

Return type:

dict

CLI Example:

# Get a value
salt '*' lgpo_reg.get_value "SOFTWARE\MyKey" "MyValue"
salt.modules.win_lgpo_reg.read_reg_pol(policy_class='Machine')

Read the contents of the Registry.pol file. Display the contents as a human-readable dictionary.

Parameters:

policy_class (str) --

The registry class to retrieve. Can be one of the following:

  • Computer

  • Machine

  • User

Default is Machine

Raises:

SaltInvocationError -- Invalid policy class

Returns:

A dictionary representing the contents of the Registry.pol file

Return type:

dict

CLI Example:

# Read the machine Registry.pol
salt '*' lgpo_reg.read_reg_pol
salt.modules.win_lgpo_reg.set_value(key, v_name, v_data, v_type='REG_DWORD', policy_class='Machine')

Add a key/value pair to the registry.pol file. This bypasses the admx/adml style policies. This is the equivalent of setting a policy to Enabled

Parameters:

  • key (str) -- The registry key path

  • v_name (str) -- The registry value name within the key

  • v_data (str) -- The registry value

  • v_type (str) --

    The registry value type. Must be one of the following:

    • REG_BINARY

    • REG_DWORD

    • REG_EXPAND_SZ

    • REG_MULTI_SZ

    • REG_QWORD

    • REG_SZ

    Default is REG_DWORD

  • policy_class (str) --

    The registry class to write to. Can be one of the following:

    • Computer

    • Machine

    • User

    Default is Machine

Raises:
Returns:

True if successful, otherwise False

Return type:

bool

CLI Example:

# Set REG_DWORD value (default)
salt '*' lgpo_reg.set_value "SOFTWARE\MyKey" "MyValue" 1

# Set REG_SZ value
salt '*' lgpo_reg.set_value "SOFTWARE\MyKey" "MyValue" "string value" "REG_SZ"
salt.modules.win_lgpo_reg.write_reg_pol(data, policy_class='Machine')

Write data to the Registry.pol file. The data is a dictionary that is then converted to the appropriate bytes format expected by Registry.pol

Parameters:

  • data (dict) -- A dictionary containing Registry.pol data

  • policy_class (str) --

    The registry class to write to. Can be one of the following:

    • Computer

    • Machine

    • User

    Default is Machine

Raises:
Returns:

True if successful

Return type:

bool

CLI Example:

# Write to Machine Registry.pol
salt '*' lgpo_reg.write_reg_pol "{'SOFTWARE\MyKey': {'MyValue': 'data': 1, 'type': 'REG_DWORD'}}"

Generated on December 18, 2024 at 17:29:28 UTC.

You are viewing docs built from a recent snapshot of the master branch. Switch to docs for the latest stable release, 3007.1.


saltproject.io

© 2024 VMware, Inc. | Privacy Policy