Skip to content

UPS Management

gitsync edited this page Jul 14, 2026 · 5 revisions

Overview

ZNAS integrates with Network UPS Tools (NUT) to monitor an attached UPS (Uninterruptible Power Supply) and automatically shut down the server when battery thresholds are reached.

The UPS feature is optional. It is installed from Requisites → Optional Features and does not affect the portal if not enabled.


Prerequisites

Click Enable UPS Feature in Requisites → Optional Features to install NUT (Network UPS Tools). Once installed, the UPS battery widget appears in the portal's top bar.

Requisites — Optional Features


Setup

Step 1 — Auto-detect your UPS

  1. Go to Settings → UPS
  2. Click Scan for UPS devices

The portal scans USB and other interfaces and lists detected UPS devices.

Step 2 — Configure

In the UPS Settings panel:

Field Description
UPS name Logical name for the UPS (e.g. myups)
Driver NUT driver (e.g. usbhid-ups, apcsmart) — auto-detected from scan
Port Device path (e.g. auto, /dev/ttyS0) — auto-detected
Description Human-readable label

Click Apply to write the NUT configuration files and start the NUT services.

Step 3 — Set shutdown policy

Configure when the portal should shut down the server:

Threshold Description
Battery % Shut down when battery drops below this percentage
Runtime remaining (s) Shut down when estimated runtime drops below this value
Grace period (s) Wait this many seconds after threshold is breached before issuing shutdown

The most conservative threshold triggers first (whichever is reached first — battery % or runtime).


Top bar battery widget

When NUT is running and a UPS is configured, a compact battery widget appears in the top bar showing:

  • Battery percentage (color-coded: green / yellow / red)
  • Charging / on battery / online indicator
  • Load percentage

Click the widget to open the full UPS settings panel.


UPS metrics panel

The full settings panel shows a visual battery gauge and a metrics grid:

Metric Description
Battery charge % Current battery level
Battery runtime Estimated time remaining
Input voltage AC input voltage
Output voltage AC output voltage
Load % Current UPS load
UPS status Online / On battery / Charging
Temperature UPS temperature (if supported by driver)

Automatic shutdown

The portal monitors the UPS continuously. When thresholds are breached:

  1. The grace period countdown begins
  2. An alert is dispatched to all configured alert targets
  3. After the grace period, the server shuts down cleanly

Note: The shutdown requires either polkit permission for the zfsnas service account (standard on Ubuntu 22.04+) or adding the shutdown command to the sudoers whitelist. See Security for details.


Uninstalling NUT

Go to Settings → UPS → Uninstall. The portal stops the services, removes the NUT packages, and cleans up the configuration.


Troubleshooting

Problem Solution
UPS not detected Try Full Scan instead of USB-only; check USB cable; run lsusb to verify USB visibility
NUT services fail to start Check logs with sudo journalctl -u nut-server; verify the driver name and port
Battery widget not showing Ensure NUT is running and the UPS is responding
Shutdown not triggered Verify polkit or sudoers permission for the zfsnas user; check the shutdown threshold settings
Wrong battery percentage Some UPS models require calibration; check the NUT driver documentation

Useful manual commands

# List detected UPS devices (USB only, fast)
sudo nut-scanner -C -N

# Query UPS status (replace 'myups' with your UPS name)
upsc myups

# Check battery-related values
upsc myups | grep battery

# Check NUT service status
systemctl status nut-server nut-client

Clone this wiki locally