win_wakeonlan: New module to send Wake-On-Lan packets (#26232)

This is the Windows implementation of the **wakeonlan** module.
Useful if you want to wake up systems in a remote network with only
Windows systems.

CHANGELOG.md

@@ -225,6 +225,7 @@ Ansible Changes By Release
   * win_firewall
   * win_psmodule
   * win_route
+  * win_wakeonlan
 
 
 ## 2.3 "Ramble On" - 2017-04-12

lib/ansible/modules/windows/win_wakeonlan.ps1

@@ -0,0 +1,62 @@
+#!powershell
+# This file is part of Ansible
+#
+# (c) 2017, Dag Wieers <dag@wieers.com>
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+# WANT_JSON
+# POWERSHELL_COMMON
+
+$ErrorActionPreference = "Stop"
+
+$params = Parse-Args $args -supports_check_mode $true
+$check_mode = Get-AnsibleParam -obj $params -name "_ansible_check_mode" -type "bool" -default $false
+
+$mac = Get-AnsibleParam -obj $params -name "mac" -type "str" -failifempty $true
+$broadcast = Get-AnsibleParam -obj $params -name "broadcast" -type "str" -default "255.255.255.255"
+$port = Get-AnsibleParam -obj $params -name "port" -type "int" -default 7
+
+$result = @{
+    changed = $false
+}
+
+$mac_orig = $mac
+$broadcast = [Net.IPAddress]::Parse($broadcast)
+
+# Remove possible separator from MAC address
+if ($mac.Length -eq (12 + 5)) {
+    $mac = $mac.Replace($mac.Substring(2, 1), "")
+}
+
+# If we don't end up with 12 hexadecimal characters, fail
+if ($mac.Length -ne 12) {
+    Fail-Json $result "Incorrect MAC address: $mac_orig"
+}
+
+# Create payload for magic packet
+# TODO: Catch possible conversion errors
+$target = 0,2,4,6,8,10 | % { [convert]::ToByte($mac.Substring($_, 2), 16) }
+$data = (,[byte]255 * 6) + ($target * 20)
+
+# Broadcast payload to network
+$udpclient = new-Object System.Net.Sockets.UdpClient
+if (-not $check_mode) {
+    $udpclient.Connect($broadcast, $port)
+    [void] $udpclient.Send($data, 102)
+}
+
+$result.changed = $true
+
+Exit-Json $result

lib/ansible/modules/windows/win_wakeonlan.py

@@ -0,0 +1,70 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# (c) 2017, Dag Wieers <dag@wieers.com>
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+ANSIBLE_METADATA = {'metadata_version': '1.0',
+                    'status': ['preview'],
+                    'supported_by': 'community'}
+
+DOCUMENTATION = r'''
+---
+module: win_wakeonlan
+version_added: '2.4'
+short_description: Send a magic Wake-on-LAN (WoL) broadcast packet
+description:
+- The C(win_wakeonlan) module sends magic Wake-on-LAN (WoL) broadcast packets.
+options:
+  mac:
+    description:
+    - MAC address to send Wake-on-LAN broadcast packet for.
+    required: true
+  broadcast:
+    description:
+    - Network broadcast address to use for broadcasting magic Wake-on-LAN packet.
+    default: 255.255.255.255
+  port:
+    description:
+    - UDP port to use for magic Wake-on-LAN packet.
+    default: 7
+author:
+- Dag Wieers (@dagwieers)
+todo:
+  - Does not have SecureOn password support
+notes:
+  - This module sends a magic packet, without knowing whether it worked. It always report a change.
+  - Only works if the target system was properly configured for Wake-on-LAN (in the BIOS and/or the OS).
+  - Some BIOSes have a different (configurable) Wake-on-LAN boot order (i.e. PXE first).
+'''
+
+EXAMPLES = r'''
+- name: Send a magic Wake-on-LAN packet to 00:00:5E:00:53:66
+  win_wakeonlan:
+    mac: 00:00:5E:00:53:66
+    broadcast: 192.0.2.23
+
+- name: Send a magic Wake-On-LAN packet on port 9 to 00-00-5E-00-53-66
+  win_wakeonlan:
+    mac: 00-00-5E-00-53-66
+    port: 9
+  delegate_to: remote_system
+'''
+
+RETURN = r'''
+# Default return values
+'''

test/integration/targets/win_wakeonlan/aliases

@@ -0,0 +1 @@
+windows/ci/group2

test/integration/targets/win_wakeonlan/tasks/main.yml

@@ -0,0 +1,9 @@
+- name: Send a magic Wake-on-LAN packet to 00:00:5E:00:53:66
+  win_wakeonlan:
+    mac: 00:00:5E:00:53:66
+    broadcast: 192.0.2.255
+
+- name: Send a magic Wake-On-LAN packet on port 9 to 00-00-5E-00-53-66
+  win_wakeonlan:
+    mac: 00-00-5E-00-53-66
+    port: 9