Config Tasks¶

Name	SupportsStates	Description
firewall-rule	Yes	Add/Remove Windows Advanced Firewall
install-rds	No	Install Microsoft Remote Desktop Services
install-sql	No	Install Microsoft SQL Server
invoke-psscript	No	Invoke custom powershell script, more details below
local-group-member	Yes	Add/Remove Local Group Members
package	Yes	Install/Uninstall package
registry-keys	Yes	Add/Remove Registry Key
request-certificate-acme	No	Requests certificate using ACME protocol
user-rights-assignment	Yes	Add/Remove Windows User Rights Assignment
win-feature	Yes	Install/Uninstall Windows Feature

Custom config tasks can be added using customer owned git repos.

firewall-rule¶

Create or modify a Windows Firewall rule or group on target hosts.

This playbook allows you to define or update a firewall rule or group by specifying either the name (for a single rule) or group (for a group of rules). You can control ports, protocols, direction, action, and other rule properties.

At least one of name or group must be defined.

Variables:

Name	Mandatory	Type	Description
name	true, if group undefined	String	Name of the firewall rule to create or modify
group	true, if name undefined	String	Name of the firewall group to create or modify
localport	false	String	Local port(s) for the rule (e.g., "80", "80,443")
action	false	String	Action for the rule (`allow`, `block`, etc.)
direction	false	String	Direction of traffic (`in`, `out`)
protocol	false	String	Protocol (`TCP`, `UDP`, etc.)
state	false	String	State of the rule (`present` or `absent`), default is `present`
enabled	false	Bool	Whether the rule is enabled (default: true)

Example usage:

  - name: firewall-rule
    variables:
      name: web
      action: allow
      localport: 443
      protocol: tcp
      direction: in

install-rds¶

Install and configure Remote Desktop Services (RDS) on target Windows hosts.

This playbook installs required RDS roles and features, configures a session deployment and collection, and sets up RDS licensing. It requires you to specify the RDS license server and the user group(s) allowed to access RDS.

Both rd_license_server and rd_users variables are mandatory.

Variables:

Name	Mandatory	Type	Description
rd_license_server	true	String	FQDN or name of the RDS license server to use
rd_users	true	String	User group(s) allowed to access the RDS collection (comma-separated or array)

Example usage:

  - name: install-rds
    variables:
      rd_license_server: rdslicense.foobar.com
      rd_users: '"foobar\group1","foobar\group2"'

install-sql¶

tbd

invoke-script¶

Run custom PowerShell code or scripts on target Windows hosts.

This playbook allows you to execute either a PowerShell script block (inline code) or a script file on the remote host. You can pass parameters to the script, and optionally enable automatic assignment of parameters if they are not explicitly defined in the script.

Variables:

Name	Mandatory	Type	Description
script	true, if path undefined	String	ScriptBlock to be executed on target
path	true, if script undefined	String	Powershell file path to be executed on target
parameters	false	String	JSON String with parameter for the given script or path to be used as input (define each parameter w/ key-value)
automatic_parameter	false	Bool	if enabled, parameter will be automatically assigned in the specified script/path and don't need to be defined.

Example usage:

  - name: invoke-psscript
    variables:
      script: |
        Set-Culture de-CH
        Set-TimeZone -Name "Central Europe Standard Time"

  - name: invoke-psscript
    variables:
      path: C:\tools\set-timezone.ps1

local-group-member¶

Manage local Windows group membership on target hosts.

This playbook allows you to add or remove users and groups to/from a specified local group. You must specify the group name and a list of members.

Both name (group name) and members (list of users/groups) are mandatory.

Variables:

Name	Mandatory	Type	Description
name	true	String	Name of the local group to manage
members	true	List	List of users or groups to add/remove (e.g., `['DOMAIN\User', 'LocalGroup']`)
state	false	String	Whether members should be present or absent in the group (`present` or `absent`, default: `present`)

Example usage:

- name: local-group-member
  variables:
    name: Remote Management Users
    members:
      - foo\group1

package¶

Install, upgrade, or uninstall software packages.

This playbook manages software packages on target hosts using the Chocolatey provider for Windows or the package manager discovered by Ansible for Linux. You can specify the package name, version, and additional options such as pinning, force, and custom sources.

The name variable (package name) is mandatory.

Variables:

Name	Mandatory	Type	Description
name	true	String	Name of the package to manage
version	false	String	Specific version to install (omit for latest)
state	false	String	Desired state: `present`, `absent`, or `latest` (default: `present`)
pinned	false	Bool	Whether the package should be pinned (default: `false`)
force	false	Bool	Force install/uninstall (default: `false`)
source	false	String	Custom Chocolatey source (optional)
package_params	false	String	Additional parameters for the package (optional)

