eneru 5.4.0

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. The OCI image is for remote UPS monitoring and SSH shutdown. Use a native host install when Eneru must manage the local host, VMs, containers, or filesystems.

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 for remote-only Docker, Podman, and Kubernetes deployments
• 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

---

Systemd daemon and OCI image

Eneru still works best as a native systemd daemon when it owns the local host shutdown sequence: stopping local VMs, stopping local Docker/Podman containers, syncing filesystems, and powering off the machine.

v5.4 adds an official OCI image for remote-only Docker, Podman, and Kubernetes deployments. Use it when Eneru monitors NUT, exposes API/health endpoints, publishes telemetry, and shuts down remote systems over SSH. Do not use the image for local-host ownership; install Eneru on the host instead.

See the container documentation for Docker, Podman, SELinux/AppArmor, and Kubernetes examples.

---

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.