regelneef/sleep-on-lan

Multi-platform process allowing to sleep on LAN a linux or windows computer, through wake-on-lan (reversed) magic packets or through HTTP REST requests.

Sleep-On-LAN (SOL)

Principle

Wake-on-LAN is a standard low-level protocol implemented in various hardware. At this time, there is not standard to make the opposite and send a computer in sleep mode.

This project allows a windows or linux box to be put into sleep from any other device.

It works with the exact same magic packet than for Wake-On-LAN, the only difference is that the MAC address has to be written in reverse order.

Technically, you have to run a little daemon on your computer that will listen the same Wake-On-LAN port and send the computer in sleep mode when the reversed MAC address received matches a local address.

Written in go, the code may run on linux and windows platforms.

Usage

Grab the latest windows + linux release : https://github.com/SR-G/sleep-on-lan/releases/

Sleep through UDP

Just send a regular wake-on-lan command but with a reversed MAC address. Thus, the same wake-on-lan tools may be used for both wake and sleep operations (python wake-on-lan script, OpenHab WoL plugin, Android applications, and so on).

Provided you are using a wake-on-lan script like this one wake-on-lan python script (available as a debian package for example), you may use :

wakeonlan c4:d9:87:7a:78:35 192.168.255.255 // regular mac address, will wake an asleep computer
wakeonlan 35:78:7a:87:d9:c4 192.168.255.255 // reversed mac address, will trigger the UDP listener of the sleep-on-lan process and will thus remotely sleep the computer

Sleep through REST service

If this HTTP listener is activated, the SleepOnLan process then exposes a few REST services, for example :

http://127.0.0.1:8009/                               // index page, just shows local IP / mac
http://127.0.0.1:8009/sleep                          // remotely sleep this computer through this URL
http://127.0.0.1:8009/wol/c4:d9:87:7a:78:35          // sends a wake-on-lan magic packet on the network to the provided mac address

Configuration

An optional configuration file may be used.

Taken automatically if named "sol.json" and located in the same folder than the SleepOnLan binary.

Content is as follow :

{
  "Listeners" : ["UDP:9", "HTTP:8009" ],
  "LogLevel" : "INFO",
  "BroadcastIP" : "255.255.255.255",
  "Commands" : []
}

Listeners defines which mechanism will be activated

• UDP : will listen on the default port (= 9)
• UDP:<port> : will listen on the provided port
• HTTP : will listen on the default port (= 8009)
• HTTP:<port> : will listen on the provided port

Several listeners may be defined (e.g., "UDP:7", "UDP:9", "HTTP:8009")

If no configuration file is provided, UDP:9 and HTTP:8009 are assumed by default.

The REST services are exposed on 0.0.0.0 and are thus accessibles from http://localhost/, http://127.0.0.1/, http://192.168.1.x/ and so on.

Rest service may be secured if needed through an optional Auth configuration (a Basic Auth is triggered on all REST services as soon as this Auth section is defined) :

{
  "Listeners" : ["UDP:9", "HTTP:8009" ],
  "Auth" : {
      "Login" : "myusername",
      "Password" : "mypassword"
  }
}

Authed REST may still be triggered from a remote host, if needed, through :

curl http://myusername:mypassword@<IP>/sleep/

Default output from REST command is XML but may be switched from a configuration point of view (by adding a HTTPOutput : 'JSON') or on a per-request basis (by adding a ?format=JSON to the request, one would retrieve a JSON result).

LogLevel defines the log level to use. Available values are NONE|OFF, DEBUG, INFO, WARN|WARNING, ERROR. Logs are just written to the stderr/stdout outputs.

BroadcastIP defines the broadcast IP used by the /wol service. By default the IP used is 192.168.255.255 (local network range).

Commands defines the available commands.

By default, on both windows and linux, only one command is defined : sleep command (through "pm-suspend" on linux and a DLL API call on windows).

