nutcracker

A deterministic UPS-aware shutdown orchestrator for Proxmox environments.

nutcracker is a small systemd daemon that continuously evaluates UPS state via NUT and performs staged, dependency-aware VM shutdown when power loss occurs. Unlike traditional LOWBATT triggers, nutcracker makes runtime-aware decisions and executes a controlled drain sequence to minimize infrastructure disruption.

The project focuses on predictable behavior, restart safety, and operational reliability rather than simple shutdown automation.

---

Version

Current version: 1.1.0

---

Changelog

v1.1.0

• Added stage transition reason logging
• Added outage duration reporting
• Added VM shutdown event logging
• Added health status file
• Added OL debounce protection

v1.0.0

• Initial release
• Deterministic shutdown state machine

---

Core behavior

• Deterministic shutdown state machine
• Dependency-aware VM shutdown ordering
• Graceful → force escalation logic
• UPS runtime-based decision making
• Persistent state recovery after restart
• Restart-safe execution model
• UPS communication failure tolerance
• Minimal runtime footprint
• systemd-native operation

---

Observability

• Stage transition reason logging
• Outage duration reporting
• VM shutdown event logging
• Health status file (/run/nut/nutcracker.health)
• Power restoration debounce protection

---

Architecture

nutcracker operates as a simple deterministic state machine:

NORMAL
  ↓
OUTAGE TIMER
  ↓
GRACEFUL (ordered VM shutdown)
  ↓
FORCE (cleanup remaining VMs)
  ↓
HOST (final cleanup + shutdown)

---

State overview

NORMAL System operating normally.

OUTAGE TIMER Power loss detected. Waiting grace delay to avoid unnecessary shutdown from short outages.

GRACEFUL Ordered VM shutdown:

• Dependent VMs first
• Infrastructure VMs last
• Progressive shutdown queue

FORCE Remaining VMs forcibly stopped to preserve battery margin.

HOST Final VM sweep and host shutdown.

---

Design principles

nutcracker was designed around reliability and predictable behavior:

• Deterministic state transitions
• No duplicate shutdown requests
• Restart-safe operation
• Battery-aware decisions
• Dependency-aware VM ordering
• Minimal external dependencies
• Fail-safe behavior on UPS communication loss
• Clear operational logging for incident analysis
• Deterministic failure behavior
• Observability-first design

---

Requirements

Required:

• Proxmox VE or Debian-based Linux
• Network UPS Tools (NUT) installed and configured
• systemd
• Root privileges

Recommended:

• NUT polling interval ≤ 2 seconds
• QEMU guest agent installed in VMs
• Proper VM dependency mapping

---

Setup

Clone repository:

git clone https://github.com/world-wide-dev/nutcracker.git

cd nutcracker

Install:

chmod +x ./install.sh
sudo ./install.sh

Enable service:

systemctl enable nutcracker
systemctl start nutcracker

Check status:

systemctl status nutcracker
journalctl -t nutcracker -f

---

Configuration

nutcracker reads VM shutdown ordering from:

/etc/nut/nutcracker.conf

Example:

DEP_VMS="101 102"
NON_DEP_VMS="103 104"

DEP_VMS

VMs depending on other services. Shut down first.

Examples: • Application servers • Frontend services • Workers

NON_DEP_VMS

Infrastructure VMs that other systems depend on. Shut down last.

Examples: • Storage • Databases • Authentication services • Network services

If configuration is empty, nutcracker shuts down all running VMs.

---

Operation model

nutcracker continuously polls UPS state using:

upsc ups@localhost

Decisions are based on:

• UPS status (OL / OB / LB)
• Remaining runtime
• Outage duration
• VM shutdown progress

Unlike standard NUT shutdown handling, nutcracker does not rely on LOWBATT triggers. Instead it continuously evaluates system state to allow staged shutdown decisions.

A runtime health snapshot is available at:

/run/nut/nutcracker.health

---

Tested scenarios

Tested against:

• Short outages (<30 seconds) • Multi-minute outages • Runtime threshold transitions • UPS communication loss • Service restart during shutdown • VM dependency ordering

---

Tested hardware

Tested with:

APC BX950MI-FR UPS

---

Notes

nutcracker intentionally runs as a standalone daemon rather than relying on NUT event hooks. This allows:

• Continuous state evaluation • Runtime-based decisions • Controlled escalation • Safer recovery behavior

Requires root privileges for VM and system operations.

AI-assisted tools were used for architecture discussion and troubleshooting. All design decisions and validation were performed during development.

---

Repository structure

nutcracker/
├── nutcracker.sh
├── nutcracker.conf.example
├── install.sh
├── uninstall.sh
├── systemd/
│   └── nutcracker.service
├── docs/
│   ├── design.md
│   └── state-machine.md
├── README.md
└── LICENSE

---

Status

Personal infrastructure project, currently stable for single-node Proxmox environments.

Version 1 focuses on deterministic shutdown behavior and operational reliability.

---

Possible future improvements

v1 polish

• Stage duration logging • VM shutdown timing metrics

v2 ideas

• Online power debounce logic • Automatic VM restart after recovery • Outage statistics tracking • Battery health tracking • Multi-node coordination

---

License

MIT License – see LICENSE file for details.

Copyright © 2026 Peter Karpati (world-wide-dev)