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.
depends: |
|
---|
salt.modules.win_lgpo.
get
(policy_class=None, return_full_policy_names=True, hierarchical_return=False, adml_language=u'en-US', return_not_configured=False)¶Get a policy value
Parameters: |
|
---|---|
Returns: | A dictionary containing the policy values for the specified class |
Return type: |
CLI Example:
salt '*' lgpo.get machine return_full_policy_names=True
salt.modules.win_lgpo.
get_policy_info
(policy_name, policy_class, adml_language=u'en-US')¶Returns information about a specified policy
Parameters: | |
---|---|
Returns: | Information about the specified policy |
Return type: |
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=u'en-US')¶Set a local server policy.
Parameters: |
|
---|---|
Returns: | True is successful, otherwise False |
Return type: |
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=u'en-US')¶Set a single computer policy
Parameters: |
|
---|---|
Returns: | True if successful, otherwise False |
Return type: |
CLI Example:
salt '*' lgpo.set_computer_policy LockoutDuration 1440
salt.modules.win_lgpo.
set_user_policy
(name, setting, adml_language=u'en-US')¶Set a single user policy
Parameters: | |
---|---|
Returns: | True if successful, Otherwise False |
Return type: |
CLI Example:
salt '*' lgpo.set_user_policy "Control Panel\Display\Disable the Display Control Panel" Enabled