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_feature_info | Gather information about Windows features |
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_net_adapter_feature | Enable or disable certain network adapters. |
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_copy | Copies registered PSRepositories to other user profiles |
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 |
community.windows.win_zip | Compress file or directory as zip archive on the Windows node |
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:
IRC - #ansible-windows
irc.libera.chat 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}"
ansible-test
Testing with 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:
pip install git+https://github.com/ansible-network/collection_prep collection_prep_add_docs --path ./ --branch-name main
- Update the
CHANGELOG
:- Make sure you have
antsibull-changelog
installedpip 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
.
- Make sure you have
- 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> -vv
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 libera.chat 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.