Proxmox VE UPS Shutdown: NUT on the Host and Getting the Order Right

Where NUT belongs in a Proxmox setup

A Proxmox VE host is the parent of everything running on it. When the host shuts down, its guest-stopping service asks each VM and container to shut down, waits, and forces off any that do not respond. That is exactly the behavior you want on UPS power, so the simplest correct design is: NUT runs on the host, and on a power event it calls a normal host shutdown.

Pick the layout that matches your cabling:

Host as NUT server (UPS plugged into Proxmox)

From the host shell (as root):

apt update
apt install nut
# Identify the UPS (optional but useful)
nut-scanner -U

Then edit the files in /etc/nut/. Use your own passwords; these are placeholders.

# /etc/nut/nut.conf
MODE=netserver          # use standalone if no other machine needs the UPS

# /etc/nut/ups.conf
[ups]
    driver = usbhid-ups
    port = auto
    desc = "Homelab UPS"

# /etc/nut/upsd.conf
LISTEN 127.0.0.1 3493
LISTEN 192.168.1.10 3493   # the host's LAN address, only if others connect

# /etc/nut/upsd.users
[upsmon_local]
    password = change-me-local
    upsmon primary

[upsclient]
    password = change-me-remote
    upsmon secondary

# /etc/nut/upsmon.conf (key lines)
MONITOR ups@localhost 1 upsmon_local change-me-local primary
MINSUPPLIES 1
SHUTDOWNCMD "/sbin/shutdown -h +0"
POWERDOWNFLAG /etc/killpower

Restart the services and check that data flows:

systemctl restart nut-server nut-monitor
upsc ups@localhost ups.status     # expect OL
upsc ups@localhost battery.runtime

Service names differ slightly between NUT packaging versions (for example, driver instances may run as nut-driver@ups units on recent releases). systemctl list-units 'nut*' shows what your system uses. The NUT guide explains each directive.

Host as NUT client (UPS owned by a NAS)

apt install nut-client

# /etc/nut/nut.conf
MODE=netclient

# /etc/nut/upsmon.conf, Synology server example
MONITOR ups@192.168.1.20 1 monuser secret secondary
SHUTDOWNCMD "/sbin/shutdown -h +0"

Test with upsc ups@192.168.1.20 before restarting nut-monitor. For a Synology server you must add the Proxmox host's IP to DSM's permitted list; see Synology UPS setup. For TrueNAS, use the credentials you defined there; see TrueNAS UPS setup.

Getting guests to shut down cleanly

NUT only shuts down the host. Proxmox handles the guests, and three settings decide how well that goes.

1. Install the QEMU guest agent in each VM (qemu-guest-agent on Linux; the virtio guest tools on Windows) and enable QEMU Guest Agent in the VM's Options. Shutdown requests then go through the agent instead of relying on the guest honoring an ACPI button event.
2. Set Start/Shutdown order in each guest's Options. Guests start in ascending order and shut down in the reverse. Put dependencies (a database VM, a DNS container) early in the start order so they stop last.
3. Set a realistic Shutdown timeout per guest. If a guest has not stopped when it expires, Proxmox forces it off. Too long wastes battery; too short forces off a guest mid-write.

Time a full host shutdown from the web UI with all guests running, before you rely on the UPS. That number is what the battery has to cover.

Ordering across machines: hypervisors before storage

A common homelab arrangement is a NAS that owns the UPS and also serves VM disks to Proxmox over NFS or iSCSI. If the NAS shuts down first, running VMs lose their disks mid-write. The hypervisor must finish first, so it needs an earlier trigger than the NAS.

A plain secondary only shuts down when the primary declares the UPS critical, which is too late here. upssched lets the Proxmox host start its own shutdown a fixed time after the UPS goes on battery, while the NAS waits longer.

# /etc/nut/upsmon.conf on the Proxmox host (additions)
NOTIFYCMD /sbin/upssched          # path varies: check with "command -v upssched"
NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
NOTIFYFLAG ONLINE SYSLOG+WALL+EXEC

# /etc/nut/upssched.conf
CMDSCRIPT /etc/nut/upssched-cmd
PIPEFN /run/nut/upssched/upssched.pipe
LOCKFN /run/nut/upssched/upssched.lock
AT ONBATT * START-TIMER early-shutdown 180
AT ONLINE * CANCEL-TIMER early-shutdown

# /etc/nut/upssched-cmd  (make it executable: chmod 755)
#!/bin/sh
case "$1" in
    early-shutdown)
        logger -t upssched "On battery 180 s: shutting down hypervisor"
        /sbin/shutdown -h +0
        ;;
esac

Create the directory for the pipe and lock files and make it writable by the NUT user (often nut), for example mkdir -p /run/nut/upssched && chown nut:nut /run/nut/upssched. Because /run is cleared at boot, some admins point PIPEFN and LOCKFN at an existing NUT state directory instead. Then restart nut-monitor and test by unplugging the UPS from the wall.

Leave a clear gap between the hypervisor's expected finish and the NAS's trigger. If power returns during the gap, the ONLINE event cancels the timer on any host that has not started shutting down.

Coming back up in the right order

Shutdown is half the job. After a long outage, everything boots at once when mains returns, and the same dependency that mattered on the way down matters on the way up: VMs whose disks live on a NAS will fail to start if the NAS is still booting.

• Host power-on. Set the server firmware's AC power recovery option to power on (or last state). If the UPS cut its outlets at the end of the outage, the host then boots by itself when power returns.
• Start at boot. Enable it only for guests that should come back unattended.
• Startup delay. In each guest's Start/Shutdown order settings, a startup delay holds the next guest back for a number of seconds. A delay after the first guest gives a storage-dependent VM time to find its datastore.
• Storage availability. For NFS or iSCSI storage, consider delaying guest autostart until the storage responds. Proxmox will mark unavailable storage as inactive and fail to start guests on it; a short wait (or a boot-time hook that waits for the NAS) avoids a pile of failed starts.

A practical check after your first real test: read the host's task log from the boot and look for guests that failed to start. Each failure there is an ordering problem you can fix before the next outage.

Mistakes we see most often

Clusters, HA and Ceph

• Quorum. In a cluster, nodes shutting down one at a time over many minutes can leave the survivors without quorum. Trigger all nodes from the same UPS event at about the same time.
• HA-managed guests. What happens to HA guests on node shutdown depends on the HA shutdown policy in the datacenter options (policies include conditional, freeze, failover and migrate in recent releases). Migrating guests onto nodes that are also about to shut down only wastes battery, so choose deliberately.
• Ceph. A hyperconverged Ceph cluster should not lose nodes piecemeal while rebalancing. Follow the Proxmox and Ceph guidance for full-cluster shutdown (such as setting the noout flag) and accept that a fully automated unattended shutdown needs extra scripting and testing.

For sizing the UPS so this whole sequence fits with margin, see UPS for a homelab server and how much runtime you need.