go-wol

Wake on LAN magic packet generator for golang.

WOL in the world?

Wake-on-LAN (WOL) describes a simple data link layer protocol which tells a listening ethernet interface to power the target machine up.

Each target system typically exposes a setting in its BIOS which enables or disables the system's WOL capabilities (since this can slowly consume a small amount of standby power).

If you are looking for a tepid overview of the core components of this project in the form of a blog post: see here

Magic Packets (of what?)

The listening interface just looks for a Magic Packet with its MAC address encoded in the WOL scheme. The packet is basically 6 bytes of 0xFF followed by 16 repetitions of the destination interface's MAC address (102 bytes total). The Magic Packet does not have to be exactly 102 bytes, but its relevant payload is. This payload can be sandwiched anywhere in the broadcasts payload.

It's important to remember that since this is typically sent over the data link layer, the target machine's IP address is irrelevant.

Installation

go get github.com/sabhiram/go-wol/cmd/wol
wol wake 08:BA:AD:F0:00:0D

Usage

Valid commands include:

    {`wake`,   `wakes up a machine by mac address or alias`},
    {`list`,   `lists all mac addresses and their aliases`},
    {`alias`,  `stores an alias to a mac address`},
    {`remove`, `removes an alias or a mac address`},

With the following options (mostly apply to the wake command):

    {`v`, `version`,   `prints the application version`},
    {`h`, `help`,      `prints the help menu`},
    {`p`, `port`,      `udp port to send bcast packet to`},
    {`b`, `bcast`,     `broadcast IP to send packet to`},
    {`i`, `interface`, `outbound interface to broadcast using`},

Defaults

The default Broadcast IP is 255.255.255.255 and the UDP Port is 9. Typically the UDP port is either 7 or 9. The default interface is set to "" which tell the program to use any available interface.

Alias file

The alias file is typically stored in the user's Home directory under the path of ~/.config/go-wol/aliases. This is a very simple BoltDB which reads a per-alias Gob made up of a MAC address and an optional preferred outbound interface.

Supported MAC addresses

The following MAC addresses are valid and will match: 01-23-45-56-67-89, 89:0A:CD:EF:00:12, 89:0a:cd:ef:00:12

The following MAC addresses are not (yet) valid: 1-2-3-4-5-6, 01 23 45 56 67 89

CLI examples

Wake up a machine with mac address 00:11:22:aa:bb:cc:

wol wake 00:11:22:aa:bb:cc

Store an alias:

wol alias skynet 00:11:22:aa:bb:cc

Note that when waking up a machine, the wake command pretty much exists for clarity. You can safely omit it (unless your alias name is list, wake, alias or remove).

Wake up a machine using an alias:

wol wake skynet
wol skynet

View all aliases and corresponding MAC addresses:

wol list

Delete an alias:

wol remove skynet

Store an alias to a MAC using a default interface:

wol alias skynet 00:11:22:aa:bb:cc eth0

Specify a Broadcast Interface (Local to the sender):

wol wake skynet -i eth0

# or

wol wake skynet --interface eth0

Note that when specifying an interface to use, you can set that as part of the alias. However, if the -i option is specified, the specified interface will be used and the one in the alias map will be ignored.

Specify the Broadcast Port and IP:

wol wake 00:11:22:aa:bb:cc -b 255.255.255.255 -p 7

# or

wol wake skynet --bcast 255.255.255.255 --port 7

Tests

All commits and PRs will get run on TravisCI and have corresponding coverage reports sent to Coveralls.io.

To run the tests:

go test -v github.com/sabhiram/go-wol/...