thedarthmole/upswake

🌟 UPSWake

https://github.com/TheDarthMole/upswake/actions/workflows/build.yml/badge.svg](https://github.com/TheDarthMole/upswake/actions/workflows/build.yml) https://github.com/TheDarthMole/upswake/actions/workflows/test.yml/badge.svg](https://github.com/TheDarthMole/upswake/actions/workflows/test.yml) https://goreportcard.com/badge/github.com/TheDarthMole/UPSWake](https://goreportcard.com/report/github.com/TheDarthMole/UPSWake) https://img.shields.io/github/license/TheDarthMole/UPSWake?color=blue](LICENSE) https://img.shields.io/docker/image-size/thedarthmole/upswake/latest](https://hub.docker.com/r/thedarthmole/upswake) https://img.shields.io/docker/pulls/thedarthmole/upswake](https://hub.docker.com/r/thedarthmole/upswake) https://www.bestpractices.dev/projects/***/badge](https://www.bestpractices.dev/projects/***) https://codecov.io/github/TheDarthMole/upswake/graph/badge.svg?token=B23QF8JDVJ](https://codecov.io/github/TheDarthMole/upswake) https://app.fossa.com/api/projects/git%2Bgithub.com%2FTheDarthMole%2Fupswake.svg?type=shield](https://app.fossa.com/projects/git%2Bgithub.com%2FTheDarthMole%2Fupswake?ref=badge_shield)

A dynamic Wake on Lan application that wakes servers based on the status of a NUT UPS server using the Rego policy language.

📜 Highlights

⚡ Efficiency

• 🌐 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

🛠️ Flexibility

• 📝 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

🛡️ Attention to Security

bash
cosign verify thedarthmole/upswake:latest \
    --certificate-identity-regexp https://github.com/TheDarthMole/upswake/ \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com

bash
cosign verify ghcr.io/thedarthmole/upswake:latest \
    --certificate-identity-regexp https://github.com/TheDarthMole/upswake/ \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com

🔍 Overview

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 many 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 https://www.raspberrypi.org/ 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.

🏎️ Getting Started

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.

yaml
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.rego

The 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%.

🐋 Deployment with Docker Compose

yaml
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"

🚀 Start the application

bash
docker compose up --detach --pull always --force-recreate

⛷️ Other Installation Methods

Usage

CODE_TOKEN_8

Development

This project uses https://go.dev/, https://github.com/casey/just and your choice of https://www.docker.com/ or https://podman.io/ for development. To install other dependencies, build or run the application, you can use the just tool to run the commands defined in the justfile.

just -l
Available recipes:
    build            # Build upswake
    build-container  # Build the thedarthmole/upswake:local container
    help             # Display this help message
    install-deps     # Install development dependencies
    lint             # Runs all linters
    run *args        # Run upswake with arguments
    run-container    # Builds and runs the upswake container
    start-nut-server # Runs a NUT server in a container for testing
    stop-nut-server  # Stops the NUT server container
    swagger          # Generate Swagger documentation
    test             # Run all Go tests

For more information about contributing to UPSWake, please read the CONTRIBUTING.md and MAINTAINERS.md docs.

License

https://app.fossa.com/api/projects/git%2Bgithub.com%2FTheDarthMole%2Fupswake.svg?type=large](https://app.fossa.com/projects/git%2Bgithub.com%2FTheDarthMole%2Fupswake?ref=badge_large)