# salt.modules.win_lgpo

Manage Local Policy on Windows

This module allows configuring local group policy (i.e. `gpedit.msc`) on a Windows machine.

Added in version 2016.11.0.

Warning

Local Group Policy will always be superseded by Domain Group policy. If policies are configured with Local Group Policy that are also configured with Domain Group policy, the Domain Group policy will take precedence.

## Administrative Templates

Administrative template policies are dynamically read from ADMX/ADML files on the server.

## Windows Settings

Policies contained in the "Windows Settings" section of the `gpedit.msc` GUI are statically defined in this module. Each policy is configured for the section (Machine/User) in the module's _policy_info class. The `_policy_info` class contains a "policies" dict on how the module will configure the policy, where the policy resides in the GUI (for display purposes), data validation data, data transformation data, etc.

## Current known limitations

- At this time, start/shutdown scripts policies are displayed, but are not configurable.

- Not all "Security Settings" policies exist in the _policy_info class

depends:

  - pywin32 Python module

  - lxml

  - uuid

  - struct

  - salt.utils.win_reg

salt.modules.win_lgpo.clear_policy_cache()

  Clears the policy definitions and resource stored in `__context__`. They will be rebuilt the next time a policy is applied.

  CLI Example:

      salt '*' lgpo.clear_policy_cache

salt.modules.win_lgpo.get(policy_class=None, return_full_policy_names=True, hierarchical_return=False, adml_language='en-US', return_not_configured=False)

  Get a policy value

  Parameters:

    - policy_class (`str`, optional) --

      Some policies are both user and computer, by default all policies will be pulled, but this can be used to retrieve only a specific policy class User/USER/user = retrieve user policies Machine/MACHINE/machine/Computer/COMPUTER/computer = retrieve machine/computer policies.

      Default is `None`.

    - return_full_policy_names (`bool`, optional) --

      `True`/`False` to return the policy name as it is seen in the `gpedit.msc` GUI or to only return the policy key/id.

      Default is `True`.

    - hierarchical_return (`bool`, optional) --

      `True`/`False` to return the policy data in the hierarchy as seen in the `gpedit.msc` GUI. The default of False will return data split only into User/Computer configuration sections.

      Default is `False`.

    - adml_language (`str`, optional) --

      The ADML language to use for processing display/descriptive names and enumeration values of ADMX template data.

      Default is `en-US`.

    - return_not_configured (`bool`, optional) --

      Include Administrative Template policies that are 'Not Configured' in the return data.

      Default is `False`.

  Returns:

    A dictionary containing the policy values for the specified class

  Return type:

    dict

  CLI Example:

      salt '*' lgpo.get machine return_full_policy_names=True

salt.modules.win_lgpo.get_policy(policy_name, policy_class, adml_language='en-US', return_value_only=True, return_full_policy_names=True, hierarchical_return=False)

  Get the current settings for a single policy on the machine

  Parameters:

    - policy_name (str) -- The name of the policy to retrieve. Can be the any of the names or alieses returned by `lgpo.get_policy_info`

    - policy_class (str) -- The policy class. Must be one of `machine` or `user`

    - adml_language (`str`, optional) --

      The language code for the adml file to use for localization.

      Default is `en-US`.

    - return_value_only (`bool`, optional) --

      `True` will return only the value for the policy, without the name of the policy. `return_full_policy_names` and `hierarchical_return` will be ignored.

      Default is `True`

    - return_full_policy_names (`bool`, optional) --

      Returns the full policy name regardless of what was passed in `policy_name`.

      Note

      This setting applies to sub-elements of the policy if they exist. The value passed in `policy_name` will always be used as the policy name when this setting is `False`

      Default is `True`.

    - hierarchical_return (`bool`, optional) --

      Returns a hierarchical view of the policy showing its parents.

      Default is `False`.

  Returns:

    A dictionary containing the policy settings

  Return type:

    dict

  CLI Example:

      # Using the policy id
      salt * lgpo.get_policy LockoutDuration machine
      salt * lgpo.get_policy AutoUpdateCfg machine

      # Using the full name
      salt * lgpo.get_policy "Account lockout duration" machine
      salt * lgpo.get_policy "Configure Automatic Updates" machine

      # Using full path and name
      salt * lgpo.get_policy "Windows Components\Windows Update\Configure Automatic Updates" machine

