UPS and Proxmox Integration Guide

To integrate a UPS with Proxmox, install Network UPS Tools on the host, point it at the UPS over USB (or at a NUT primary over the network), and configure the shutdown so the VMs and LXC containers come down gracefully before the host halts. Proxmox is Debian under the hood, so the NUT setup is the same as any Linux box — the only Proxmox-specific work is making sure the guests stop cleanly first, which means a QEMU guest agent in each VM and enough shutdown timeout for them to finish.

This matters more on a virtualization host than anywhere else in the lab. A hard power cut on a Proxmox node does not just risk the host’s filesystem — it can corrupt every running VM’s disk and leave LXC containers in an inconsistent state. The whole point of the UPS is an orderly cascade: guests park first, then the host. This guide covers the two ways to wire it and the guest-shutdown details that the generic NUT setup guide does not, and it sits under the UPS and power management hub.

Two ways to wire Proxmox to the UPS

There are two topologies, and which one you use depends on whether the Proxmox host is the machine plugged into the UPS. In a single-host lab, the UPS connects to the Proxmox node by USB, and that node runs the full NUT stack — driver, server, and monitor — as the primary. In a multi-machine lab where a different box (say, a NAS or a small always-on server) owns the USB cable, the Proxmox host runs only the NUT monitor as a secondary, connecting over the network to that primary.

I run the second pattern, because the Proxmox host is the heaviest thing to shut down and I want it to be among the last to go, not the machine babysitting the UPS connection. Either way works; the secondary pattern just keeps the USB ownership on a lighter, faster-to-shutdown box. The guest-shutdown configuration on the Proxmox node is identical in both cases — only the MONITOR line in upsmon.conf changes between primary on the host and secondary pointing at another machine.

Installing NUT on the Proxmox host

Because Proxmox VE is Debian-based, installation is a single package. On the host:

apt update
apt install nut

If the host owns the USB connection, configure it exactly as a NUT primary: set MODE=netserver in /etc/nut/nut.conf, define the UPS in ups.conf with the usbhid-ups driver, expose it with upsd, and set the upsmon.conf MONITOR line to primary. If instead another machine owns the UPS, install NUT and edit only upsmon.conf with a secondary MONITOR line pointing at that primary’s IP. All of that wiring is in the NUT setup guide — the Proxmox-specific part starts after NUT can read the UPS.

The Proxmox-specific part: graceful guest shutdown

When upsmon fires its shutdown command on low battery, it runs a normal shutdown -h. On Proxmox, that triggers the pve-guests service, which is responsible for stopping running VMs and containers before the host goes down. The catch is that a VM only stops gracefully if the host can ask its operating system to shut down — and that requires the QEMU guest agent. Without it, Proxmox can only send an ACPI power button event and hope the guest honours it, or eventually force-stop it, which is the corruption risk you were trying to avoid.

So the real integration work is per-VM: enable the QEMU guest agent on the VM (set agent: 1 in the VM options) and install the qemu-guest-agent package inside the guest OS. LXC containers shut down cleanly on their own because they share the host kernel and stop like any process group. With the agent in place, the cascade works: upsmon calls shutdown, pve-guests asks each VM’s OS to halt, the containers stop, and only then does the host power off.

Give the guests time: shutdown timeouts

A graceful guest shutdown is not instant — a VM running a database or a file server needs a few seconds to flush and halt. If the host’s shutdown timeout is too short, it will give up waiting and force-stop the laggards, which defeats the purpose. Proxmox lets you set a per-guest shutdown timeout and a startup/shutdown order in each VM’s Options, so you can stagger the cascade: stop the dependent services first, give the heavy ones longer, and make sure the total fits inside your UPS runtime.

This is where the runtime calculation and the shutdown design have to agree. If your guests need ninety seconds to all park cleanly, and your UPS gives ten minutes at your load, you have an enormous margin and can set a generous on-battery delay before shutdown even begins — so a short flicker never bounces the whole node. If runtime were tight, you would shorten the delay and trim guest timeouts. Design the two numbers together, never in isolation.

The USB passthrough trap

One mistake bites people who run a firewall or NAS as a VM on the same Proxmox host: do not pass the UPS’s USB device through to a guest VM if the host needs to read it. If you give the UPS USB connection to, say, an OPNsense VM, the Proxmox host can no longer see the UPS and cannot coordinate its own shutdown. Either let the host own the USB and run NUT on the host, or — if you genuinely want a guest to own it — make that guest the NUT primary and run the Proxmox host as a secondary pointing at it over the network. Pick one owner for the USB device and build around it.

This is the kind of failure mode that only shows up during a real outage, long after you have forgotten the passthrough decision, which is exactly why I test the full power-cut cascade after building it. A configuration that looks right in the GUI but has the UPS invisible to the host is worse than no UPS, because it gives you false confidence.

apcupsd as an alternative

NUT is the most flexible option and the right default for a multi-machine lab, but for a single Proxmox host plugged directly into an APC unit, apcupsd is a simpler alternative that does the same core job — monitor the UPS over USB and shut the host down on low battery. It is easier to set up for the one-box case but does not have NUT’s clean network primary/secondary model, so the moment you have a second machine to protect, NUT is the better foundation. I use NUT everywhere precisely so the whole rack speaks one protocol, but if you have exactly one APC unit and one host, apcupsd is a perfectly reasonable shortcut.

Test the whole cascade

Build it, then prove it. With non-critical guests running, pull the mains plug on the UPS and watch the sequence: the host should detect battery, wait out your configured delay, then run the shutdown that stops the VMs and containers before halting itself. Check afterward that every guest came down cleanly — no force-stops in the logs, no filesystem checks on next boot. I run this test once when I build the integration and once a year, because the cascade has the most moving parts of anything in the power chain, and the only test that counts is the one that pulls real power. Pair it with monitoring so an aging battery shows up on your dashboards long before an outage finds it for you.

Frequently Asked Questions

Related Articles

• Home Lab UPS & Power Management Hub
• NUT Network UPS Tools Setup Guide
• Proxmox Homelab Setup Guide
• LXC Containers vs VMs in Proxmox
• UPS Runtime Calculation for a Home Lab