UPS
Uninterruptible power supply via NUT: detection, status, shutdown, network server.
Bunkerbox monitors a UPS connected via USB with NUT (packages nut-server and nut-client, set up by the installer) and shuts the server down in time during a power failure. NUT does the shutdown itself (upsmon, upssched), so it also works when the interface hangs.
Setup
- Connect the UPS via USB and switch it on.
- System → UPS → Find UPS:
nut-scanner -Ulists the devices found with driver (usuallyusbhid-ups), USB ID and serial number. - Use takes over the device; adjust description and shutdown policy, Apply.
Bunkerbox writes the NUT configuration, enables and starts nut-driver@ups, nut-server (upsd) and nut-monitor (upsmon). If NUT cannot start (e.g. UPS not connected), the settings stay saved and the message contains the output of systemctl/journal. Switching off Monitor the UPS sets MODE=none and stops the services.
Status
The page and the dashboard card show every 5 seconds (upsc ups@localhost):
| Value | Source |
|---|---|
| State | ups.status: on line power (OL), on battery (OB), battery low (LB), shutting down (FSD); unreachable when the driver or upsd deliver no data |
| Charge, runtime, load | battery.charge, battery.runtime, ups.load |
| Input voltage | input.voltage |
| Status flags | all flags, e.g. CHRG, DISCHRG, RB (replace battery) |
| Services | state of nut-driver@ups, nut-server, nut-monitor |
During a power failure page and dashboard show the duration and – with the timer policy – the time left until shutdown.
Shutdown
| Policy | Behaviour |
|---|---|
| At low battery (default) | upsmon shuts down as soon as the UPS reports LB. Uses the full battery runtime. |
| After a fixed time on battery (30–7200 s) | upssched starts a timer when switching to battery and cancels it when power returns. When it expires, /etc/nut/bunkerbox-upssched-cmd calls upsmon -c fsd. A low battery still shuts down right away. |
upsmon runs shutdown -h +0. For the server to start again when power returns, enable "power on after power loss" in the BIOS.
Notifications
Through the notifications, once per power failure each:
| Event | When |
|---|---|
| UPS on battery (warning) | switch to battery, with charge and runtime |
| UPS on battery (info) | power restored, with the duration of the outage |
| UPS battery low (critical) | LB reported on battery (many UPS units also report LB while recharging on mains, which sends no e-mail) |
| Shutdown by UPS (critical) | on FSD, OB + LB or 10 seconds before the timer expires, so the e-mail still gets out |
Network server
With Allow other devices to monitor the UPS NUT runs in netserver mode: upsd also listens on the given addresses (port 3493, default 0.0.0.0) and an extra user (default monuser) may monitor the UPS as secondary. On the client:
| Field | Value |
|---|---|
| UPS name | ups |
| Server | IP address of this server |
| Port | 3493 |
| User / password | as configured |
Synology DSM (Hardware & Power → UPS → Network UPS server) expects the user monuser. Clients shut down before this server during a power failure (HOSTSYNC 15 s). Open port 3493 in the local network only.
Files
All files below /etc/nut/ are managed by Bunkerbox and rewritten on every change (root:nut, 640; the script 750):
| File | Content |
|---|---|
nut.conf | MODE=standalone, netserver or none |
ups.conf | section [ups] with driver, port, vendorid, productid, serial, desc |
upsd.conf | LISTEN 127.0.0.1 3493 and the network server addresses |
upsd.users | local user bunkerbox (upsmon primary, random password) and the network user (upsmon secondary) |
upsmon.conf | MONITOR ups@localhost 1 bunkerbox … primary, SHUTDOWNCMD, with the timer policy NOTIFYCMD /usr/sbin/upssched |
upssched.conf, bunkerbox-upssched-cmd | timer bunkerbox-shutdown |
upsmon runs as root (RUN_AS_USER root) because the timer script has to signal the upsmon process. The settings are in /appdata/bunkerbox/data/ups.json (600), the passwords in data/secrets/ups-monitor-password and data/secrets/ups-net-password (600). All values are checked strictly before writing (no quotes, backslashes or line breaks). When the service starts, the files are rewritten from ups.json without restarting NUT.
In mock mode a CyberPower CP1500EPFCLCD on line power is set up.