salt.modules.win_lgpo.get_policy_info(policy_name, policy_class, adml_language='en-US')

  Returns information about a specified policy

  Parameters:

    - policy_name (str) -- The name of the policy to lookup

    - policy_class (str) -- The class of policy, i.e. machine, user, both

    - adml_language (`str`, optional) --

      The ADML language to use for Administrative Template data lookup.

      Default is `en-US`.

  Returns:

    Information about the specified policy

  Return type:

    dict

  CLI Example:

      salt '*' lgpo.get_policy_info 'Maximum password age' machine

  You can use `lgpo.get_policy_info` to get all the possible names that could be used in a state file or from the command line (along with elements that need to be set/etc). The key is to match the text you see in the `gpedit.msc` gui exactly, including quotes around words or phrases. The "full path" style is really only needed when there are multiple policies that use the same base name. For example, `Access data sources across domains` exists in ~10 different paths. If you put that through `get_policy_info` you'll get back a message that it is used for multiple policies and you need to be more specific.

  CLI Example:

      salt-call --local lgpo.get_policy_info ShellRemoveOrderPrints_2 machine

      local:
          ----------
          message:
          policy_aliases:
              - Turn off the "Order Prints" picture task
              - ShellRemoveOrderPrints_2
              - System\Internet Communication Management\Internet Communication settings\Turn off the "Order Prints" picture task
          policy_class:
              machine
          policy_elements:
          policy_found:
              True
          policy_name:
              ShellRemoveOrderPrints_2
          rights_assignment:
              False

  Escaping can get tricky in cmd/Powershell. The following is an example of escaping in Powershell using backquotes:

      PS>salt-call --local lgpo.get_policy_info "Turn off the `\`"Order Prints`\`" picture task" machine

      local:
          ----------
          message:
          policy_aliases:
              - Turn off the "Order Prints" picture task
              - ShellRemoveOrderPrints_2
              - System\Internet Communication Management\Internet Communication settings\Turn off the "Order Prints" picture task
          policy_class:
              machine
          policy_elements:
          policy_found:
              True
          policy_name:
              Turn off the "Order Prints" picture task
          rights_assignment:
              False

  This function can then be used to get the options available for specifying Group Policy Objects to be used in state files. Based on the above any of these should be usable:

      internet_communications_settings:
        lgpo.set:
          - computer_policy:
              Turn off the "Order Prints" picture task: Enabled

      internet_communications_settings:
        lgpo.set:
          - computer_policy:
              ShellRemoveOrderPrints_2: Enabled

  When using the full path, it might be a good idea to use single quotes around the path:

      internet_communications_settings:
        lgpo.set:
          - computer_policy:
              'System\Internet Communication Management\Internet Communication settings\Turn off the "Order Prints" picture task': 'Enabled'

  If you struggle to find the policy from `get_policy_info` using the name as you see in `gpedit.msc`, the names such as "ShellRemoveOrderPrints_2" come from the `.admx` files. If you know nothing about `.admx/.adml` relationships (ADML holds what you see in the GUI, ADMX holds the more technical details), then this may be a little bit too much info, but here is an example with the above policy using Powershell:

      PS>Get-ChildItem -Path C:\Windows\PolicyDefinitions -Recurse -Filter *.adml | Select-String "Order Prints"

      C:\windows\PolicyDefinitions\en-US\ICM.adml:152:      <string id="ShellRemoveOrderPrints">Turn off the "Order Prints" picture task</string>
      C:\windows\PolicyDefinitions\en-US\ICM.adml:153:      <string id="ShellRemoveOrderPrints_Help">This policy setting specifies whether the "Order Prints Online" task is available from Picture Tasks in Windows folders.
      C:\windows\PolicyDefinitions\en-US\ICM.adml:155:The Order Prints Online Wizard is used to download a list of providers and allow users to order prints online.
      C:\windows\PolicyDefinitions\en-US\ICM.adml:157:If you enable this policy setting, the task "Order Prints Online" is removed from Picture Tasks in File Explorer folders.

  From this grep, we can see id "ShellRemoveOrderPrints" is the ID of the string used to describe this policy, then we search for it in the ADMX:

      PS>Get-ChildItem -Path C:\Windows\PolicyDefinitions -Recurse -Filter *.admx | Select-String "ShellRemoveOrderPrints"

      C:\windows\PolicyDefinitions\ICM.admx:661:    <policy name="ShellRemoveOrderPrints_1" class="User" displayName="$(string.ShellRemoveOrderPrints)" explainText="$(string.ShellRemoveOrderPrints_Help)" key="Software\Microsoft\Windows\CurrentVersion\Policies\Explorer" valueName="NoOnlinePrintsWizard">
      C:\windows\PolicyDefinitions\ICM.admx:671:    <policy name="ShellRemoveOrderPrints_2" class="Machine" displayName="$(string.ShellRemoveOrderPrints)" explainText="$(string.ShellRemoveOrderPrints_Help)" key="Software\Microsoft\Windows\CurrentVersion\Policies\Explorer" valueName="NoOnlinePrintsWizard">

  Now we have two to pick from. And if you notice the `class="Machine"` and `class="User"` (which details if it is a computer policy or user policy respectively) the `ShellRemoveOrderPrints_2` is the "short name" we could use to pass through `get_policy_info` to see what the module itself is expecting.

salt.modules.win_lgpo.set_(computer_policy=None, user_policy=None, cumulative_rights_assignments=True, adml_language='en-US')

  Set a local server policy.

  Parameters:

    - computer_policy (`dict`, optional) --

      A dictionary of "policyname: value" pairs of computer policies to set. 'value' should be how it is displayed in the gpedit GUI, i.e. if a setting can be 'Enabled'/'Disabled', then that should be passed.

      Administrative Template data may require dicts within dicts to specify each element of the Administrative Template policy. Administrative Templates policies are always cumulative.

      Policy names can be specified in a number of ways based on the type of policy:

      > Windows Settings Policies:

      > > These policies can be specified using the GUI display name or the key name from the _policy_info class in this module. The GUI display name is also contained in the _policy_info class in this module.

      > Administrative Template Policies:

      > > These can be specified using the policy name as displayed in the GUI (case sensitive). Some policies have the same name, but a different location (for example, "Access data sources across domains"). These can be differentiated by the "path" in the GUI (for example, "Windows ComponentsInternet ExplorerInternet Control PanelSecurity PageInternet ZoneAccess data sources across domains").

      > > Additionally, policies can be specified using the "name" and "id" attributes from the ADMX files.

      > > For Administrative Templates that have policy elements, each element can be specified using the text string as seen in the GUI or using the ID attribute from the ADMX file. Due to the way some of the GUI text is laid out, some policy element names could include descriptive text that appears lbefore the policy element in the GUI.

      > > Use the get_policy_info function for the policy name to view the element ID/names that the module will accept.

      Default is `None`.

    - user_policy (`dict`, optional) --

      The same setup as the computer_policy, except with data to configure the local user policy.

      Default is `None`.

    - cumulative_rights_assignments (`bool`, optional) --

      Determine how user rights assignment policies are configured.

      If `True`, user right assignment specifications are simply added to the existing policy

      If `False`, only the users specified will get the right (any existing will have the right revoked)

      Default is `True`.

    - adml_language (`str`, optional) --

      The language files to use for looking up Administrative Template policy data (i.e. how the policy is displayed in the GUI).

      Default is `en-US`.

  Returns:

    `True` is successful, otherwise `False`.

  Return type:

    bool

  CLI Example:

      salt '*' lgpo.set computer_policy='{"LockoutDuration": 2, "RestrictAnonymous": "Enabled", "AuditProcessTracking": "Succes, Failure"}'

salt.modules.win_lgpo.set_computer_policy(name, setting, cumulative_rights_assignments=True, adml_language='en-US')

  Set a single computer policy

  Parameters:

    - name (str) -- The name of the policy to configure

    - setting (str) -- The setting to configure the named policy with

    - cumulative_rights_assignments (`bool`, optional) --

      Determine how user rights assignment policies are configured. If `True`, user right assignment specifications are simply added to the existing policy. If `False`, only the users specified will get the right (any existing will have the right revoked)

      Default is `True`.

    - adml_language (`str`, optional) --

      The language files to use for looking up Administrative Template policy data (i.e. how the policy is displayed in the GUI).

      Default is `en-US`.

  Returns:

    `True` if successful, otherwise `False`.

  Return type:

    bool

  CLI Example:

      salt '*' lgpo.set_computer_policy LockoutDuration 1440

salt.modules.win_lgpo.set_user_policy(name, setting, adml_language='en-US')

  Set a single user policy

  Parameters:

    - name (str) -- The name of the policy to configure

    - setting (str) -- The setting to configure the named policy with

    - adml_language (`str`, optional) --

      The language files to use for looking up Administrative Template policy data (i.e. how the policy is displayed in the GUI).

      Default is `en-US`.

  Returns:

    True if successful, Otherwise False

  Return type:

    bool

  CLI Example:

      salt '*' lgpo.set_user_policy "Control Panel\Display\Disable the Display Control Panel" Enabled