asif/ps-cmdlet-wol
1
0
Fork 0
Code Issues Pull Requests Releases 3 Activity

docs(readme): proofread and update readme

Browse Source
This commit is contained in:
Asif Bacchus 2021-09-04 19:13:23 -06:00
parent f2901b6c80
commit 05fbfe6af4
1 changed files with 41 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
README.md
View File

@ -1,27 +1,27 @@
# PowerShell cmdlet: Send Magic Packet
PowerShell cmdlet (module/function) to send a *magic packet* based on a provided MAC address. Comment-based help
included in source-code: `Get-Help Send-MagicPacket -Full`
PowerShell cmdlet (module/function) to send a *magic packet* based on provided MAC address(es). Comment-based help is
included in the source-code: `Get-Help Send-MagicPacket -Full`
## Installation and Verification
## Installation and verification
Downloads are available
via [my git server (https://git.asifbacchus.dev/asif/ps-cmdlet-wol)](https://git.asifbacchus.dev/asif/ps-cmdlet-wol)
and [GitHub (https://github.com/asifbacchus/ps-cmdlet-wol)](https://github.com/asifbacchus/ps-cmdlet-wol). You may
verify the cmdlet's integrity using [CodeNotary](https://codenotary.io) `vcn authenticate` or by dropping the downloaded
script onto their verification webpage at [https://verify.codenotary.io](https://verify.codenotary.io). Please always
try to verify downloaded scripts and software regardless of the source!
verify the cmdlet's integrity using [CodeNotary](https://codenotary.io) via `vcn authenticate` or by dropping the
downloaded script onto their verification webpage at [https://verify.codenotary.io](https://verify.codenotary.io).
Please always try to verify downloaded scripts and software regardless of the source!
## Overview
The function sends two (2) magic packets spaced one (1) second apart. One set of magic packets will be sent per MAC
address submitted either directly via the `MacAddress` parameter or via the pipeline (implicitly or explicitly). Usage
examples provided via `Get-Help Send-MagicPacket -Examples`.
examples are provided via `Get-Help Send-MagicPacket -Examples`.
The only mandatory parameter is `MacAddress` which can be provided directly or via the pipeline either implicitly or
explicitly (parameter is in the first position). `MacAddress` is an *array of strings*. The actual hex values of the MAC
address can be separated with either a ':' or '-'. For example, the following MAC addresses are all valid even within
the same command:
address can be separated with a colon (':') and/or a hyphen ('-'). For example, the following MAC addresses are all
valid even within the same command:
```powershell
Send-MagicPacket '1a:2b:3c:4d:5e:aa', 'a1-b2-c3-d4-e5-bb', '1a:2b-3c:4d-5e-cc'
@ -30,8 +30,9 @@ ## Overview
By default, the magic packet will be sent on the global broadcast address for your current system (e.g. 255.255.255.255)
using UDP on the *echo* port (7). These options can be customized via parameters:
- `-BroadcastIP` | `IP` | `Address`: Broadcast address to use. By default, this is 255.255.255.255 but you really shuold
use a subnet specific broadcast address instead (e.g. 192.168.1.255). See Broadcast section for more discussion.
- `-BroadcastIP` | `IP` | `Address`: Broadcast address to use. By default, this is 255.255.255.255 but you really should
use a subnet specific broadcast address instead (e.g. 192.168.1.255). See
the [Broadcast considerations](#broadcast-considerations) section for more discussion.
- `Port`: Allows changing the UDP port over which the magic packet is sent. This is by default port 7 (echo). Port 9 (
discard) is also quite common but any port can be used depending on your particular environment.
@ -53,8 +54,8 @@ ## Broadcast considerations
Things become a little more complicated with IP6. There is no concept of 'broadcast' in IP6 and thus, you need to use
multicast. I have not extensively tested IP6 WOL since I tend to continue using IP4 for this purpose (all my networks
are dual-stack). I would assume the simplest place to start testing would be using the link-local all-nodes address
of **ff02::1**. I suspect this should work especially on Windows networks, but I have not really tested this extensively
and could be greatly impacted by switches, routers and even machine specific set-ups.
of **ff02::1**. I suspect this should work across most networks, but I have not tested it extensively and it would
depend greatly on switches, routers and even machine specific set-ups.
## Pipeline
@ -64,23 +65,44 @@ ## Pipeline
dummy magic packets to the localhost for all interfaces on the local machine:
```powershell
# get name, manufacturer and MAC address for connected interfaces and pipe to
# get name, manufacturer and MAC address for connected interfaces and pipe to our function
Get-CimInstance -Query "Select * From Win32_NetworkAdapter Where NetConnectionStatus=2" | Select-Object Name, Manufacturer, MacAddress | Send-MagicPacket -IP 127.0.0.1 -Verbose
```
You will see the function picks up the `MacAddress` of each object (network interface) and sends a magic packet to
127.0.0.1 on port 7 (echo). This is not at all useful, but demonstrates pipeline usage quite nicely, I think.
You will notice I've selected stuff we don't need (Name, Manufacturer) to show that the function can parse and pick up
named the `MacAddress` of each object (network interface) and then send a magic packet to 127.0.0.1 on port 7 (echo).
This is not at all useful, but demonstrates pipeline usage quite nicely, I think. A simpler demonstration would be the
following:
```powershell
# send magic packets to two machines over IP4 localhost using port 9 (discard)
'1a:2b:3c:4d:5e:aa', 'a1:b2:c3:d4:e5:bb' | Send-MagicPacket -BroadcastIP 127.0.0.1 -Port 9
```
## Module or Function
This was intended to be used as a simple function that can be integrated into other scripts directly or, more
conveniently, loaded as a module and referenced as needed in a variety of use-cases.
If using as a function, simply place it within your script. If you want to load it as a module either `Load-Module`
within your script or do so at a PS prompt:
```powershell
# load module
Load-Module C:\path\to\module\wol-magicPacket.psm1
# call module anytime after loading within the same session
Send-MagicPacket ...
```
## Feedback
I coded this pretty quickly for a project I was working on in a small LAN deployment. I also use it pretty routinely in
I coded this pretty quickly for a project I was working on in a small LAN deployment. I also use it routinely in
networks of various sizes and over VPN connections and also when I'm too lazy to move from my office to the living room
to turn on my media centre. I'm always interested in improvements since I don't code in PowerShell that often and I'm
to turn on my media centre. I've polished it up and added comment-based help for the version in this repo, hence the
more recent creation date. I'm always interested in improvements since I don't code in PowerShell that often and I'm
sure this can be vastly improved. Please send any suggestions, bugs, etc. to me by filing an issue.
I hope you find this useful! As indicated by the license, you can use this code for whatever you want in any capacity.
If you do use it, a link to my blog at [https://mytechiethoughts.com](https://mytechiethoughts.com) would be greatly
appreciated!