Manage Local Policy on Windows
This module allows configuring local group policy (i.e. gpedit.msc
) on a
Windows server.
New in version 2016.11.0.
Administrative template policies are dynamically read from ADMX/ADML files on the server.
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.
At this time, start/shutdown scripts policies are displayed, but are not configurable.
Not all "Security Settings" policies exist in the _policy_info class
pywin32 Python module
lxml
uuid
struct
salt.utils.win_reg
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
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
A dictionary containing the policy values for the specified class
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
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
A dictionary containing the policy settings
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
Information about the specified policy
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.
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).
True is successful, otherwise False
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
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).
True if successful, otherwise False
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
True if successful, Otherwise False
CLI Example:
salt '*' lgpo.set_user_policy "Control Panel\Display\Disable the Display Control Panel" Enabled