[PowerShell] Wake on LAN (WOL) and Packet Broadcast to Remote Machine

README.md

PSWakeOnLan PowerShell Module

PSWakeOnLan.psm1 contains the functions below:

• Get-MACAddress:
  • Retrieve the MAC Address for the Local or a Remote Machine via Get-WmiObject.
• Test-MACAddress:
  • Tests the format of a MAC Address, ensuring its syntax is proper.
• New-WOLMagicPacket:
  • Creates a new "magic" packet
    • See Wake-on-LAN | Magic Packet (wikipedia.com)
    • The packet broadcasts the payload with 6 bytes of all 255 (FF FF FF FF FF FF in Hexadecimal) followed by sixteen repetitions of the target machine's 48-bit MAC Address, totaling 102 bytes.
• Invoke-WakeComputer:
  • Invokes WOL on target machine by creating a .NET UDP Client, Connecting via Broadcast, and Sending the Packet.

---

This solution composed two steps:

• Identify and create a WOL packet based off of the target machine’s MAC Address
• Broadcast the WOL packet to the target machine’s subnet to wake the machine via the .NET [System.Net.Sockets.UdpClient] Class

Details

Wake On LAN (WOL) Packet

• Wake-on-LAN:

  • Wake-on-LAN (WOL) “Magic” Packet is defined as a byte array with six bytes of value 255 (0xFF) and sixteen repetitions of the target machine’s 48-bit (6-byte) MAC Address.
  • Wake-on-LAN works by broadcasting the magic packet to all network devices in a network. The network device that has a matching MAC address is instructed to be woken up, should they be configured to handle Wake-on-LAN requests.

• Broadcasting:

  • The .NET UdpClient Object, is used here to broadcast the address and send the packet from step 1.
  • See UdpClient Class (System.Net.Sockets) | Microsoft Learn for details.

The magic packet is a broadcast frame containing anywhere within its payload 6 bytes of all 255 (FF FF FF FF FF FF in hexadecimal), followed by sixteen repetitions of the 48-bit MAC address of the target computer, for a total of 102 bytes.

Additional Considerations

• WakeMeOnLan - Turn on computers on your network with Wake-on-LAN packet (nirsoft.net)

The following wake patterns may be supported by a network adapter:

• Wake Pattern.
• Wake on new incoming TCP connection for IPv4 and IPv6 such as TCP SYN IPv4 and TCP SYN IPv6.
• 802.1x re-authentication packets.
• Bitmapped Patterns: Most network adapters can be programmed with bit-mapped pattern filters. Bitmapped patterns are defined by a bit-map mask and a pattern filter. As a network packet is received, it is masked using the bitmap mask and then compared to the pattern filter. If there is a match, then the network adapter wakes the computer.

The built-in Windows PowerShell module NetTCPIP has a function Set-NetIpInterface with an argument -DirectedMacWolPattern that can be used to specify the wake-up packet value for an IP interface. The -DirectedMacWolPattern argument’s value determines if an IP interface is configured to wake up a computer with directed MAC packet patterns. Acceptable values are Enabled or Disabled with Disabled being the default.

The Set-NetAdapterPowerManagement and Enable-NetAdapterPowerManagement cmdlets from the NetAdapter Module have arguments for -WakeOnPattern and -WakeOnMagicPacket:

• WakeOnMagicPacket
  • Specifies the wake on magic packet capability of the network adapter.
  • The magic packet is a broadcast frame containing anywhere within its payload 6 bytes of all 255 (FF FF FF FF FF FF in hexadecimal), followed by sixteen repetitions of the 48-bit MAC address of the target computer, for a total of 102 bytes.
• WakeOnPattern
  • Manages the wake on pattern capability of the network adapter.
  • A wake pattern refers to network packet filters that determine if incoming network traffic should wake the computer. These patterns can be enabled on the network adapter.

Windows Configuration Manager (Intune) and its ConfigurationManager PowerShell module could also be used to apply WOL configurations:

The cmdlet Set-CMClientSettingPowerManagement provides WOL specific arguments:

• -EnableWakeupProxy
• -FirewallExceptionForWakeupProxy
• -NetworkWakeupOption (Use this parameter to enable or disable the client setting, Allow network wake-up)
• -WakeOnLanPort
• -WakeupProxyDirectAccessPrefix
• -WakeupProxyPort

For non-PowerShell Configuration Management see Configure Wake on LAN - Configuration Manager | Microsoft Learn:

PSWakeOnLan.psm1

Function Get-MACAddress {
    Param(
        [Switch]$Local,
        [String]$ComputerName
    )

    if ($Local) {
        $MACAddress = Get-WmiObject -Class Win32_NetworkAdapterConfiguration -Filter "IPEnabled = 'True'" | Select-Object -ExpandProperty MACAddress
    } else {
        $MACAddress = Get-WmiObject -Class Win32_NetworkAdapterConfiguration -Filter "IPEnabled = 'True'" -ComputerName $ComputerName | Select-Object -ExpandProperty MACAddress
    }

    Write-Output $MACAddress

}

Function Test-MACAddress {
    Param(
        [String]$MACAddress
    )

    if (($MACAddress -notlike '*:*:*:*:*:*') -and ($MACAddress -notlike '*-*-*-*-*-*')) {
        Write-Warning 'Invalid MAC Address'
        return $false
    } else {
        Write-Host 'Valid MAC Address' -ForegroundColor Green
        return $true
    }

}

Function New-WOLMagicPacket {
    Param(
        [String]$MACAddress
    )

    $String = @(
        $MacAddress.Split(':') | ForEach-Object { [Byte]('0x' + $_) } # $_.Insert(0,"0x") }
    )

    $Packet = [Byte[]](, 0xFF * 6)
    $Packet += $String * 16

    return $Packet

}

Function Invoke-WakeComputer {
    Param(
        [String]$MACAddress
    )

    Begin {
        
        if (-not(Test-MACAddress -MACAddress $MACAddress)) {
            return
        }

        $Packet = New-WOLMagicPacket -MACAddress $MACAddress

        $UDPClient = New-Object System.Net.Sockets.UdpClient
    }

    Process {

        $UDPClient.Connect(([System.Net.IPAddress]::Broadcast), 4000)
        [Void] $UDPClient.Send($Packet, $Packet.Length)
        Write-Host "Wake-On-Lan magic packet sent to $MACAddress (Length of Packet: $($Packet.Length))"

    }

    End {
        $UDPClient.Close()
    }
}