neulab/tldr huggingface dataset:
If set to True the guest will stop instead of rebooting.  This is specially useful when creating a virtual machine with an installation cdrom or an autoinstallation needing a special first boot configuration.  Defaults to False
Make sure an already-defined virtual machine called domain_name is running:
domain_name: virt.running
Do the same, but define the virtual machine if needed:
domain_name: virt.running: - cpu: 2 - mem: 2048 - disk_profile: prod - boot_dev: network hd - disks: - name: system size: 8192 overlay_image: True pool: default image: /path/to/image.qcow2 - name: data size: 16834 - nic_profile: prod - interfaces: - name: eth0 mac: 01:23:45:67:89:AB - name: eth1 type: network source: admin - graphics: type: spice listen: type: address address: 192.168.0.125
salt.states.virt.saved(name, suffix=None) Deprecated since version 2016.3.0: Use snapshot() instead.
Takes a snapshot of a particular VM or by a UNIX-style wildcard.
domain_name: virt.saved: - suffix: periodic
domain*: virt.saved: - suffix: periodic
salt.states.virt.snapshot(name, suffix=None, connection=None, username=None, password=None) Takes a snapshot of a particular VM or by a UNIX-style wildcard.
domain_name: virt.snapshot: - suffix: periodic
domain*: virt.snapshot: - suffix: periodic
salt.states.virt.stopped(name, connection=None, username=None, password=None) Stops a VM by shutting it down nicely.
salt.states.virt.unpowered(name) Deprecated since version 2016.3.0: Use powered_off() instead.
Stops a VM by power off.
salt.states.virt.volume_defined(pool, name, size, allocation=0, format=None, type=None, permissions=None, backing_store=None, nocow=False, connection=None, username=None, password=None) Ensure a disk volume is existing.
• pool -- name of the pool containing the volume
• name -- name of the volume
• permissions -- Permissions to set on the target folder. This is mostly used for filesystem-based pool types. See pool-define-permissions for more details on this structure.
esx_volume: virt.volume_defined: - pool: "[local-storage]" - name: myvm/myvm.vmdk - size: 8192
myvolume: virt.volume_defined: - pool: default - name: myvm.qcow2 - format: qcow2 - size: 8192 - permissions: mode: '0775' owner: '123' group: '345' - backing_store: path: /path/to/base.img format: raw - nocow: True
salt.states.virtualenv Setup of Python virtualenv sandboxes.
salt.states.virtualenv_mod.manage(name, venv_bin=None, requirements=None, system_site_packages=False, distribute=False, use_wheel=False, clear=False, python=None, extra_search_dir=None, never_download=None, prompt=None, user=None, cwd=None, index_url=None, extra_index_url=None, pre_releases=False, no_deps=False, pip_download=None, pip_download_cache=None, pip_exists_action=None, pip_ignore_installed=False, proxy=None, use_vt=False, env_vars=None, no_use_wheel=False, pip_upgrade=False, pip_pkgs=None, pip_no_cache_dir=False, pip_cache_dir=None, process_dependency_links=False, no_binary=None, **kwargs) This function is an alias of managed. Create a virtualenv and optionally manage it with pip
name   Path to the virtualenv.
venv_bin: virtualenv The name (and optionally path) of the virtualenv command. This can also be set globally in the minion config file as virtualenv.venv_bin.
requirements: None Path to a pip requirements file. If the path begins with salt:// the file will be transferred from the master file server.
use_wheel: False Prefer wheel archives (requires pip >= 1.4).
python: None Python executable used to build the virtualenv
user: None The user under which to run virtualenv and pip.
cwd: None Path to the working directory where pip install is executed.
no_deps: False Pass --no-deps to pip install.
pip_exists_action: None Default action of pip when a path already exists: (s)witch, (i)gnore, (w)ipe, (b)ackup.
proxy: None Proxy address which is passed to pip install.
env_vars: None Set environment variables that some builds will depend on. For example, a Python C-module may have a Makefile that needs INCLUDE_PATH set to pick up a header file while compiling.
no_use_wheel: False Force to not use wheel archives (requires pip>=1.4)
pip_upgrade: False Pass --upgrade to pip install.
pip_pkgs: None As an alternative to requirements, pass a list of pip packages that should be installed.
process_dependency_links: False Run pip install with the --process_dependency_links flag.
Also accepts any kwargs that the virtualenv module will. However, some kwargs, such as the pip option, require - distribute: True.
/var/www/myvirtualenv.com: virtualenv.managed: - system_site_packages: False - requirements: salt://REQUIREMENTS.txt - env_vars: PATH_VAR: '/usr/local/bin/'
salt.states.virtualenv_mod.managed(name, venv_bin=None, requirements=None, system_site_packages=False, distribute=False, use_wheel=False, clear=False, python=None, extra_search_dir=None, never_download=None, prompt=None, user=None, cwd=None, index_url=None, extra_index_url=None, pre_releases=False, no_deps=False, pip_download=None, pip_download_cache=None, pip_exists_action=None, pip_ignore_installed=False, proxy=None, use_vt=False, env_vars=None, no_use_wheel=False, pip_upgrade=False, pip_pkgs=None, pip_no_cache_dir=False, pip_cache_dir=None, process_dependency_links=False, no_binary=None, **kwargs) Create a virtualenv and optionally manage it with pip
salt.states.webutil Support for htpasswd module. Requires the apache2-utils package for Debian-based distros.
username: webutil.user_exists: - password: secr3t - htpasswd_file: /etc/nginx/htpasswd - options: d - force: true
salt.states.webutil.user_absent(name, htpasswd_file=None, runas=None) Make sure the user is not in the specified htpasswd file
htpasswd_file Path to the htpasswd file
salt.states.webutil.user_exists(name, password=None, htpasswd_file=None, options='', force=False, runas=None, update=False) Make sure the user is inside the specified htpasswd file
options See salt.modules.htpasswd.useradd
force  Touch the file even if user already created
update Update an existing user's password if it's different from what's in the htpasswd file (unlike force, which updates regardless)
salt.states.win_certutil Installing of certificates to the Windows Certificate Manager Install certificates to the Windows Certificate Manager
salt://certs/cert.cer: certutil.add_store: - store: TrustedPublisher
salt.states.win_certutil.add_store(name, store, saltenv='base') Store a certificate to the given store
name   The certificate to store, this can use local paths or salt:// paths
store  The store to add the certificate to
saltenv The salt environment to use, this is ignored if a local path is specified
salt.states.win_certutil.del_store(name, store, saltenv='base') Remove a certificate in the given store
name   The certificate to remove, this can use local paths or salt:// paths
store  The store to remove the certificate from
salt.states.win_dacl Windows Object Access Control Lists
Ensure an ACL is present
parameters: name - the path of the object objectType - Registry/File/Directory user - user account or SID for the ace permission - permission for the ace (see module win_acl for available permissions for each objectType) acetype - Allow/Deny propagation - how the ACL should apply to child objects (see module win_acl for available propagation types)
addAcl: win_dacl.present: - name: HKEY_LOCAL_MACHINE\SOFTWARE\mykey - objectType: Registry - user: FakeUser - permission: FullControl - acetype: ALLOW - propagation: KEY&SUBKEYS
Ensure an ACL does not exist
removeAcl: win_dacl.absent: - name: HKEY_LOCAL_MACHINE\SOFTWARE\mykey - objectType: Registry - user: FakeUser - permission: FulLControl - acetype: ALLOW - propagation: KEY&SUBKEYS
Ensure an object is inheriting permissions
parameters: name - the path of the object objectType - Registry/File/Directory clear_existing_acl - True/False - when inheritance is enabled, should the existing ACL be kept or cleared out
eInherit: win_dacl.enableinheritance: - name: HKEY_LOCAL_MACHINE\SOFTWARE\mykey - objectType: Registry - clear_existing_acl: True
Ensure an object is not inheriting permissions
parameters: name - the path of the object objectType - Registry/File/Directory copy_inherited_acl - True/False - if inheritance is enabled, should the inherited permissions be copied to the ACL when inheritance is disabled
dInherit: win_dacl.disableinheritance: - name: HKEY_LOCAL_MACHINE\SOFTWARE\mykey - objectType: Registry - copy_inherited_acl: False
salt.states.win_dacl.absent(name, objectType, user, permission, acetype, propagation) Ensure an ACL does not exist
salt.states.win_dacl.disinherit(name, objectType, copy_inherited_acl=True) Ensure an object is not inheriting ACLs from its parent
salt.states.win_dacl.inherit(name, objectType, clear_existing_acl=False) Ensure an object is inheriting ACLs from its parent
salt.states.win_dacl.present(name, objectType, user, permission, acetype, propagation) Ensure an ACE is present
salt.states.win_dism Installing of Windows features using DISM Install windows features/capabilties with DISM
Language.Basic~~~en-US~0.0.1.0: dism.capability_installed
NetFx3: dism.feature_installed
salt.states.win_dism.capability_installed(name, source=None, limit_access=False, image=None, restart=False) Install a DISM capability
• name (str) -- The capability to install
• source (str) -- The optional source of the capability
• limit_access (bool) -- Prevent DISM from contacting Windows Update for online images
Run dism.available_capabilities to get a list of available capabilities. This will help you get the proper name to use.
install_dotnet35: dism.capability_installed: - name: NetFX3~~~~
salt.states.win_dism.capability_removed(name, image=None, restart=False) Uninstall a DISM capability
• name (str) -- The capability to uninstall
Run dism.installed_capabilities to get a list of installed capabilities. This will help you get the proper name to use.
remove_dotnet35: dism.capability_removed: - name: NetFX3~~~~
salt.states.win_dism.feature_installed(name, package=None, source=None, limit_access=False, enable_parent=False, image=None, restart=False) Install a DISM feature
• name (str) -- The feature in which to install
• source (str) -- The optional source of the feature
Run dism.available_features to get a list of available features. This will help you get the proper name to use.
install_telnet_client: dism.feature_installed: - name: TelnetClient
salt.states.win_dism.feature_removed(name, remove_payload=False, image=None, restart=False) Disables a feature.
• name (str) -- The feature to disable
Run dism.installed_features to get a list of installed features. This will help you get the proper name to use.
remove_telnet_client: dism.feature_removed: - name: TelnetClient - remove_payload: True
salt.states.win_dism.package_installed(name, ignore_check=False, prevent_pending=False, image=None, restart=False) Install a package.
• name (str) -- The package to install. Can be a .cab file, a .msu file, or a folder
install_KB123123123: dism.package_installed: - name: C:\Packages\KB123123123.cab
salt.states.win_dism.package_removed(name, image=None, restart=False) Uninstall a package
• name (str) -- The full path to the package. Can be either a .cab file or a folder. Should point to the original source of the package, not to where the file is installed. This can also be the name of a package as listed in dism.installed_packages
# Example using source remove_KB1231231: dism.package_installed: - name: C:\Packages\KB1231231.cab
# Example using name from ``dism.installed_packages`` remove_KB1231231: dism.package_installed: - name: Package_for_KB1231231~31bf3856ad364e35~amd64~~10.0.1.3
salt.states.win_dns_client Module for configuring DNS Client on Windows systems
salt.states.win_dns_client.dns_dhcp(name, interface='Local Area Connection') Configure the DNS server list from DHCP Server
salt.states.win_dns_client.dns_exists(name, servers=None, interface='Local Area Connection', replace=False) Configure the DNS server list in the specified interface
config_dns_servers: win_dns_client.dns_exists: - replace: True #remove any servers not in the "servers" list, default is False - servers: - 8.8.8.8 - 8.8.8.9
salt.states.win_dns_client.primary_suffix(name, suffix=None, updates=False) New in version 2014.7.0.
Configure the global primary DNS suffix of a DHCP client.
suffix None The suffix which is advertised for this client when acquiring a DHCP lease When none is set, the explicitly configured DNS suffix will be removed.
updates False Allow syncing the DNS suffix with the AD domain when the client's AD domain membership changes
primary_dns_suffix: win_dns_client.primary_suffix: - suffix: sub.domain.tld - updates: True
salt.states.win_firewall State for configuring Windows Firewall
salt.states.win_firewall.add_rule(name, localport, protocol='tcp', action='allow', dir='in', remoteip='any') Add a new inbound or outbound rule to the firewall policy
open_smb_port: win_firewall.add_rule: - name: SMB (445) - localport: 445 - protocol: tcp - action: allow
salt.states.win_firewall.disabled(name='allprofiles') Disable all the firewall profiles (Windows only)
# To disable the domain profile disable_domain: win_firewall.disabled: - name: domainprofile
# To disable all profiles disable_all: win_firewall.disabled: - name: allprofiles
salt.states.win_firewall.enabled(name='allprofiles') Enable all the firewall profiles (Windows only)
# To enable the domain profile enable_domain: win_firewall.enabled: - name: domainprofile
# To enable all profiles enable_all: win_firewall.enabled: - name: allprofiles
salt.states.win_iis Microsoft IIS site management
This module provides the ability to add/remove websites and application pools from Microsoft IIS.
salt.states.win_iis.container_setting(name, container, settings=None) Set the value of the setting for an IIS container.
• settings (str) -- A dictionary of the setting names and their values.  Example of usage for the AppPools container:
site0-apppool-setting: win_iis.container_setting: - name: site0 - container: AppPools - settings: managedPipelineMode: Integrated processModel.maxProcesses: 1 processModel.userName: TestUser processModel.password: TestPassword processModel.identityType: SpecificUser
Example of usage for the Sites container:
site0-site-setting: win_iis.container_setting: - name: site0 - container: Sites - settings: logFile.logFormat: W3C logFile.period: Daily limits.maxUrlSegments: 32
salt.states.win_iis.create_app(name, site, sourcepath, apppool=None) Create an IIS application.
site0-v1-app: win_iis.create_app: - name: v1 - site: site0 - sourcepath: C:\inetpub\site0\v1
site0-v1-app: win_iis.create_app: - name: v1 - site: site0 - sourcepath: C:\inetpub\site0\v1 - apppool: site0
salt.states.win_iis.create_apppool(name) Create an IIS application pool.
site0-apppool: win_iis.create_apppool: - name: site0
salt.states.win_iis.create_binding(name, site, hostheader='', ipaddress='*', port=80, protocol='http', sslflags=0) Create an IIS binding.
• port (str) -- The TCP port of the binding.
site0-https-binding: win_iis.create_binding: - site: site0
site0-https-binding: win_iis.create_binding: - site: site0 - hostheader: site0.local - ipaddress: '*' - port: 443 - protocol: https - sslflags: 0
salt.states.win_iis.create_cert_binding(name, site, hostheader='', ipaddress='*', port=443, sslflags=0) Assign a certificate to an IIS binding.
• sslflags (str) -- Flags representing certificate type and certificate storage of the binding.
site0-cert-binding: win_iis.create_cert_binding: - name: 9988776655443322111000AAABBBCCCDDDEEEFFF - site: site0
site0-cert-binding: win_iis.create_cert_binding: - name: 9988776655443322111000AAABBBCCCDDDEEEFFF - site: site0 - hostheader: site0.local - ipaddress: 192.168.1.199 - port: 443 - sslflags: 1
salt.states.win_iis.create_vdir(name, site, sourcepath, app='/') Create an IIS virtual directory.
site0-foo-vdir: win_iis.create_vdir: - name: foo - site: site0 - sourcepath: C:\inetpub\vdirs\foo
site0-foo-vdir: win_iis.create_vdir: - name: foo - site: site0 - sourcepath: C:\inetpub\vdirs\foo - app: v1
salt.states.win_iis.deployed(name, sourcepath, apppool='', hostheader='', ipaddress='*', port=80, protocol='http') Ensure the website has been deployed.
Example of usage with only the required arguments. This will default to using the default application pool assigned by IIS:
site0-deployed: win_iis.deployed: - name: site0 - sourcepath: C:\inetpub\site0
site0-deployed: win_iis.deployed: - name: site0 - sourcepath: C:\inetpub\site0 - apppool: site0 - hostheader: site0.local - ipaddress: '*' - port: 443 - protocol: https
salt.states.win_iis.remove_app(name, site) Remove an IIS application.
site0-v1-app-remove: win_iis.remove_app: - name: v1 - site: site0
salt.states.win_iis.remove_apppool(name) Remove an IIS application pool.
defaultapppool-remove: win_iis.remove_apppool: - name: DefaultAppPool
salt.states.win_iis.remove_binding(name, site, hostheader='', ipaddress='*', port=80) Remove an IIS binding.
site0-https-binding-remove: win_iis.remove_binding: - site: site0
site0-https-binding-remove: win_iis.remove_binding: - site: site0 - hostheader: site0.local - ipaddress: '*' - port: 443
salt.states.win_iis.remove_cert_binding(name, site, hostheader='', ipaddress='*', port=443) Remove a certificate from an IIS binding.
site0-cert-binding-remove: win_iis.remove_cert_binding: - name: 9988776655443322111000AAABBBCCCDDDEEEFFF - site: site0
site0-cert-binding-remove: win_iis.remove_cert_binding: - name: 9988776655443322111000AAABBBCCCDDDEEEFFF - site: site0 - hostheader: site0.local - ipaddress: 192.168.1.199 - port: 443
salt.states.win_iis.remove_site(name) Delete a website from IIS.
defaultwebsite-remove: win_iis.remove_site: - name: Default Web Site
salt.states.win_iis.remove_vdir(name, site, app='/') Remove an IIS virtual directory.
site0-foo-vdir-remove: win_iis.remove_vdir: - name: foo - site: site0
site0-foo-vdir-remove: win_iis.remove_vdir: - name: foo - site: site0 - app: v1
salt.states.win_iis.set_app(name, site, settings=None) New in version 2017.7.0.
Set the value of the setting for an IIS web application.
NOTE: This function only configures existing app. Params are case sensitive.
Available settings:
• physicalPath - The physical path of the webapp
• applicationPool - The application pool for the webapp
• userName "connectAs" user
• password "connectAs" password for user
Example of usage:
site0-webapp-setting: win_iis.set_app: - name: app0 - site: Default Web Site - settings: userName: domain\\user password: pass physicalPath: c:\inetpub\wwwroot applicationPool: appPool0
salt.states.win_iis.webconfiguration_settings(name, settings=None) Set the value of webconfiguration settings.
• name (str) -- The name of the IIS PSPath containing the settings.  Possible PSPaths are : MACHINE, MACHINE/WEBROOT, IIS:, IIS:Sitessitename, ...
• settings (dict) -- Dictionaries of dictionaries.  You can match a specific item in a collection with this syntax inside a key: 'Collection[{name: site0}].logFile.directory'
Example of usage for the MACHINE/WEBROOT PSPath:
MACHINE-WEBROOT-level-security: win_iis.webconfiguration_settings: - name: 'MACHINE/WEBROOT' - settings: system.web/authentication/forms: requireSSL: True protection: "All" credentials.passwordFormat: "SHA1" system.web/httpCookies: httpOnlyCookies: True
Example of usage for the IIS:\Sites\site0 PSPath:
site0-IIS-Sites-level-security: win_iis.webconfiguration_settings: - name: 'IIS:\Sites\site0' - settings: system.webServer/httpErrors: errorMode: "DetailedLocalOnly" system.webServer/security/requestFiltering: allowDoubleEscaping: False verbs.Collection: - verb: TRACE allowed: False fileExtensions.allowUnlisted: False
Example of usage for the IIS:\ PSPath with a collection matching:
site0-IIS-level-security: win_iis.webconfiguration_settings: - name: 'IIS:\' - settings: system.applicationHost/sites: 'Collection[{name: site0}].logFile.directory': 'C:\logs\iis\site0'
salt.states.win_lgpo Manage Windows Local Group Policy New in version 2016.11.0.
This state module allows you to configure local Group Policy on Windows. You can ensure the setting of a single policy or multiple policies in one pass.
Single policies must specify the policy name, the setting, and the policy class (Machine/User/Both). Here are some examples for setting a single policy setting.
Example single policy configuration:
Ensure Account Lockout Duration: lgpo.set: - name: Account lockout duration - setting: 90 - policy_class: Machine
Example using abbreviated form:
Account lockout duration: lgpo.set: - setting: 120 - policy_class: Machine
It is also possible to set multiple policies in a single state. This is done by setting the settings under either computer_policy or user_policy. Here are some examples for setting multiple policy settings in a single state.
Multiple policy configuration
Company Local Group Policy: lgpo.set: - computer_policy: Deny log on locally: - Guest Account lockout duration: 120 Account lockout threshold: 10 Reset account lockout counter after: 120 Enforce password history: 24 Maximum password age: 60 Minimum password age: 1 Minimum password length: 14 Password must meet complexity requirements: Enabled Store passwords using reversible encryption: Disabled Configure Automatic Updates: Configure automatic updating: 4 - Auto download and schedule the intsall Scheduled install day: 7 - Every Saturday Scheduled install time: 17:00 Specify intranet Microsoft update service location: Set the intranet update service for detecting updates: http://mywsus Set the intranet statistics server: http://mywsus - user_policy: Do not process the legacy run list: Enabled
server_policy: lgpo.set: - computer_policy: Maximum password age: 60 Minimum password age: 1 Minimum password length: 14 Account lockout duration: 120 Account lockout threshold: 10 Reset account lockout counter after: 120 Manage auditing and security log: - "BUILTIN\\Administrators" Replace a process level token: - "NT AUTHORITY\\NETWORK SERVICE" - "NT AUTHORITY\\LOCAL SERVICE" "Accounts: Guest account status": Disabled "Accounts: Rename guest account": Not_4_U "Audit: Audit the use of Backup and Restore privilege": Enabled "Interactive logon: Do not display last user name": Enabled "Network\\DNS Client\\Dynamic update": Disabled "System\\Logon\\Do not display the Getting Started welcome screen at logon": Enabled "Windows Components\\Remote Desktop Services\\Remote Desktop Session Host\\Connections\\Select RDP transport protocols": "Select Transport Type": "Use both UDP and TCP" "Windows Components\\Windows Update\\Allow Automatic Updates immediate installation": Enabled "Windows Components\\Windows Update\\Allow non-administrators to receive update notifications": Disabled "Windows Components\\Windows Update\\Always automatically restart at the scheduled time": "The restart timer will give users this much time to save their work (minutes)": 15 "Windows Components\\Windows Update\\Automatic Updates detection frequency": "Check for updates at the following interval (hours)": 1 "Windows Components\\Windows Update\\Configure Automatic Updates": "Configure automatic updating": 4 - Auto download and schedule the install "Install during automatic maintenance": False "Scheduled install day": 7 - Every Saturday "Scheduled install time": "17:00" "Windows Components\\Windows Update\\Delay Restart for scheduled installations": "Wait the following period before proceeding with a scheduled restart (minutes)": 1 "Windows Components\\Windows Update\\No auto-restart with logged on users for scheduled automatic updates installations": Disabled "Windows Components\\Windows Update\\Re-prompt for restart with scheduled installations": "Wait the following period before prompting again with a scheduled restart (minutes)": 30 "Windows Components\\Windows Update\\Reschedule Automatic Updates scheduled installations": Disabled "Windows Components\\Windows Update\\Specify intranet Microsoft update service location": "Set the intranet update service for detecting updates": http://mywsus "Set the intranet statistics server": http://mywsus - cumulative_rights_assignments: True
Some policy settings can't be set on their own an require that other policy settings are set at the same time. It can be difficult to figure out what additional settings need to be applied. The easiest way to do this is to modify the setting manually using the Group Policy Editor (`gpedit.msc`) on the machine. Then `get` the policy settings configured on that machine. Use the following command:
salt-call --local lgpo.get machine
For example, if I want to set the Windows Update settings for a Windows Server 2016 machine I would go into the Group Policy Editor (`gpedit.msc`) and configure the group policy. That policy can be found at: Computer Configuration -> Administrative Templates -> Windows Components -> Windows Update -> Configure Automatic Updates. You have the option to "Enable" the policy and set some configuration options. In this example, just click "Enable" and accept the default configuration options. Click "OK" to apply the setting.
Now run the `get` command as shown above. You will find the following in the minion return:
Windows Components\Windows Update\Configure Automatic Updates: ---------- Configure automatic updating: 3 - Auto download and notify for install Install during automatic maintenance: False Install updates for other Microsoft products: False Scheduled install day: 0 - Every day Scheduled install time: 03:00
This shows you that to enable the "Configure Automatic Updates" policy you also have to configure the following settings:
- Configure automatic updating - Install during automatic maintenance - Install updates for other Microsoft products - Scheduled install day - Scheduled install time
So, if you were writing a state for the above policy, it would look like this:
configure_windows_update_settings: lgpo.set: - computer_policy: Configure Automatic Updates: Configure automatic updating: 3 - Auto download and notify for install Install during automatic maintenance: False Install updates for other Microsoft products: False Scheduled install day: 0 - Every day Scheduled install time: 03:00
It is important that you put names of policies and settings exactly as they are displayed in the return. That includes capitalization and punctuation such as periods, dashes, etc. This rule applies to both the setting name and the setting value.
.. warning::
From time to time Microsoft updates the Administrative templates on the machine. This can cause the policy name to change or the list of settings that must be applied at the same time. These settings often change between versions of Windows as well. For example, Windows Server 2019 allows you to also specify a specific week of the month to apply the update.
Another thing note is the long policy name returned by the `get` function:
Windows Components\Windows Update\Configure Automatic Updates:
When we wrote the state for this policy we only used the final portion of the policy name, `Configure Automatic Updates`. This usually works fine, but if you are having problems, you may try the long policy name.
When writing the long name in a state file either wrap the name in single quotes to make yaml see it as raw data, or escape the back slashes.
'Windows Components\Windows Update\Configure Automatic Updates:'
Windows Components\\Windows Update\\Configure Automatic Updates:
salt.states.win_lgpo.set_(name, setting=None, policy_class=None, computer_policy=None, user_policy=None, cumulative_rights_assignments=True, adml_language='en-US') Ensure the specified policy is set.
WARNING: The setting argument cannot be used in conjunction with the computer_policy or user_policy arguments
• name (str) -- The name of a single policy to configure
• setting (str, dict, list) -- The configuration setting for the single named policy. If this argument is used the computer_policy / user_policy arguments will be ignored
• policy_class (str) -- The policy class of the single named policy to configure. This can machine, user, or both
• computer_policy (dict) -- A dictionary of containing the policy name and key/value pairs of a set of computer policies to configure. If this argument is used, the name / policy_class arguments will be ignored
• user_policy (dict) -- A dictionary of containing the policy name and key/value pairs of a set of user policies to configure. If this argument is used, the name / policy_class arguments will be ignored
• cumulative_rights_assignments (bool) -- If user rights assignments are being configured, determines if any user right assignment policies specified will be cumulative or explicit
• adml_language (str) -- The adml language to use for AMDX policy data/display conversions.  Default is en-US
salt.states.win_license Installation and activation of windows licenses Install and activate windows licenses
XXXXX-XXXXX-XXXXX-XXXXX-XXXXX: license.activate
salt.states.win_license.activate(name) Install and activate the given product key
name   The 5x5 product key given to you by Microsoft
salt.states.win_network Configuration of network interfaces on Windows hosts New in version 2014.1.0.
This module provides the network state(s) on Windows hosts. DNS servers, IP addresses and default gateways can currently be managed.
Below is an example of the configuration for an interface that uses DHCP for both DNS servers and IP addresses:
Local Area Connection #2: network.managed: - dns_proto: dhcp - ip_proto: dhcp
NOTE: Both the dns_proto and ip_proto arguments are required.
Static DNS and IP addresses can be configured like so:
Local Area Connection #2: network.managed: - dns_proto: static - dns_servers: - 8.8.8.8 - 8.8.4.4 - ip_proto: static - ip_addrs: - 10.2.3.4/24
NOTE: IP addresses are specified using the format <ip-address>/<subnet-length>. Salt provides a convenience function called ip.get_subnet_length to calculate the subnet length from a netmask.
Optionally, if you are setting a static IP address, you can also specify the default gateway using the gateway parameter:
Local Area Connection #2: network.managed: - dns_proto: static - dns_servers: - 8.8.8.8 - 8.8.4.4 - ip_proto: static - ip_addrs: - 10.2.3.4/24 - gateway: 10.2.3.1
salt.states.win_network.managed(name, dns_proto=None, dns_servers=None, ip_proto=None, ip_addrs=None, gateway=None, enabled=True, **kwargs) Ensure that the named interface is configured properly.
• name (str) -- The name of the interface to manage
• dns_proto (str) -- None Set to static and use the dns_servers parameter to provide a list of DNS nameservers. set to dhcp to use DHCP to get the DNS servers.
• dns_servers (list) -- None A list of static DNS servers. To clear the list of DNS servers pass an empty list ([]). None will make no changes.
• ip_proto (str) -- None Set to static and use the ip_addrs and (optionally) gateway parameters to provide a list of static IP addresses and the default gateway. Set to dhcp to use DHCP.
• ip_addrs (list) -- None A list of static IP addresses with netmask flag, ie: 192.168.0.11/24
• gateway (str) -- None The gateway to set for the interface
• enabled (bool) -- True Set to False to ensure that this interface is disabled.
Returns A dictionary of old and new settings
Ethernet1: network.managed: - dns_proto: static - dns_servers: - 8.8.8.8 - 8.8.8.4 - ip_proto: static - ip_addrs: - 192.168.0.100/24
Clear DNS entries example:
Ethernet1: network.managed: - dns_proto: static - dns_servers: [] - ip_proto: dhcp
salt.states.win_path Manage the Windows System PATH
salt.states.win_path.absent(name) Remove the directory from the SYSTEM path
'C:\sysinternals': win_path.absent
salt.states.win_path.exists(name, index=None) Add the directory to the system PATH at index location
index  Position where the directory should be placed in the PATH. This is 0-indexed, so 0 means to prepend at the very start of the PATH.
NOTE: If the index is not specified, and the directory needs to be added to the PATH, then the directory will be appended to the PATH, and this state will not enforce its location within the PATH.
'C:\python27': win_path.exists
'C:\sysinternals': win_path.exists: - index: 0
'C:\mystuff': win_path.exists: - index: -1
salt.states.win_pki Microsoft certificate management via the Pki PowerShell module.
salt.states.win_pki.import_cert(name, cert_format='cer', context='LocalMachine', store='My', exportable=True, password='', saltenv='base') Import the certificate file into the given certificate store.
• password (str) -- The password of the certificate. Only applicable to pfx format.
site0-cert-imported: win_pki.import_cert: - name: salt://win/webserver/certs/site0.cer
site0-cert-imported: win_pki.import_cert: - name: salt://win/webserver/certs/site0.pfx - cert_format: pfx - context: LocalMachine - store: My - exportable: True - password: TestPassword - saltenv: base
salt.states.win_pki.remove_cert(name, thumbprint, context='LocalMachine', store='My') Remove the certificate from the given certificate store.
site0-cert-removed: win_pki.remove_cert: - thumbprint: 9988776655443322111000AAABBBCCCDDDEEEFFF
site0-cert-removed: win_pki.remove_cert: - thumbprint: 9988776655443322111000AAABBBCCCDDDEEEFFF - context: LocalMachine - store: My
salt.states.win_powercfg This module allows you to control the power settings of a windows minion via powercfg.
# Set timeout to 30 minutes on battery power monitor: powercfg.set_timeout: - value: 30 - power: dc
salt.states.win_powercfg.set_timeout(name, value, power='ac', scheme=None) Set the sleep timeouts of specific items such as disk, monitor, etc.
The setting to change, can be one of the following:
• monitor
• standby
• hibernate
• value (int) -- The amount of time in minutes before the item will timeout
# Set monitor timeout to 30 minutes on Battery monitor: powercfg.set_timeout: - value: 30 - power: dc
# Set disk timeout to 10 minutes on AC Power disk: powercfg.set_timeout: - value: 10 - power: ac
salt.states.win_servermanager Manage Windows features via the ServerManager powershell module. Can install and remove roles/features.
depends win_servermanager.install
depends win_servermanager.remove
salt.states.win_servermanager.installed(name, features=None, recurse=False, restart=False, source=None, exclude=None, **kwargs) Install the windows feature. To install a single feature, use the name parameter. To install multiple features, use the features parameter.
NOTE: Some features require reboot after un/installation. If so, until the server is restarted other features can not be installed!
Short name of the feature (the right column in win_servermanager.list_available). This can be a single feature or a string of features in a comma delimited list (no spaces)
NOTE: A list is not allowed in the name parameter of any state. Use the features parameter if you want to pass the features as a list
• features (Optional[list]) --
A list of features to install. If this is passed it will be used instead of the name parameter.
• recurse (Optional[bool]) -- Install all sub-features as well. If the feature is installed but one of its sub-features are not installed set this will install additional sub-features. This argument was previously renamed from force. To ensure backwards compatibility force will continue to work but please update your states to use the preferred recurse arg.
• restart (Optional[bool]) -- Restarts the computer when installation is complete, if required by the role/feature installed. Default is False
Do not use the role or feature names mentioned in the PKGMGR documentation. To get a list of available roles and features run the following command:
salt <minion_name> win_servermanager.list_available
Use the name in the right column of the results.
# Installs the IIS Web Server Role (Web-Server) IIS-WebServerRole: win_servermanager.installed: - recurse: True - name: Web-Server
# Install multiple features, exclude the Web-Service install_multiple_features: win_servermanager.installed: - recurse: True - features: - RemoteAccess - XPS-Viewer - SNMP-Service - exclude: - Web-Server
salt.states.win_servermanager.removed(name, features=None, remove_payload=False, restart=False) Remove the windows feature To remove a single feature, use the name parameter. To remove multiple features, use the features parameter.
Short name of the feature (the right column in win_servermanager.list_available). This can be a single feature or a string of features in a comma-delimited list (no spaces)
A list of features to remove. If this is passed it will be used instead of the name parameter.
• remove_payload (Optional[bool]) -- True will cause the feature to be removed from the side-by-side store. To install the feature in the future you will need to specify the source
• restart (Optional[bool]) -- Restarts the computer when uninstall is complete if required by the role/feature uninstall. Default is False
NOTE: Some features require a reboot after uninstall. If so the feature will not be completely uninstalled until the server is restarted.
# Uninstall the IIS Web Server Rol (Web-Server) IIS-WebserverRole: win_servermanager.removed: - name: Web-Server
# Uninstall multiple features, reboot if required uninstall_multiple_features: win_servermanager.removed: - features: - RemoteAccess - XPX-Viewer - SNMP-Service - restart: True
salt.states.win_smtp_server Module for managing IIS SMTP server configuration on Windows servers.
salt.states.win_smtp_server.active_log_format(name, log_format, server='SmtpSvc/1') Manage the active log format for the SMTP server.
smtp-log-format: win_smtp_server.active_log_format: - log_format: Microsoft IIS Log File Format
salt.states.win_smtp_server.connection_ip_list(name, addresses=None, grant_by_default=False, server='SmtpSvc/1') Manage IP list for SMTP connections.
Example of usage for creating a whitelist:
smtp-connection-whitelist: win_smtp_server.connection_ip_list: - addresses: 127.0.0.1: 255.255.255.255 172.16.1.98: 255.255.255.255 172.16.1.99: 255.255.255.255 - grant_by_default: False
Example of usage for creating a blacklist:
smtp-connection-blacklist: win_smtp_server.connection_ip_list: - addresses: 172.16.1.100: 255.255.255.255 172.16.1.101: 255.255.255.255 - grant_by_default: True
Example of usage for allowing any source to connect:
smtp-connection-blacklist: win_smtp_server.connection_ip_list: - addresses: {} - grant_by_default: True
salt.states.win_smtp_server.relay_ip_list(name, addresses=None, server='SmtpSvc/1') Manage IP list for SMTP relay connections.
smtp-relay-list: win_smtp_server.relay_ip_list: - addresses: - 24.0.0.128 - 32.0.0.128 - 60.0.0.128 - 1.0.0.0 - 76.0.0.0 - 0.0.0.0 - 0.0.0.0 - 1.0.0.0 - 1.0.0.0 - 2.0.0.0 - 2.0.0.0 - 4.0.0.0 - 0.0.0.0 - 76.0.0.128 - 0.0.0.0 - 0.0.0.0 - 0.0.0.0 - 0.0.0.0 - 255.255.255.255 - 127.0.0.1
Example of usage for disabling relaying:
smtp-relay-list: win_smtp_server.relay_ip_list: - addresses: None
Example of usage for allowing relaying from any source:
smtp-relay-list: win_smtp_server.relay_ip_list: - addresses: []
salt.states.win_smtp_server.server_setting(name, settings=None, server='SmtpSvc/1') Ensure the value is set for the specified setting.
smtp-settings: win_smtp_server.server_setting: - settings: LogType: 1 LogFilePeriod: 1 MaxMessageSize: 16777216 MaxRecipients: 10000 MaxSessionSize: 16777216
salt.states.win_snmp Module for managing SNMP service settings on Windows servers.
salt.states.win_snmp.agent_settings(name, contact, location, services=None) Manage the SNMP sysContact, sysLocation, and sysServices settings.
• contact (str) -- The SNMP contact.
• location (str) -- The SNMP location.
• services (str) -- A list of selected services.
snmp-agent-settings: win_snmp.agent_settings: - contact: Test Contact - location: Test Location - services: - Physical - Internet
salt.states.win_snmp.auth_traps_enabled(name, status=True) Manage the sending of authentication traps.
Parameters status (bool) -- The enabled status.
snmp-auth-traps: win_snmp.auth_traps_enabled: - status: True
salt.states.win_snmp.community_names(name, communities=None) Manage the SNMP accepted community names and their permissions.
Parameters communities (str) -- A dictionary of SNMP communities and permissions.
snmp-community-names: win_snmp.community_names: - communities: TestCommunity: Read Only OtherCommunity: Read Write
salt.states.win_system Management of Windows system information New in version 2014.1.0.
This state is used to manage system information such as the computer name and description.
ERIK-WORKSTATION: system.computer_name: []
This is Erik's computer, don't touch!: system.computer_desc: []
salt.states.win_system.computer_desc(name) Manage the computer's description field
name   The desired computer description
salt.states.win_system.computer_description(name) This function is an alias of computer_desc. Manage the computer's description field
salt.states.win_system.computer_name(name) Manage the computer's name
name   The desired computer name
salt.states.win_system.hostname(name) New in version 2016.3.0.
Manage the hostname of the computer
name   The hostname to set
salt.states.win_system.join_domain(name, username=None, password=None, account_ou=None, account_exists=False, restart=False) Checks if a computer is joined to the Domain. If the computer is not in the Domain, it will be joined.
• name (str) -- The name of the Domain.
• username (str) -- Username of an account which is authorized to join computers to the specified domain. Need to be either fully qualified like user@domain.tld or simply user.
• password (str) -- Password of the account to add the computer to the Domain.
• account_ou (str) -- The DN of the OU below which the account for this computer should be created when joining the domain, e.g. ou=computers,ou=departm_432,dc=my-company,dc=com.
• account_exists (bool) -- Needs to be set to True to allow re-using an existing computer account.
• restart (bool) -- Needs to be set to True to restart the computer after a successful join.
join_to_domain: system.join_domain: - name: mydomain.local.com - username: myaccount@mydomain.local.com - password: mysecretpassword - restart: True
salt.states.win_system.reboot(name, message=None, timeout=5, force_close=True, in_seconds=False, only_on_pending_reboot=True) Reboot the computer
• message (str) --
An optional message to display to users. It will also be used as a comment in the event log entry.
The default value is None.
The number of minutes or seconds before a reboot will occur. Whether this number represents minutes or seconds depends on the value of in_seconds.
The default value is 5.
If this is True, the value of timeout will be treated as a number of seconds. If this is False, the value of timeout will be treated as a number of minutes.
The default value is False.
• force_close (bool) --
If this is True, running applications will be forced to close without warning. If this is False, running applications will not get the opportunity to prompt users about unsaved data.
The default value is True.
• only_on_pending_reboot (bool) --
If this is True, the reboot will only occur if the system reports a pending reboot. If this is False, the reboot will always occur.
salt.states.win_system.shutdown(name, message=None, timeout=5, force_close=True, reboot=False, in_seconds=False, only_on_pending_reboot=False) Shutdown the computer
The number of minutes or seconds before a shutdown will occur. Whether this number represents minutes or seconds depends on the value of in_seconds.
• reboot (bool) --
If this is True, the computer will restart immediately after shutting down. If False the system flushes all caches to disk and safely powers down the system.
If this is True, the shutdown will only occur if the system reports a pending reboot. If this is False, the shutdown will always occur.
salt.states.win_system.workgroup(name) New in version 3001.
Manage the workgroup of the computer
Parameters name (str) -- The workgroup to set
set workgroup: system.workgroup: - name: local
salt.states.win_wua Installation of Windows Updates using the Windows Update Agent
Salt can manage Windows updates via the "wua" state module. Updates can be installed and removed. Update management declarations are as follows:
For installation:
# Install a single update using the KB KB3194343: wua.installed
# Install a single update using the name parameter install_update: wua.installed: - name: KB3194343
# Install multiple updates using the updates parameter and a combination of # KB number and GUID install_updates: wua.installed: - updates: - KB3194343 - bb1dbb26-3fb6-45fd-bb05-e3c8e379195c
For removal:
# Remove a single update using the KB KB3194343: wua.removed
# Remove a single update using the name parameter remove_update: wua.removed: - name: KB3194343
# Remove multiple updates using the updates parameter and a combination of # KB number and GUID remove_updates: wua.removed: - updates: - KB3194343 - bb1dbb26-3fb6-45fd-bb05-e3c8e379195c
salt.states.win_wua.installed(name, updates=None) Ensure Microsoft Updates are installed. Updates will be downloaded if needed.
• name (str) -- The identifier of a single update to install.
• updates (list) -- A list of identifiers for updates to be installed. Overrides name. Default is None.
NOTE: Identifiers can be the GUID, the KB number, or any part of the Title of the Microsoft update. GUIDs and KBs are the preferred method to ensure you're installing the correct update.
WARNING: Using a partial KB number or a partial Title could result in more than one update being installed.
Returns A dictionary containing the results of the update
# using a GUID install_update: wua.installed: - name: 28cf1b09-2b1a-458c-9bd1-971d1b26b211
# using a KB install_update: wua.installed: - name: KB3194343
# using the full Title install_update: wua.installed: - name: Security Update for Adobe Flash Player for Windows 10 Version 1607 (for x64-based Systems) (KB3194343)
# Install multiple updates install_updates: wua.installed: - updates: - KB3194343 - 28cf1b09-2b1a-458c-9bd1-971d1b26b211
salt.states.win_wua.removed(name, updates=None) Ensure Microsoft Updates are uninstalled.
• name (str) -- The identifier of a single update to uninstall.
• updates (list) -- A list of identifiers for updates to be removed. Overrides name.  Default is None.
NOTE: Identifiers can be the GUID, the KB number, or any part of the Title of the Microsoft update. GUIDs and KBs are the preferred method to ensure you're uninstalling the correct update.
WARNING: Using a partial KB number or a partial Title could result in more than one update being removed.
Returns A dictionary containing the results of the removal
# using a GUID uninstall_update: wua.removed: - name: 28cf1b09-2b1a-458c-9bd1-971d1b26b211
# using a KB uninstall_update: wua.removed: - name: KB3194343
# using the full Title uninstall_update: wua.removed: - name: Security Update for Adobe Flash Player for Windows 10 Version 1607 (for x64-based Systems) (KB3194343)
# Install multiple updates uninstall_updates: wua.removed: - updates: - KB3194343 - 28cf1b09-2b1a-458c-9bd1-971d1b26b211
salt.states.win_wua.uptodate(name, software=True, drivers=False, skip_hidden=False, skip_mandatory=False, skip_reboot=True, categories=None, severities=None) Ensure Microsoft Updates that match the passed criteria are installed.  Updates will be downloaded if needed.
This state allows you to update a system without specifying a specific update to apply. All matching updates will be installed.
• name (str) -- The name has no functional value and is only used as a tracking reference
• software (bool) -- Include software updates in the results (default is True)
• drivers (bool) -- Include driver updates in the results (default is False)
• skip_hidden (bool) -- Skip updates that have been hidden. Default is False.
• skip_mandatory (bool) -- Skip mandatory updates. Default is False.
• skip_reboot (bool) -- Skip updates that require a reboot. Default is True.
# Update the system using the state defaults update_system: wua.uptodate
# Update the drivers update_drivers: wua.uptodate: - software: False - drivers: True - skip_reboot: False
# Apply all critical updates update_critical: wua.uptodate: - severities: - Critical
salt.states.win_wusa Microsoft Updates (KB) Management
This module provides the ability to enforce KB installations from files (.msu), without WSUS or Windows Update
salt.states.win_wusa.installed(name, source) Ensure an update is installed on the minion
• name (str) -- Name of the Windows KB ("KB123456")
• source (str) -- Source of .msu file corresponding to the KB
KB123456: wusa.installed: - source: salt://kb123456.msu
salt.states.win_wusa.uninstalled(name) Ensure an update is uninstalled from the minion
Parameters name (str) -- Name of the Windows KB ("KB123456")
KB123456: wusa.uninstalled
salt.states.winrepo Manage Windows Package Repository