From 05fbfe6af42320d7baffe056fcb6216140db10d4 Mon Sep 17 00:00:00 2001 From: Asif Bacchus Date: Sat, 4 Sep 2021 19:13:23 -0600 Subject: [PATCH] docs(readme): proofread and update readme --- README.md | 60 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 41 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index b438160..f81185c 100644 --- a/README.md +++ b/README.md @@ -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 @@ Send-MagicPacket '1a:2b:3c:4d:5e:aa', 'a1-b2-c3-d4-e5-bb', '1a:2b-3c:4d-5e-cc' 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 @@ WOL packets. If broadcast is not working in your environment, you may want to tr 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 @@ queries and allows this function to be easily called using piped output from suc 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. \ No newline at end of file +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! \ No newline at end of file