Ansible Collection: community.windows

The community.windows collection includes the community plugins supported by Ansible community to help the management of Windows hosts.

Ansible version compatibility

This collection has been tested against following Ansible versions: >=2.10.

Plugins and modules within a collection may be tested with only specific Ansible versions. A collection may contain metadata that identifies these versions. PEP440 is the schema used to describe the versions of Ansible.

Included content

Lookup plugins

Name	Description
community.windows.laps_password	Retrieves the LAPS password for a server.

Modules

Name	Description
community.windows.psexec	Runs commands on a remote Windows host based on the PsExec model
community.windows.win_audit_policy_system	Used to make changes to the system wide Audit Policy
community.windows.win_audit_rule	Adds an audit rule to files, folders, or registry keys
community.windows.win_auto_logon	Adds or Sets auto logon registry keys.
community.windows.win_certificate_info	Get information on certificates from a Windows Certificate Store
community.windows.win_computer_description	Set windows description, owner and organization
community.windows.win_credential	Manages Windows Credentials in the Credential Manager
community.windows.win_data_deduplication	Module to enable Data Deduplication on a volume.
community.windows.win_defrag	Consolidate fragmented files on local volumes
community.windows.win_dhcp_lease	Manage Windows Server DHCP Leases
community.windows.win_disk_facts	Show the attached disks and disk information of the target host
community.windows.win_disk_image	Manage ISO/VHD/VHDX mounts on Windows hosts
community.windows.win_dns_record	Manage Windows Server DNS records
community.windows.win_dns_zone	Manage Windows Server DNS Zones
community.windows.win_domain_computer	Manage computers in Active Directory
community.windows.win_domain_group	Creates, modifies or removes domain groups
community.windows.win_domain_group_membership	Manage Windows domain group membership
community.windows.win_domain_object_info	Gather information an Active Directory object
community.windows.win_domain_user	Manages Windows Active Directory user accounts
community.windows.win_dotnet_ngen	Runs ngen to recompile DLLs after .NET updates
community.windows.win_eventlog	Manage Windows event logs
community.windows.win_eventlog_entry	Write entries to Windows event logs
community.windows.win_file_compression	Alters the compression of files and directories on NTFS partitions.
community.windows.win_file_version	Get DLL or EXE file build version
community.windows.win_firewall	Enable or disable the Windows Firewall
community.windows.win_firewall_rule	Windows firewall automation
community.windows.win_format	Formats an existing volume or a new volume on an existing partition on Windows
community.windows.win_hosts	Manages hosts file entries on Windows.
community.windows.win_hotfix	Install and uninstalls Windows hotfixes
community.windows.win_http_proxy	Manages proxy settings for WinHTTP
community.windows.win_iis_virtualdirectory	Configures a virtual directory in IIS
community.windows.win_iis_webapplication	Configures IIS web applications
community.windows.win_iis_webapppool	Configure IIS Web Application Pools
community.windows.win_iis_webbinding	Configures a IIS Web site binding
community.windows.win_iis_website	Configures a IIS Web site
community.windows.win_inet_proxy	Manages proxy settings for WinINet and Internet Explorer
community.windows.win_initialize_disk	Initializes disks on Windows Server
community.windows.win_lineinfile	Ensure a particular line is in a file, or replace an existing line using a back-referenced regular expression
community.windows.win_mapped_drive	Map network drives for users
community.windows.win_msg	Sends a message to logged in users on Windows hosts
community.windows.win_netbios	Manage NetBIOS over TCP/IP settings on Windows.
community.windows.win_nssm	Install a service using NSSM
community.windows.win_pagefile	Query or change pagefile configuration
community.windows.win_partition	Creates, changes and removes partitions on Windows Server
community.windows.win_pester	Run Pester tests on Windows hosts
community.windows.win_power_plan	Changes the power plan of a Windows system
community.windows.win_product_facts	Provides Windows product and license information
community.windows.win_psexec	Runs commands (remotely) as another (privileged) user
community.windows.win_psmodule	Adds or removes a Windows PowerShell module
community.windows.win_psmodule_info	Gather information about PowerShell Modules
community.windows.win_psrepository	Adds, removes or updates a Windows PowerShell repository.
community.windows.win_psrepository_info	Gather information about PSRepositories
community.windows.win_psscript	Install and manage PowerShell scripts from a PSRepository
community.windows.win_psscript_info	Gather information about installed PowerShell Scripts
community.windows.win_pssession_configuration	Manage PSSession Configurations
community.windows.win_rabbitmq_plugin	Manage RabbitMQ plugins
community.windows.win_rds_cap	Manage Connection Authorization Policies (CAP) on a Remote Desktop Gateway server
community.windows.win_rds_rap	Manage Resource Authorization Policies (RAP) on a Remote Desktop Gateway server
community.windows.win_rds_settings	Manage main settings of a Remote Desktop Gateway server
community.windows.win_region	Set the region and format settings
community.windows.win_regmerge	Merges the contents of a registry file into the Windows registry
community.windows.win_robocopy	Synchronizes the contents of two directories using Robocopy
community.windows.win_route	Add or remove a static route
community.windows.win_say	Text to speech module for Windows to speak messages and optionally play sounds
community.windows.win_scheduled_task	Manage scheduled tasks
community.windows.win_scheduled_task_stat	Get information about Windows Scheduled Tasks
community.windows.win_scoop	Manage packages using Scoop
community.windows.win_scoop_bucket	Manage Scoop buckets
community.windows.win_security_policy	Change local security policy settings
community.windows.win_shortcut	Manage shortcuts on Windows
community.windows.win_snmp	Configures the Windows SNMP service
community.windows.win_timezone	Sets Windows machine timezone
community.windows.win_toast	Sends Toast windows notification to logged in users on Windows 10 or later hosts
community.windows.win_unzip	Unzips compressed files and archives on the Windows node
community.windows.win_user_profile	Manages the Windows user profiles.
community.windows.win_wait_for_process	Waits for a process to exist or not exist before continuing.
community.windows.win_wakeonlan	Send a magic Wake-on-LAN (WoL) broadcast packet
community.windows.win_webpicmd	Installs packages using Web Platform Installer command-line
community.windows.win_xml	Manages XML file content on Windows hosts

