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:

SaltInvocationError -- Invalid policy_class
CommandExecutionError -- On failure

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:

SaltInvocationError -- Invalid policy_class
CommandExecutionError -- On failure

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:

SaltInvocationError -- Invalid policy_class
SaltInvocationError -- Invalid v_type
SaltInvocationError -- v_data doesn't match v_type

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:

SaltInvocationError -- Invalid policy class
CommandExecutionError -- On failure

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:25 UTC.

You are viewing docs for the latest stable release, 3007.1. Switch to docs for the previous stable release, 3006.9, or to a recent doc build from the master branch.

saltproject.io