1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
# Ansible Collection: community.windows
[](https://dev.azure.com/ansible/community.windows/_build/latest?definitionId=23&branchName=main)
[](https://codecov.io/gh/ansible-collections/community.windows)
The `community.windows` collection includes the community plugins supported by Ansible community to help the management of Windows hosts.
<!--start requires_ansible-->
## 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.
<!--end requires_ansible-->
## Included content
<!--start collection content-->
### Lookup plugins
Name | Description
--- | ---
[community.windows.laps_password](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.laps_password_lookup.rst)|Retrieves the LAPS password for a server.
### Modules
Name | Description
--- | ---
[community.windows.psexec](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.psexec_module.rst)|Runs commands on a remote Windows host based on the PsExec model
[community.windows.win_audit_policy_system](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_audit_policy_system_module.rst)|Used to make changes to the system wide Audit Policy
[community.windows.win_audit_rule](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_audit_rule_module.rst)|Adds an audit rule to files, folders, or registry keys
[community.windows.win_auto_logon](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_auto_logon_module.rst)|Adds or Sets auto logon registry keys.
[community.windows.win_certificate_info](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_certificate_info_module.rst)|Get information on certificates from a Windows Certificate Store
[community.windows.win_computer_description](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_computer_description_module.rst)|Set windows description, owner and organization
[community.windows.win_credential](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_credential_module.rst)|Manages Windows Credentials in the Credential Manager
[community.windows.win_data_deduplication](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_data_deduplication_module.rst)|Module to enable Data Deduplication on a volume.
[community.windows.win_defrag](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_defrag_module.rst)|Consolidate fragmented files on local volumes
[community.windows.win_dhcp_lease](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_dhcp_lease_module.rst)|Manage Windows Server DHCP Leases
[community.windows.win_disk_facts](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_disk_facts_module.rst)|Show the attached disks and disk information of the target host
[community.windows.win_disk_image](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_disk_image_module.rst)|Manage ISO/VHD/VHDX mounts on Windows hosts
[community.windows.win_dns_record](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_dns_record_module.rst)|Manage Windows Server DNS records
[community.windows.win_dns_zone](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_dns_zone_module.rst)|Manage Windows Server DNS Zones
[community.windows.win_domain_computer](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_domain_computer_module.rst)|Manage computers in Active Directory
[community.windows.win_domain_group](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_domain_group_module.rst)|Creates, modifies or removes domain groups
[community.windows.win_domain_group_membership](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_domain_group_membership_module.rst)|Manage Windows domain group membership
[community.windows.win_domain_object_info](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_domain_object_info_module.rst)|Gather information an Active Directory object
[community.windows.win_domain_user](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_domain_user_module.rst)|Manages Windows Active Directory user accounts
[community.windows.win_dotnet_ngen](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_dotnet_ngen_module.rst)|Runs ngen to recompile DLLs after .NET updates
[community.windows.win_eventlog](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_eventlog_module.rst)|Manage Windows event logs
[community.windows.win_eventlog_entry](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_eventlog_entry_module.rst)|Write entries to Windows event logs
[community.windows.win_file_compression](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_file_compression_module.rst)|Alters the compression of files and directories on NTFS partitions.
[community.windows.win_file_version](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_file_version_module.rst)|Get DLL or EXE file build version
[community.windows.win_firewall](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_firewall_module.rst)|Enable or disable the Windows Firewall
[community.windows.win_firewall_rule](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_firewall_rule_module.rst)|Windows firewall automation
[community.windows.win_format](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_format_module.rst)|Formats an existing volume or a new volume on an existing partition on Windows
[community.windows.win_hosts](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_hosts_module.rst)|Manages hosts file entries on Windows.
[community.windows.win_hotfix](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_hotfix_module.rst)|Install and uninstalls Windows hotfixes
[community.windows.win_http_proxy](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_http_proxy_module.rst)|Manages proxy settings for WinHTTP
[community.windows.win_iis_virtualdirectory](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_iis_virtualdirectory_module.rst)|Configures a virtual directory in IIS
[community.windows.win_iis_webapplication](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_iis_webapplication_module.rst)|Configures IIS web applications
[community.windows.win_iis_webapppool](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_iis_webapppool_module.rst)|Configure IIS Web Application Pools
[community.windows.win_iis_webbinding](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_iis_webbinding_module.rst)|Configures a IIS Web site binding
[community.windows.win_iis_website](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_iis_website_module.rst)|Configures a IIS Web site
[community.windows.win_inet_proxy](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_inet_proxy_module.rst)|Manages proxy settings for WinINet and Internet Explorer
[community.windows.win_initialize_disk](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_initialize_disk_module.rst)|Initializes disks on Windows Server
[community.windows.win_lineinfile](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_lineinfile_module.rst)|Ensure a particular line is in a file, or replace an existing line using a back-referenced regular expression
[community.windows.win_mapped_drive](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_mapped_drive_module.rst)|Map network drives for users
[community.windows.win_msg](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_msg_module.rst)|Sends a message to logged in users on Windows hosts
[community.windows.win_net_adapter_feature](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_net_adapter_feature_module.rst)|Enable or disable certain network adapters.
[community.windows.win_netbios](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_netbios_module.rst)|Manage NetBIOS over TCP/IP settings on Windows.
[community.windows.win_nssm](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_nssm_module.rst)|Install a service using NSSM
[community.windows.win_pagefile](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_pagefile_module.rst)|Query or change pagefile configuration
[community.windows.win_partition](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_partition_module.rst)|Creates, changes and removes partitions on Windows Server
[community.windows.win_pester](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_pester_module.rst)|Run Pester tests on Windows hosts
[community.windows.win_power_plan](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_power_plan_module.rst)|Changes the power plan of a Windows system
[community.windows.win_product_facts](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_product_facts_module.rst)|Provides Windows product and license information
[community.windows.win_psexec](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_psexec_module.rst)|Runs commands (remotely) as another (privileged) user
[community.windows.win_psmodule](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_psmodule_module.rst)|Adds or removes a Windows PowerShell module
[community.windows.win_psmodule_info](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_psmodule_info_module.rst)|Gather information about PowerShell Modules
[community.windows.win_psrepository](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_psrepository_module.rst)|Adds, removes or updates a Windows PowerShell repository.
[community.windows.win_psrepository_copy](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_psrepository_copy_module.rst)|Copies registered PSRepositories to other user profiles
[community.windows.win_psrepository_info](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_psrepository_info_module.rst)|Gather information about PSRepositories
[community.windows.win_psscript](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_psscript_module.rst)|Install and manage PowerShell scripts from a PSRepository
[community.windows.win_psscript_info](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_psscript_info_module.rst)|Gather information about installed PowerShell Scripts
[community.windows.win_pssession_configuration](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_pssession_configuration_module.rst)|Manage PSSession Configurations
[community.windows.win_rabbitmq_plugin](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_rabbitmq_plugin_module.rst)|Manage RabbitMQ plugins
[community.windows.win_rds_cap](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_rds_cap_module.rst)|Manage Connection Authorization Policies (CAP) on a Remote Desktop Gateway server
[community.windows.win_rds_rap](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_rds_rap_module.rst)|Manage Resource Authorization Policies (RAP) on a Remote Desktop Gateway server
[community.windows.win_rds_settings](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_rds_settings_module.rst)|Manage main settings of a Remote Desktop Gateway server
[community.windows.win_region](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_region_module.rst)|Set the region and format settings
[community.windows.win_regmerge](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_regmerge_module.rst)|Merges the contents of a registry file into the Windows registry
[community.windows.win_robocopy](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_robocopy_module.rst)|Synchronizes the contents of two directories using Robocopy
[community.windows.win_route](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_route_module.rst)|Add or remove a static route
[community.windows.win_say](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_say_module.rst)|Text to speech module for Windows to speak messages and optionally play sounds
[community.windows.win_scheduled_task](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_scheduled_task_module.rst)|Manage scheduled tasks
[community.windows.win_scheduled_task_stat](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_scheduled_task_stat_module.rst)|Get information about Windows Scheduled Tasks
[community.windows.win_scoop](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_scoop_module.rst)|Manage packages using Scoop
[community.windows.win_scoop_bucket](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_scoop_bucket_module.rst)|Manage Scoop buckets
[community.windows.win_security_policy](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_security_policy_module.rst)|Change local security policy settings
[community.windows.win_shortcut](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_shortcut_module.rst)|Manage shortcuts on Windows
[community.windows.win_snmp](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_snmp_module.rst)|Configures the Windows SNMP service
[community.windows.win_timezone](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_timezone_module.rst)|Sets Windows machine timezone
[community.windows.win_toast](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_toast_module.rst)|Sends Toast windows notification to logged in users on Windows 10 or later hosts
[community.windows.win_unzip](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_unzip_module.rst)|Unzips compressed files and archives on the Windows node
[community.windows.win_user_profile](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_user_profile_module.rst)|Manages the Windows user profiles.
[community.windows.win_wait_for_process](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_wait_for_process_module.rst)|Waits for a process to exist or not exist before continuing.
[community.windows.win_wakeonlan](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_wakeonlan_module.rst)|Send a magic Wake-on-LAN (WoL) broadcast packet
[community.windows.win_webpicmd](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_webpicmd_module.rst)|Installs packages using Web Platform Installer command-line
[community.windows.win_xml](https://github.com/ansible-collections/community.windows/blob/main/docs/community.windows.win_xml_module.rst)|Manages XML file content on Windows hosts
<!--end collection content-->
## 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:
```yaml
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](https://github.com/ansible-collections/community.windows). See [Contributing to Ansible-maintained collections](https://docs.ansible.com/ansible/devel/community/contributing_maintained_collections.html#contributing-maintained-collections) for details.
See [Developing modules for Windows](https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general_windows.html#developing-modules-general-windows) for specifics on Windows modules.
You can also join us on:
Freenode IRC - ``#ansible-windows`` Freenode channel
See the [Ansible Community Guide](https://docs.ansible.com/ansible/latest/community/index.html) for details on contributing to Ansible.
### Code of Conduct
This collection follows the Ansible project's
[Code of Conduct](https://docs.ansible.com/ansible/devel/community/code_of_conduct.html).
Please read and familiarize yourself with this document.
### Generating plugin docs
Currently module documentation is generated manually using
[add_docs.py](https://github.com/ansible-network/collection_prep/blob/master/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](docs).
```bash
# 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`](https://docs.ansible.com/ansible/latest/dev_guide/testing_integration.html).
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:
```bash
git clone https://github.com/ansible-network/collection_prep.git /tmp/collection_prep
pip install /tmp/collection_prep
collection_prep_add_docs --path ./ --branch-name main
rm -rf /tmp/collection_prep
```
* Update the `CHANGELOG`:
* Make sure you have [`antsibull-changelog`](https://pypi.org/project/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:
```bash
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](https://galaxy.ansible.com/community/windows).
## 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](https://github.com/ansible/community/wiki/Windows) Community wiki page.
- [Ansible Collection overview](https://github.com/ansible-collections/overview)
- [Ansible User guide](https://docs.ansible.com/ansible/latest/user_guide/index.html)
- [Ansible Developer guide](https://docs.ansible.com/ansible/latest/dev_guide/index.html)
- [Ansible Community code of conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html)
## License
GNU General Public License v3.0 or later
See [COPYING](COPYING) to see the full text.
|
