salt.states.win_lgpo_reg#

LGPO - Registry.pol#

New in version 3006.0.

A state 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 configure that policy.

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.states.win_lgpo_reg.refresh_policy(name)#

Trigger a Machine Group Policy refresh.

This is an imperative state — it fires a refresh signal every run. Use it at the end of a block of value_present / value_disabled states that were applied with refresh_policy: False to commit all policy changes in a single GP refresh pass.

Note

This state does not assert a persistent desired configuration. It signals the Group Policy service to process the current Registry.pol file. Registry values will be updated asynchronously after the service completes its refresh cycle. To verify the applied state, run lgpo_reg.get_rsop_value after allowing the refresh to complete.

The recommended pattern on Domain Controllers is to write all policy values with refresh_policy: False, then seal the batch with a single lgpo_reg.refresh_policy state using require:

set_appx_policy:
  lgpo_reg.value_present:
    - key: SOFTWARE\\Policies\\Microsoft\\Windows\\Appx
    - name: AllowAllTrustedApps
    - v_type: REG_DWORD
    - v_data: 0
    - refresh_policy: False

set_smartscreen_policy:
  lgpo_reg.value_present:
    - key: SOFTWARE\\Policies\\Microsoft\\Windows\\System
    - name: EnableSmartScreen
    - v_type: REG_DWORD
    - v_data: 1
    - refresh_policy: False

apply_local_policy:
  lgpo_reg.refresh_policy:
    - name: apply_local_policy
    - require:
      - lgpo_reg: set_appx_policy
      - lgpo_reg: set_smartscreen_policy
Parameters:

name (str) -- Arbitrary identifier for the state (not used functionally).

Returns:

Standard state return with result indicating whether the refresh signal was accepted.

Return type:

dict

salt.states.win_lgpo_reg.value_absent(name, key, policy_class='Machine', write_registry=None, refresh_policy=False)#

Ensure a registry setting is not present in the Registry.pol file.

Parameters:

  • key (str) -- The registry key path

  • 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

  • write_registry (bool, optional) --

    Controls whether the registry value is also deleted immediately after updating Registry.pol.

    • None (default): auto-detect. Skips the registry delete on Domain Controllers; deletes directly on all other machine types.

    • True: always delete from the registry (non-DC behaviour).

    • False: always skip the registry delete; the Group Policy engine will remove the value on the next refresh.

  • refresh_policy (bool, optional) --

    When True, trigger a native in-process Group Policy refresh via userenv.dll after successfully writing Registry.pol.

    Note

    The refresh is asynchronous. This call signals the Group Policy service to begin processing; it returns before processing is complete. Registry values will reflect the updated policy only after the service finishes its refresh cycle. Use lgpo_reg.get_rsop_value to verify applied state.

    Default is False.

CLI Example:

# Using the name parameter in the definition
set_reg_pol_value:
  lgpo_reg.value_absent:
    - key: SOFTWARE\MyKey
    - name: MyValue
    - policy_class: Machine


# Using the name as the parameter and modifying the User policy
MyValue:
  lgpo_reg.value_absent:
    - key: SOFTWARE\MyKey
    - policy_class: User
salt.states.win_lgpo_reg.value_disabled(name, key, policy_class='Machine', write_registry=None, refresh_policy=False)#

Ensure a registry setting is disabled in the Registry.pol file.

Parameters:

  • key (str) -- The registry key path

  • 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

  • write_registry (bool, optional) --

    Controls whether the registry value is also deleted immediately after updating Registry.pol.

    • None (default): auto-detect. Skips the registry delete on Domain Controllers; deletes directly on all other machine types.

    • True: always delete from the registry (non-DC behaviour).

    • False: always skip the registry delete; the Group Policy engine will remove the value on the next refresh.

  • refresh_policy (bool, optional) --

    When True, trigger a native in-process Group Policy refresh via userenv.dll after successfully writing Registry.pol.

    Note

    The refresh is asynchronous. This call signals the Group Policy service to begin processing; it returns before processing is complete. Registry values will reflect the updated policy only after the service finishes its refresh cycle. Use lgpo_reg.get_rsop_value to verify applied state.

    Default is False.

CLI Example:

# Using the name parameter in the definition
set_reg_pol_value:
  lgpo_reg.value_disabled:
    - key: SOFTWARE\MyKey
    - name: MyValue
    - policy_class: Machine


# Using the name as the parameter and modifying the User policy
MyValue:
  lgpo_reg.value_disabled:
    - key: SOFTWARE\MyKey
    - policy_class: User
salt.states.win_lgpo_reg.value_present(name, key, v_data, v_type='REG_DWORD', policy_class='Machine', write_registry=None, refresh_policy=False)#

Ensure a registry setting is present in the Registry.pol file.

Parameters:

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

  • key (str) -- The registry key path

  • 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

  • write_registry (bool, optional) --

    Controls whether the value is also written to the live registry immediately after updating Registry.pol.

    • None (default): auto-detect. Skips the registry write on Domain Controllers where HKLM\\SOFTWARE\\Policies\\ is write-protected; writes directly on all other machine types.

    • True: always write to the registry (non-DC behaviour).

    • False: always skip the registry write; the Group Policy engine will commit the value on the next refresh.

  • refresh_policy (bool, optional) --

    When True, trigger a native in-process Group Policy refresh via userenv.dll after successfully writing Registry.pol.

    Note

    The refresh is asynchronous. This call signals the Group Policy service to begin processing; it returns before processing is complete. Registry values will reflect the updated policy only after the service finishes its refresh cycle. Use lgpo_reg.get_rsop_value to verify applied state.

    Default is False.

CLI Example:

# Using the name parameter in the definition
set_reg_pol_value:
  lgpo_reg.value_present:
    - key: SOFTWARE\MyKey
    - name: MyValue
    - v_type: REG_SZ
    - v_data: "some string data"
    - policy_class: Machine

# Using the name as the parameter and modifying the User policy
MyValue:
  lgpo_reg.value_present:
    - key: SOFTWARE\MyKey
    - v_type: REG_SZ
    - v_data: "some string data"
    - policy_class: User