Example usage:

  - name: package
    variables:
      name: sql-server-management-studio

- name: package
  variables:
    name:
    - pwsh
    - mremoteng
    - vscode
    - googlechrome
    - firefox
    - vim
    - sql-server-management-studio

- name: package
  variables:
    provider: chocolatey
    name: dotnetcore-windowshosting
    version: 2.1.30

registry-keys¶

Manage Windows registry keys and values on target hosts.

This Config Task allows you to create, modify, or delete registry keys and values by specifying a list of registry key definitions. Each entry can define the key path, value name, data, type, and desired state.

The registry_keys variable (a list of registry key/value definitions) is mandatory.

Variables:

Name	Mandatory	Type	Description
registry_keys	true	List	List of registry key/value definitions (see examples below)

Each item in registry_keys can have:

Field	Mandatory	Type	Description
path	true	String	Registry key path (e.g., `HKLM:\Software\TestPath`)
name	false	String	Name of the registry value (omit to operate on the key itself)
data	false	Any	Value data (string, int, binary, etc.)
type	false	String	Value type (`string`, `dword`, `binary`, etc.)
state	false	String	`present` (default) to create/update, `absent` to delete value or key
delete_key	false	Bool	If true, deletes the entire key (optional)
hive	false	String	Registry hive (optional, usually inferred from path)

Example usage:

- name: registry-keys
  variables:
    registry_keys:
      - name: stringExample
        path: HKLM:\Software\TestPath
        data: world
      - name: dwordExample
        path: HKLM:\Software\TestPath
        data: 1337
        type: dword
      - name: binaryExample
        path: HKLM:\Software\TestPath
        data: hex:be,ef,be,ef,be,ef,be,ef,be,ef
        type: binary
      - name: stringExample
        path: HKLM:\Software\TestPath
        state: absent
      - path: HKLM:\Software\TestPath
        state: absent

request-certificate-acme¶

Request and deploy SSL certificates from an ACME server (e.g., Let's Encrypt) using Win-ACME on Windows hosts.

This playbook requests a certificate for a given FQDN and email, optionally assigns it to IIS websites, and sets up automatic renewal using a scheduled task. You can also specify a custom ACME endpoint.

The fqdn and email variables are mandatory.

Variables:

Name	Mandatory	Type	Description
fqdn	true	String	The fully qualified domain name for the certificate
email	true	String	Email address for ACME registration and notifications
acme_endpoint	false	String	Custom ACME server endpoint (default: Let's Encrypt production)
target	false	String	Set to `iis` to automatically assign and renew the certificate for IIS websites

Example usage:

- name: Request and deploy certificate for IIS
  import_playbook: request-certificate-acme.yml
  vars:
    fqdn: "myapp.example.com"
    email: "admin@example.com"
    target: "iis"

- name: Request certificate from custom ACME endpoint
  import_playbook: request-certificate-acme.yml
  vars:
    fqdn: "internal.example.com"
    email: "admin@example.com"
    acme_endpoint: "https://pki.foobar.com/acme"

user-rights-assignment¶

Manage Windows user rights assignments (privileges) on target hosts.

This playbook allows you to add or remove specific user rights (such as logon as a service, batch logon, etc.) for users or groups. You must specify the right (permission), the identities (users/groups), and the action (add or remove).

The user_rights variable (a list of assignments) is mandatory.

Variables:

Name	Mandatory	Type	Description
user_rights	true	List	List of user rights assignments (see fields below)

Each item in user_rights can have:

Field	Mandatory	Type	Description
permission	true	String	The user right/privilege to assign (e.g., `SeBatchLogonRight`)
identities	true	List/Str	List of users/groups or a single user/group to assign/remove
action	false	String	`add` (default) or `remove`

Example usage:

- name: user-rights-assignment
    variables:
      user_rights:
      - permission: SeLockMemoryPrivilege
        identities:
          - "foobar\\serviceaccount1"

win-feature¶

Install, remove, or manage Windows Features on target hosts.

This playbook allows you to add or remove Windows features and roles by specifying the feature name and desired state. You can also control whether management tools and sub-features are included, and specify a custom source if needed.

The name variable (feature name) is mandatory.

Variables:

Name	Mandatory	Type	Description
name	true	String	Name of the Windows feature to manage
state	false	String	Desired state: `present` (default) or `absent`
include_management_tools	false	Bool	Whether to include management tools (default: false)
include_sub_features	false	Bool	Whether to include sub-features (default: false)
force	false	Bool	Force install/uninstall (default: false)
source	false	String	Custom source for feature files (optional)

Example usage:

- name: win-feature
    variables:
      name:
        - PowerShell
        - PowerShell-V2
        - WoW64-Support

- name: win-feature
    variables:
      name: PowerShell-V2
      state: absent