/community.windows

Windows community collection for Ansible

Primary LanguagePowerShellGNU General Public License v3.0GPL-3.0

Ansible Collection: community.windows

Build Status codecov

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}"

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:
    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 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> -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.

License

GNU General Public License v3.0 or later

See COPYING to see the full text.