A Wake on Lan application that dynamically wakes servers based on the status of a NUT UPS server using the Rego policy language.
Highlights • Overview • Getting Started • Usage • Contributing • Maintainers • Code of Conduct • Security
- 🌐 Lightweight API server to handle Wake on Lan requests
- 📦 Small Docker image size and low footprint
- 🥧 Can be run on a Raspberry Pi or other small computer
- 📝 Define dynamic rules using the Rego policy language
- 📦 Multi-arch Docker image can run on any platform
- ⚙️ CLI tool to manually wake a server
- 📡 Connect to multiple NUT servers and wake multiple servers
Click to expand: ✍️ You can verify the Docker images were built from this repository using the cosign tool.
cosign verify docker.io/thedarthmole/upswake:latest \
--certificate-identity-regexp https://github.com/TheDarthMole/upswake/ \
--certificate-oidc-issuer https://token.actions.githubusercontent.comcosign verify ghcr.io/thedarthmole/upswake:latest \
--certificate-identity-regexp https://github.com/TheDarthMole/upswake/ \
--certificate-oidc-issuer https://token.actions.githubusercontent.com[!NOTE] This only proves that the Docker image is from this repository, assuming that no one hacks into GitHub or the repository. It does not prove that the code itself is secure.
UPSWake is an application that allows you to dynamically wake servers using Wake on Lan based on the status of a NUT UPS server.
The OPA Rego language is used in order to allow for dynamic rules to be defined for when to wake a server. The status of one or more NUT UPS servers is checked against the defined rules and if the rules are met, a Wake on Lan packet is sent to the defined server.
UPSWake is designed to run on a Raspberry Pi or any small, always-on computer that shares the same network as the servers you want to wake. It is ideal for environments where the servers are set to shut down using the NUT client when the UPS switches to battery power, as UPSWake provides the capability to wake them back up using intelligent rules.
Create a config.yaml file in the same directory as the application.
If a config is not provided, the application will attempt to create a default config.
nut_servers:
- name: raspberrypi
host: 192.168.13.37
port: 3493
username: upsmon
password: bigsecret
targets:
- name: MyNAS
mac: "01:23:45:67:89:01"
broadcast: 192.168.13.255
port: 9
interval: 5s
rules:
- 80percentOn.rego
- name: Gaming PC
mac: "10:98:76:54:32:01"
broadcast: 192.168.13.255
port: 9
interval: 15m
rules:
- alwaysTrue.regoThe above config allows for a flexible configuration where you can define multiple NUT hosts and multiple target hosts. Multiple rules can also be defined for each server to be woken. YAML anchors can be used if the same NUT client is used for multiple servers.
Note
The Rego rules are evaluated in a logical OR fashion. If any of the rules evaluate to true, the host will be woken.
Rules are stored and read from the rules folder and are written in the OPA Rego language. The example rule 80percentOn.rego will wake the server if the UPS named "cyberpower900" is on line power and the battery level is above 80%.
services:
upswake:
# Choose the appropriate tag based on your need:
# - "latest" for the latest stable version (which could become 2.x.y in the future and break things)
# - "edge" for the latest development version running on the default branch
# - "1" for the latest stable version whose major version is 1
# - "1.x" for the latest stable version whose major.minor version is 1.x
# - "1.x.y" to pin the specific version 1.x.y
image: thedarthmole/upswake:latest
# image: ghcr.io/thedarthmole/upswake:latest # Use this if you prefer the GitHub Container Registry
container_name: upswake
# Required to allow the container to access the host's network interface to send Wake-on-LAN packets
network_mode: host
# Restart the container automatically after reboot
restart: always
# Run the application as a non-root user (optional but recommended)
# Change the user and group IDs based on your needs
user: "1000:1000"
# Make the container filesystem read-only (optional but recommended)
read_only: true
# Drop all Linux capabilities (optional but recommended)
cap_drop: [ all ]
# Another protection to restrict superuser privileges (optional but recommended)
security_opt: [no-new-privileges:true]
command: ["serve"]
# Mount the configuration file and the rules folder as read-only volumes
volumes:
- "./config.yaml:/config.yaml:ro" # upswake will create a config if one doesn't exist, you may want to remove the ':ro' in that case
- "./rules/:/rules/:ro"docker compose up --detach --pull always --force-recreateClick to expand: 🐋 Directly run the Docker image
docker run \
--network host \
-v ${PWD}/config.yaml:/config.yaml:ro \
-v ${PWD}/rules:/rules/:ro \
--name upswake \
thedarthmole/upswake:latestNote: The
--network hostflag is required to allow the container to access the host's network interface to send Wake-on-LAN packets.
Click to expand: 🧬 Directly install UPSWake from its source
You need the Go tool to run UPSWake from its source.
go install github.com/TheDarthMole/UPSWake/cmd/upswake@latestClick to expand: 🏗️ Build UPSWake from its source
You need the Go tool to build UPSWake from its source.
git clone git@github.com:TheDarthMole/upswake.git
cd upswake
go build -o upswake ./cmd/upswakeUsage:
upswake [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
help Help about any command
json Retrieve JSON from a NUT server
serve Run the UPSWake server
wake Manually wake a computer
Flags:
-h, --help help for upswake
Use "upswake [command] --help" for more information about a command.
For information about contributing to UPSWake, please read the CONTRIBUTING.md and MAINTAINERS.md docs.