Installation and Usage

Installing the Collection from Ansible Galaxy

Before using the Windows collection, you need to install it with the ansible-galaxy CLI:

ansible-galaxy collection install community.windows

You can also include it in a requirements.yml file and install it via ansible-galaxy collection install -r requirements.yml using the format:

collections:
- name: community.windows

Contributing to this collection

We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the Community Windows collection repository. See Contributing to Ansible-maintained collections for details.

See Developing modules for Windows for specifics on Windows modules.

You can also join us on:

Freenode IRC - #ansible-windows Freenode channel

See the Ansible Community Guide for details on contributing to Ansible.

Code of Conduct

This collection follows the Ansible project's Code of Conduct. Please read and familiarize yourself with this document.

Generating plugin docs

Currently module documentation is generated manually using add_docs.py. This should be run whenever there are any major doc changes or additional plugins have been added to ensure a docpage is viewable online in this repo. The following commands will run the doc generator and create the updated doc pages under docs.

# This is the path to the ansible.windows checkout
COLLECTION_PATH=~/ansible_collections/community/windows

cd /tmp
git clone https://github.com/ansible-network/collection_prep.git
cd collection_prep
python add_docs.py -p "${COLLECTION_PATH}"

Testing with ansible-test

The tests directory contains configuration for running sanity and integration tests using ansible-test.

You can run the collection's test suites with the commands:

ansible-test sanity --docker
ansible-test windows-integration --docker

Publishing New Version

The current process for publishing new versions of the Windows Community Collection is manual, and requires a user who has access to the community namespace on Ansible Galaxy to publish the build artifact.

• Update galaxy.yml with the new version for the collection.
• Rebuild the plugin docs:

  git clone https://github.com/ansible-network/collection_prep.git /tmp/collection_prep
  python /tmp/collection_prep/add_docs.py --path ./ --branch-name main
  rm -rf /tmp/collection_prep

• Update the CHANGELOG:
  • Make sure you have antsibull-changelog installed pip install antsibull-changelog.
  • Make sure there are fragments for all known changes in changelogs/fragments.
  • Add a new fragment with the header release_summary to give a summary on the release.
  • Run antsibull-changelog release.
• Commit the changes and wait for CI to be green
• Build and publish the collection to Galaxy:

  git clone https://github.com/ansible-collections/community.windows.git /tmp/community.windows
  ansible-galaxy collection build /tmp/community.windows --output-path /tmp/community.windows
  ansible-galaxy collection publish $(find /tmp/community.windows -maxdepth 1 -name 'community-windows-*.tar.gz') --token <API_KEY>
  

After the version is published, verify it exists on the Windows Community Collection Galaxy page.

More Information

For more information about Ansible's Windows integration, join the #ansible-windows channel on Freenode IRC, and browse the resources in the Windows Working Group Community wiki page.

• Ansible Collection overview
• Ansible User guide
• Ansible Developer guide
• Ansible Community code of conduct

License

GNU General Public License v3.0 or later

See COPYING to see the full text.