eneru 5.5.1

Intelligent UPS Monitoring & Shutdown Orchestration for NUT

⚡ Eneru

UPS monitoring and shutdown orchestration for NUT

A Python-based UPS monitoring daemon for Network UPS Tools (NUT). Monitors one or more UPSes, orchestrates shutdown of VMs, containers, and remote servers during power events, and exposes read-only API, Prometheus, MQTT, and Grafana observability.

Documentation • Getting Started • Configuration • Changelog • Roadmap

---

Why Eneru?

Most UPS shutdown tools handle one machine. If you have more than one, things get complicated fast:

Challenge	Eneru Solution
Multiple UPSes powering different servers	✅ Multi-UPS monitoring from a single instance
Multiple servers need coordinated shutdown	✅ Orchestrated multi-server shutdown via SSH
VMs and containers need graceful stop	✅ Libvirt VM and Docker/Podman container handling
Network mounts hang during power loss	✅ Timeout-protected unmounting
No visibility during power events	✅ Real-time TUI dashboard + notifications via 100+ services
Different systems need different commands	✅ Per-server custom shutdown commands
Hypervisors need VM shutdown before host	✅ Pre-shutdown actions (Proxmox, ESXi, XCP-ng, libvirt)
Battery estimates are unreliable	✅ Multi-vector shutdown triggers
Network down during outage	✅ Non-blocking notifications with persistent retry
Firmware recalibrates battery silently	✅ Battery anomaly detection and alerts
Need power-quality telemetry	✅ API, Prometheus, MQTT, Grafana, JSON logs, and SQLite events

---

How Eneru is different

NUT's upsmon shuts down one machine with two triggers (low battery, forced shutdown). apcupsd does the same for APC hardware. PeaNUT and NUTCase provide dashboards but no shutdown logic. Enterprise tools (Eaton IPM, PowerChute) add virtualization support but are vendor-locked and proprietary.

Eneru sits on top of NUT and adds what these tools lack:

• Orchestrated multi-resource shutdown, VMs, compose stacks, containers, remote servers, filesystems, and local system in a coordinated sequence
• 6 independent shutdown triggers, including depletion rate (computed from observed battery data, not UPS estimates) and extended time on battery. NUT's 2 triggers miss these failure modes
• Multi-UPS coordination, monitor multiple UPSes with per-group triggers and shutdown policies, each with independent failure handling
• Battery anomaly detection, catches firmware recalibrations and battery degradation with vendor-specific jitter filtering (APC, CyberPower, Ubiquiti)

See the full comparison in the documentation.

---

Use cases

Homelabs, virtualization hosts (Proxmox, ESXi, libvirt), Docker/Podman container hosts, NAS systems (Synology, QNAP, TrueNAS), multi-UPS environments with multiple server groups, and mixed physical/virtual setups.

---

Quick start

Installation

Docker / Podman:

docker pull ghcr.io/m4r1k/eneru:latest

docker run -d --name eneru \
  --restart unless-stopped \
  -p 9191:9191 \
  -v /srv/eneru/config.yaml:/etc/ups-monitor/config.yaml:ro \
  -v /srv/eneru/state:/var/lib/eneru \
  -v /srv/eneru/run:/var/run/eneru \
  -v /srv/eneru/ssh:/var/lib/eneru/ssh:ro \
  ghcr.io/m4r1k/eneru:latest \
  run --config /etc/ups-monitor/config.yaml \
  --api --api-bind 0.0.0.0 --api-port 9191

Use ghcr.io/m4r1k/eneru:testing for pre-release builds. v5.5+ makes the OCI image first-class for both remote-only and local-host deployments — for full local-host ownership from a container (host poweroff, VM teardown, container stop, filesystem unmount), add --network host, -v /etc/machine-id:/etc/machine-id:ro, and a loopback SSH key. See Choose your install for the three deployment profiles and Migrate to container for the step-by-step.

PyPI:

pip install eneru[notifications]

Debian/Ubuntu:

curl -fsSL https://m4r1k.github.io/Eneru/KEY.gpg | sudo gpg --dearmor -o /usr/share/keyrings/eneru.gpg
echo "deb [arch=all signed-by=/usr/share/keyrings/eneru.gpg] https://m4r1k.github.io/Eneru/deb stable main" | sudo tee /etc/apt/sources.list.d/eneru.list
sudo apt update && sudo apt install eneru