You may customize / override this behavior, or add new commands (that will then be available under http://<IP>:<HTTP PORT>/<operation> if a HTTP listener is defined), if needed.

Each command has 4 attributes :

• "Operation" : the name of the operation (for the HTTP url)
• "Type" : the type of the operation, either "external" (by default, for remote execution) or "internal-dll" (on windows, to trigger a sleep through a DLL API call)
• "Default" : true or false. Default command will be executed when UDP magic packets are received. If only one command is defined, it will automatically be the default one
• "Command" : for external commands, the exact command that has to be executed (see examples below). May have to contain full path on windows.

Example 1 : only one (default) operation that will shutdown the system on windows. Through HTTP, the operation will be triggerable with http://<IP>:<PORT_HTTP>/halt/.

  "Commands" : [ 
    {
        "Operation" : "halt",
        "Command" : "C:\\Windows\\System32\\Shutdown.exe -s -t 0"
    }]

Example 2 : force sleep on windows through the rundll32.exe trick (and not through the default API call)

  "Commands" : [ 
    {
        "Operation" : "sleep",
        "Command" : "C:\\Windows\\System32\\rundll32.exe powrprof.dll,SetSuspendState 0,1,1"
    }]

Example 3 : default operation will put the computer to sleep on linux and a second operation will be published to shutdown the computer through HTTP.

  "Commands" : [ 
    {
        "Operation" : "halt",
        "Command" : "pm-halt",
		"Default" : "false"
    },
    {
        "Operation" : "sleep",
        "Command" : "pm-sleep",
		"Default" : "true"
    }]

Installation

Under windows

The SleepOnLan process may be run manually or, for convenience, installed as a service. The easiest way to install the SleepOnLan service is probably to use NSSM (the Non-Sucking Service Manager).

Usage :

nssm install <service name> <full path to binary>

Installation example :

c:\Tools\nssm\2.24\win64\nssm.exe install SleepOnLan c:\Tools\SleepOnLan\sol.exe

Removal example :

c:\Tools\nssm\2.24\win64\nssm.exe remove SleepOnLan confirm

Reference : nssm

Under Linux

The SleepOnLan process must use (usually) port 9 (see configuration section if you need another port or if you need to listen to several UDP ports).

Thus the process has either to be ran as root, either has to have the authorization to start on ports < 1024.

The following example allows the process to run on ports < 1024 on recent Linux kernels (for example on ubuntu) :

sudo setcap 'cap_net_bind_service=+ep' /path/to/sol_binary
nohup /path/to/sol_binary > /var/log/sleep-on-lan.log 2>&1 &

You may of course daemonize the process or launch it through an external monitor (like monit or supervisor).

Miscellaneous

Standalone sleep on lan under windows

Another way to sleep a windows computer remotely :

net rpc SHUTDOWN -f -I xxx.xxx.xxx.xxx -U uname%psswd

Other similar projects

• Sleep On Lan (pure java implementation, magic anti-packet starts with 6 * 0x00 instead of 6 * 0xFF)

OpenHab configuration

Example of configuration under OpenHab.

This is a very standard configuration : MAC addresses have just to be reversed.

Switch  Network_WoL_Solaris   	"Wake PC (solaris)"   		(WoL, Status, Network)   { wol="192.168.8.255#14:da:e9:01:98:19" }
Switch  Network_WoL_Jupiter   	"Wake PC (jupiter)"   		(WoL, Status, Network)   { wol="192.168.8.255#bc:5f:f4:2b:df:26" }
Switch  Network_WoL_Laptop   	"Wake PC (laptop)"    		(WoL, Status, Network)   { wol="192.168.8.255#C4:D9:87:7A:78:35" }

Switch  Network_SoL_Solaris   	"Sleep PC (solaris)"  		(WoL, Status, Network)   { wol="192.168.8.255#19:98:01:e9:da:14" }
Switch  Network_SoL_Laptop   	"Sleep PC (laptop)"   		(WoL, Status, Network)   { wol="192.168.8.255#35:78:7A:87:D9:C4" }

Developement

Compile from docker (from host) :

make docker

Create binaries (from docker container) :

make install

Create distribution (from docker container) :

make distribution