diff --git a/CHANGELOG.md b/CHANGELOG.md index a3706d379b..1ff40de9d9 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/lib/ansible/modules/windows/win_wakeonlan.ps1 b/lib/ansible/modules/windows/win_wakeonlan.ps1 new file mode 100644 index 0000000000..de40c32af2 --- /dev/null +++ b/lib/ansible/modules/windows/win_wakeonlan.ps1 @@ -0,0 +1,62 @@ +#!powershell +# This file is part of Ansible +# +# (c) 2017, Dag Wieers +# +# 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 . + +# 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 diff --git a/lib/ansible/modules/windows/win_wakeonlan.py b/lib/ansible/modules/windows/win_wakeonlan.py new file mode 100644 index 0000000000..4e43e70ac7 --- /dev/null +++ b/lib/ansible/modules/windows/win_wakeonlan.py @@ -0,0 +1,70 @@ +#!/usr/bin/python +# -*- coding: utf-8 -*- + +# (c) 2017, Dag Wieers +# +# 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 . + +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 +''' diff --git a/test/integration/targets/win_wakeonlan/aliases b/test/integration/targets/win_wakeonlan/aliases new file mode 100644 index 0000000000..ee0ed5974e --- /dev/null +++ b/test/integration/targets/win_wakeonlan/aliases @@ -0,0 +1 @@ +windows/ci/group2 diff --git a/test/integration/targets/win_wakeonlan/tasks/main.yml b/test/integration/targets/win_wakeonlan/tasks/main.yml new file mode 100644 index 0000000000..169362b002 --- /dev/null +++ b/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