RHEL/Fedora:

sudo dnf install -y epel-release
sudo curl -o /etc/yum.repos.d/eneru.repo https://m4r1k.github.io/Eneru/rpm/eneru.repo
sudo dnf install eneru

Configuration

# Edit configuration
sudo nano /etc/ups-monitor/config.yaml

# Validate and start
eneru validate --config /etc/ups-monitor/config.yaml
sudo systemctl enable --now eneru.service

# Monitor in real time
eneru monitor --config /etc/ups-monitor/config.yaml

Single UPS

ups:
  name: "UPS@192.168.1.100"
  display_name: "Main UPS"

triggers:
  low_battery_threshold: 20
  critical_runtime_threshold: 600

local_shutdown:
  enabled: true

Multiple UPSes

ups:
  - name: "UPS1@192.168.1.10"
    display_name: "Rack A UPS"
    is_local: true
    remote_servers:
      - name: "Proxmox Node"
        enabled: true
        host: "192.168.1.20"
        user: "root"

  - name: "UPS2@192.168.1.11"
    display_name: "Rack B UPS"
    remote_servers:
      - name: "NAS"
        enabled: true
        host: "192.168.1.30"
        user: "admin"

See the full documentation for complete configuration options.

---

Features

• Monitor one or more UPSes from a single instance, each with its own shutdown group
• Real-time TUI dashboard (eneru monitor) with color-coded status
• Shutdown triggers: battery %, runtime, depletion rate, time on battery, FSD flag
• Battery anomaly alerts for unexpected charge drops while on line power, with jitter filtering for APC, CyberPower, and Ubiquiti UniFi UPS units
• Shuts down VMs, containers, remote servers, filesystems, and the local system in order
• Notifications to 100+ services (Discord, Slack, Telegram, ntfy, email) via Apprise
• Power quality monitoring: voltage, AVR, bypass, overload
• Read-only API, Prometheus metrics, outbound MQTT, JSON/syslog logs, and Grafana dashboard
• Official OCI image — first-class for both remote-only deployments AND full local-host ownership via SSH loopback delegate (v5.5+)
• Dry-run mode for safe testing
• Comprehensive test suite across multiple Linux distros, with E2E tests against real NUT, SSH, Docker, and libvirt on every commit

---

Three deployment profiles

Install path	Local-host ownership	Remote systems	Recommended for
pip / deb / rpm (native)	First-class via systemd	Yes	Homelab, single-host professional, end-user-managed enterprise
OCI image (Docker / Podman)	First-class via SSH loopback delegate (v5.5+)	Yes	Homelab, professional, enterprise — the v5.5 default for containerized local-host
Kubernetes	Not recommended	Yes	Enterprise multi-site fleet monitoring of remote systems

v5.5 made the OCI image first-class for the local-host case: the container SSHes to the host it runs on so the namespace barrier doesn't block the host-poweroff contract. Pick by deployment preference, not capability.

See Choose your install for the full feature × install matrix and Containers and Kubernetes for Docker, Podman, SELinux/AppArmor, Kubernetes, and the SSH walkthrough.

---

The name

Named after Eneru (エネル) from One Piece, the self-proclaimed God of Skypiea who ate the Goro Goro no Mi (Rumble-Rumble Fruit) and can control electricity. When the power from the grid fails, this tool takes over and shuts everything down safely. Unlimited power... management!

---

Documentation

Full documentation at eneru.readthedocs.io:

• Getting Started - installation and basic setup
• Configuration - full config reference
• Shutdown Triggers - how shutdown decisions work
• Notifications - Discord, Slack, Telegram, etc.
• Remote Servers - SSH setup for NAS and other servers
• Testing - testing strategy and coverage
• Troubleshooting - common issues and solutions

---

Support the project

Eneru is free and MIT-licensed and will stay that way. If it has saved your homelab or rack from a dirty shutdown and you'd like to chip in toward UPS hardware, NUT testing, and the maintainer's coffee budget, Buy Me a Coffee — always optional, much appreciated.

---

License

MIT License - See LICENSE file for details.