salt.modules.win_lgpo¶

Manage Local Policy on Windows

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

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) -- 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

• return_full_policy_names (bool) -- True/False to return the policy name as it is seen in the gpedit.msc GUI or to only return the policy key/id.

• hierarchical_return (bool) -- 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

• adml_language (str) -- The ADML language to use for processing display/descriptive names and enumeration values of ADMX template data, defaults to en-US

• return_not_configured (bool) -- Include Administrative Template policies that are 'Not Configured' in the return data

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) -- The language code for the adml file to use for localization. The default is en-US

• return_value_only (bool) -- 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) --

  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

• hierarchical_return (bool) -- Returns a hierarchical view of the policy showing its parents

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) -- The ADML language to use for Administrative Template data lookup

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) --

  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.

• user_policy (dict) -- The same setup as the computer_policy, except with data to configure the local user policy.

• cumulative_rights_assignments (bool) --

  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)

• adml_language (str) -- The language files to use for looking up Administrative Template policy data (i.e. how the policy is displayed in the GUI). Defaults to 'en-US' (U.S. English).

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) -- 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)

• adml_language (str) -- The language files to use for looking up Administrative Template policy data (i.e. how the policy is displayed in the GUI). Defaults to 'en-US' (U.S. English).

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) -- The language files to use for looking up Administrative Template policy data (i.e. how the policy is displayed in the GUI). Defaults to 'en-US' (U.S. English).

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