A UPS can keep a Proxmox VE server running during a short power outage, but battery backup alone does not protect your virtual machines from an extended outage.
The safest approach is to automatically detect that the APC UPS is running on battery, give utility power a few minutes to return, gracefully shut down your virtual machines and containers, power down the Proxmox VE host, and only then allow the UPS to shut off its output.
This guide walks through a practical configuration using Proxmox VE, an APC UPS, and Network UPS Tools (NUT).
Recommended shutdown sequence
Utility power fails → APC UPS switches to battery → short delay → VMs and containers shut down → Proxmox VE shuts down → UPS output turns off
This approach minimizes the risk of filesystem corruption, database damage, interrupted writes, and abrupt VM termination.
Why You Should Shut Down VMs Instead of Pausing Them
Proxmox allows a virtual machine to be paused, but pausing is not a good emergency UPS strategy.
A paused VM still depends on the Proxmox host remaining powered. If the UPS battery eventually runs out, the host will lose power and the paused VM will still terminate unexpectedly.
For an extended power outage, the preferred approach is:
- Gracefully shut down guest operating systems.
- Shut down containers.
- Shut down the Proxmox VE host.
- Allow the UPS to remove power.
The UPS battery should provide enough time for this entire process to complete.
1. Install the QEMU Guest Agent
Before configuring the UPS, make sure Proxmox can properly communicate with your VMs.
For Debian or Ubuntu guests:
apt update
apt install qemu-guest-agent
systemctl enable --now qemu-guest-agent
Then open the VM in the Proxmox web interface:
VM → Options → QEMU Guest Agent → Enabled
A reboot may be required after enabling the guest agent.
You can test communication from the Proxmox host with:
qm agent 100 ping
Replace 100 with your VM ID.
For Windows guests, install the QEMU Guest Agent from the VirtIO drivers ISO and verify that the QEMU Guest Agent service is running.
2. Configure VM Startup and Shutdown Order
Some servers should remain running longer than others.
For example, you may want DNS, Active Directory, or other infrastructure services to remain online while your application servers are shutting down.
A typical configuration might look like this:
Order 10 DNS / Active Directory
Order 20 Database Server
Order 30 Application Server
Order 40 Web Server
During startup:
DNS
↓
Database
↓
Application
↓
Web Server
During shutdown, Proxmox reverses the order:
Web Server
↓
Application
↓
Database
↓
DNS
You can configure startup order from the Proxmox GUI or from the command line.
Example:
qm set 100 --onboot 1 --startup order=10,up=30,down=20
qm set 101 --onboot 1 --startup order=20,up=30,down=20
qm set 102 --onboot 1 --startup order=30,up=30,down=20
The up and down values add delays between startup or shutdown operations.
You can also delay all VM startup after the Proxmox host boots:
pvenode config set --startall-onboot-delay 30
This is useful when switches, storage systems, NAS devices, or other infrastructure need time to become available.
3. Test VM Shutdown Before Configuring the UPS
Do not make the UPS your first test of the shutdown process.
Test each important VM individually.
For example:
qm shutdown 100 --timeout 120
Check the status:
qm status 100
You should eventually see:
status: stopped
Restart the VM afterward:
qm start 100
Repeat this test for all critical VMs.
Test All Proxmox Guests
Proxmox can shut down all VMs and containers using:
pvenode stopall
This attempts to gracefully stop the guests.
If necessary, Proxmox can eventually hard-stop guests that refuse to shut down. During a real UPS emergency, that is preferable to letting the entire server abruptly lose power because the UPS battery became completely exhausted.
Once testing is complete, you can restart configured guests with:
pvenode startall
4. Connect the APC UPS to the Proxmox Host
For a single Proxmox server, the simplest configuration is usually a USB connection between the APC UPS and the physical Proxmox server.
The UPS USB cable should connect directly to the Proxmox host.
Avoid passing the UPS USB device through to a VM.
The physical Proxmox host needs to know when the UPS is on battery because the physical host is ultimately responsible for shutting itself down.
5. Install Network UPS Tools
Install NUT on the Proxmox VE host:
apt update
apt install nut-server nut-client
Scan for USB UPS devices:
nut-scanner -U
You can also check USB devices with:
lsusb
An APC UPS may appear similar to:
American Power Conversion
NUT may report a configuration resembling:
[nutdev1]
driver = "usbhid-ups"
port = "auto"
vendorid = "051D"
Use the information reported by your own UPS.
6. Configure NUT in Standalone Mode
Edit:
nano /etc/nut/nut.conf
Set:
MODE=standalone
This tells NUT that this Proxmox server is directly connected to and responsible for the UPS.
7. Configure the APC UPS
Edit:
nano /etc/nut/ups.conf
For many APC USB UPS models, the configuration will look like this:
[apc]
driver = usbhid-ups
port = auto
desc = "APC UPS protecting Proxmox"
Restart NUT:
systemctl restart nut-server
systemctl restart nut-monitor
Now query the UPS:
upsc apc@localhost
You should see UPS information including battery charge, runtime, load, and status.
For example:
battery.charge: 100
battery.runtime: 2400
ups.load: 30
ups.status: OL
Common UPS status values include:
OL = On Line / Utility Power
OB = On Battery
LB = Low Battery
Under normal conditions, you should see:
ups.status: OL
8. Create a NUT Monitoring Account
Edit:
nano /etc/nut/upsd.users
Add:
[monuser]
password = CHANGE_THIS_TO_A_LONG_RANDOM_PASSWORD
upsmon primary
Use a strong unique password.
9. Create a Proxmox UPS Shutdown Script
Create:
nano /usr/local/sbin/pve-ups-shutdown
Add:
#!/bin/bash
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
logger -t pve-ups "UPS emergency shutdown started"
# Gracefully stop Proxmox VMs and containers
pvenode stopall
logger -t pve-ups "Guest shutdown complete"
# Flush outstanding filesystem writes
sync
logger -t pve-ups "Powering off Proxmox host"
systemctl poweroff
Make the script executable:
chmod 750 /usr/local/sbin/pve-ups-shutdown
chown root:root /usr/local/sbin/pve-ups-shutdown
The important shutdown sequence is:
UPS shutdown event
↓
pvenode stopall
↓
VMs and containers shut down
↓
sync
↓
systemctl poweroff
10. Configure NUT to Call the Shutdown Script
Edit:
nano /etc/nut/upsmon.conf
Configure the UPS monitor:
MONITOR apc@localhost 1 monuser CHANGE_THIS_TO_A_LONG_RANDOM_PASSWORD primary
MINSUPPLIES 1
SHUTDOWNCMD "/usr/local/sbin/pve-ups-shutdown"
POWERDOWNFLAG /etc/killpower
The username and password must match the credentials created in:
/etc/nut/upsd.users
Protect the configuration file because it contains the UPS monitoring password:
chown root:nut /etc/nut/upsmon.conf
chmod 640 /etc/nut/upsmon.conf
Restart NUT:
systemctl restart nut-server
systemctl restart nut-monitor
Verify the services:
systemctl status nut-server
systemctl status nut-monitor
Then verify UPS communication again:
upsc apc@localhost
11. Do Not Immediately Shut Down During Every Power Flicker
A short power outage does not necessarily justify shutting down your entire virtualization environment.
For example, if utility power disappears for 10 seconds, the UPS can easily bridge the outage.
A better strategy is to wait several minutes before beginning shutdown.
A useful sequence might be:
0:00 Utility power fails
0:00
↓
3:00 Continue running from UPS
3:00 If utility power has not returned,
begin shutdown
3:00
↓
6:00 VMs and containers shut down
6:00 Proxmox host powers off
6:30+ UPS can remove output power
The exact times depend on your UPS runtime and workload.
12. Configure a Three-Minute UPS Shutdown Delay
NUT provides upssched for delayed actions.
First determine where the commands are installed:
command -v upssched
command -v upsmon
Then edit:
nano /etc/nut/upsmon.conf
Add:
NOTIFYCMD /usr/sbin/upssched
NOTIFYFLAG ONLINE SYSLOG+EXEC
NOTIFYFLAG ONBATT SYSLOG+EXEC
NOTIFYFLAG LOWBATT SYSLOG+EXEC
Now edit:
nano /etc/nut/upssched.conf
Add:
CMDSCRIPT /usr/local/sbin/upssched-cmd
PIPEFN /run/nut/upssched.pipe
LOCKFN /run/nut/upssched.lock
AT ONBATT * START-TIMER ups-shutdown 180
AT ONLINE * CANCEL-TIMER ups-shutdown
AT LOWBATT * EXECUTE ups-shutdown-now
The value:
180
means:
180 seconds = 3 minutes
13. Create the upssched Command Script
Create:
nano /usr/local/sbin/upssched-cmd
Add:
#!/bin/sh
case "$1" in
ups-shutdown|ups-shutdown-now)
logger -t upssched "UPS shutdown threshold reached - initiating FSD"
/usr/sbin/upsmon -c fsd
;;
esac
Make it executable:
chmod 750 /usr/local/sbin/upssched-cmd
chown root:root /usr/local/sbin/upssched-cmd
Restart the UPS monitor:
systemctl restart nut-monitor
How the Three-Minute Timer Works
If utility power fails:
UPS status changes to ONBATT
↓
180-second timer starts
If utility power returns after 30 seconds:
ONLINE event detected
↓
shutdown timer canceled
↓
everything continues running
Nothing shuts down.
If utility power remains off for more than three minutes:
ONBATT
↓
180 seconds
↓
ups-shutdown
↓
upsmon -c fsd
↓
Proxmox shutdown begins
If the UPS unexpectedly reaches a low battery condition before the timer expires:
LOWBATT
↓
immediate shutdown
This gives you protection against both extended outages and unexpectedly short battery runtime.
14. Leave Plenty of Battery Reserve
Do not configure Proxmox to start shutting down when the UPS only has one or two minutes remaining.
For example, imagine your UPS normally reports:
20 minutes runtime
Your Proxmox environment takes:
4 minutes
to completely shut down.
A shutdown trigger at approximately three to five minutes into the outage leaves a substantial safety margin.
You want:
Available battery runtime
>
UPS delay
+
worst-case VM shutdown time
+
Proxmox shutdown time
+
safety reserve
The larger the environment, the more reserve you should leave.
15. Test the UPS Without Shutting Down Proxmox
Before performing a complete shutdown test, verify that NUT properly detects a power failure.
Run:
upsc apc@localhost | grep -E 'ups.status|battery.charge|battery.runtime|ups.load'
Under normal conditions you should see:
ups.status: OL
Now leave the server plugged into the UPS and disconnect utility power going into the UPS.
Do not unplug the server from the UPS.
Watch the UPS status:
watch -n 1 'upsc apc@localhost | grep -E "ups.status|battery.charge|battery.runtime"'
The status should change to:
ups.status: OB
Restore utility power before the three-minute shutdown timer expires.
The status should return to:
ups.status: OL
Check the NUT logs:
journalctl -u nut-monitor --since "10 minutes ago"
You should see the UPS transition to battery and then back to utility power.
16. Perform a Full Shutdown Test
Once the configuration has been verified, schedule a maintenance window and perform a complete shutdown test.
NUT allows you to simulate a critical UPS event with:
upsmon -c fsd
Warning: This command will initiate your configured shutdown sequence.
During the test, verify that the following happens:
FSD triggered
↓
UPS shutdown script starts
↓
pvenode stopall
↓
VMs shut down
↓
containers shut down
↓
Proxmox powers off
Watch the Proxmox interface or console during the shutdown.
Every important guest should shut down cleanly before the physical server powers off.
17. Configure Automatic Startup After Power Returns
A UPS shutdown is only half of the process.
You also need the server to start again when utility power returns.
Enter your physical server’s BIOS or UEFI configuration.
Look for a setting similar to:
Restore on AC Power Loss
or:
AC Power Recovery
Set it to:
Power On
Different server manufacturers use slightly different terminology.
When utility power returns:
Utility power restored
↓
APC UPS restores output
↓
Server receives AC power
↓
BIOS automatically powers on server
↓
Proxmox boots
↓
VMs start according to configured order
18. Configure Important VMs to Start Automatically
Enable automatic startup for each VM that should return after power restoration.
For example:
qm set 100 --onboot 1
Then use the startup order configured earlier.
A typical recovery sequence might be:
Proxmox VE
↓
DNS / Active Directory
↓
Database Server
↓
Application Server
↓
Web Server
This prevents application servers from starting before services they depend on are available.
19. Keep Supporting Network Equipment on the UPS
An often-overlooked part of UPS design is the network infrastructure.
If Proxmox depends on any of the following:
- Managed switches
- Routers
- Firewalls
- DNS servers
- Active Directory
- NAS devices
- NFS storage
- iSCSI storage
- Ceph nodes
- APC Network Management Cards
those devices may also need UPS power.
For example, if Proxmox uses network storage and the network switch loses power before the VM shuts down, the VM could lose access to its storage while it is still running.
Ideally:
UPS
├── Proxmox Server
├── Network Switch
├── Storage
└── Critical Network Infrastructure
Everything required for a clean shutdown should remain operational until the shutdown process finishes.
APC UPS With a Network Management Card
Some APC Smart-UPS systems include or support Network Management Cards such as the AP9630, AP9631, AP9640, or AP9641.
In this situation, the UPS does not necessarily need to connect directly to Proxmox using USB.
The environment can instead look like:
APC UPS
│
│ Ethernet
↓
Network Switch
│
↓
Proxmox VE
NUT can communicate with supported network-managed UPS devices, or Schneider Electric’s PowerChute Network Shutdown can be used.
The Proxmox shutdown logic should remain essentially the same:
UPS detects extended outage
↓
Shutdown command sent
↓
pvenode stopall
↓
VMs and containers stop
↓
Proxmox host powers off
↓
UPS eventually turns off output
Make sure the network switch connecting Proxmox to the UPS management interface is itself connected to battery-backed power.
Otherwise Proxmox may lose communication with the UPS during the outage.
What About a Proxmox Cluster?
A multi-node Proxmox cluster requires more planning.
For example:
APC UPS
↓
UPS monitoring system
↓
PVE Node 1
PVE Node 2
PVE Node 3
You should consider:
- Which node is physically connected to the UPS?
- Are all nodes protected by the same UPS?
- Are there multiple UPS units?
- Is shared storage UPS protected?
- Is Ceph being used?
- Is Proxmox HA enabled?
- Should VMs migrate or shut down?
- Which node should shut down last?
NUT supports a primary/secondary architecture that allows one machine to monitor the UPS while other machines receive UPS status over the network.
For clusters, the goal is generally:
UPS outage
↓
Notify every PVE node
↓
Gracefully shut down workloads
↓
Shut down cluster nodes
↓
Shut down storage
↓
UPS removes power
Do not blindly duplicate a single-node UPS shutdown script across a production Proxmox cluster without considering quorum, HA, shared storage, and shutdown order.
Recommended Final Configuration
For a single Proxmox VE host connected to an APC UPS through USB, a solid configuration looks like this:
APC UPS
│
│ USB
↓
Proxmox VE Host
│
├── NUT usbhid-ups driver
│
├── upsmon
│
└── upssched
During an outage:
Power Failure
↓
UPS switches to battery
↓
Wait 3 minutes
↓
Did utility power return?
│
┌───┴────┐
│ │
YES NO
│ │
Cancel Begin shutdown
timer ↓
│ pvenode stopall
Continue ↓
running VMs/CTs stop
↓
Proxmox powers off
↓
UPS powers off
When power returns:
Utility restored
↓
UPS output restored
↓
Physical server powers on
↓
Proxmox boots
↓
Infrastructure VMs start
↓
Application VMs start
Final Safety Checklist
Before relying on your APC UPS configuration in production:
- APC UPS communicates correctly with NUT
upsc apc@localhostreports valid information- Every important VM has been tested for graceful shutdown
- QEMU Guest Agent is installed where appropriate
- Proxmox VM startup and shutdown ordering is configured
pvenode stopallhas been tested- A short power failure does not immediately shut down the server
- An extended outage triggers the NUT shutdown process
- LOWBATT triggers an emergency shutdown
- The UPS has enough remaining runtime to complete shutdown
- Network switches required for shutdown remain on UPS power
- Shared storage remains available until Proxmox has shut down
- BIOS/UEFI is configured to power the server on after AC returns
- Important VMs have
onbootenabled - VM startup order has been tested
- A complete simulated UPS shutdown has been performed
Conclusion
Connecting an APC UPS to a Proxmox VE server is only the first step in protecting your virtual environment.
The real protection comes from coordinating the UPS, Proxmox host, virtual machines, containers, storage, and network infrastructure so that an extended power outage results in a controlled shutdown rather than an unexpected loss of power.
For a standalone Proxmox VE server, APC UPS + NUT + a delayed shutdown timer + pvenode stopall provides a straightforward and reliable architecture.
The most important rule is simple:
Start the shutdown while you still have plenty of battery remaining.
Do not try to squeeze every last minute of runtime from the UPS. Battery capacity changes with age, temperature, and load. Leaving a generous reserve gives Proxmox enough time to stop its guests, flush storage writes, and power down cleanly before the UPS battery is exhausted.
