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.
pull/25623/merge
Dag Wieers 7 years ago committed by Jordan Borean
parent a66bd8f7c3
commit 52c1a1936d

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

@ -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

@ -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
'''

@ -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
Loading…
Cancel
Save