# salt.modules.win_lgpo_reg

## LGPO - Registry.pol

Added 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`, optional) --

      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`, optional) --

      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`, optional) --

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

      - Computer

      - Machine

      - User

      Default is `Machine`.

  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`, optional) --

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

      - Computer

      - Machine

      - User

      Default is `Machine`.

  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`, optional) --

    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`, optional) --

      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`, optional) --

      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`, optional) --

      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'}}"