Homelab Addiction
Proxmox

Proxmox UPS Shutdown with NUT: The Safe Power-Failure Setup I Actually Trust

Set up Proxmox UPS shutdown with NUT the right way: host-level monitoring, sane battery thresholds, clean VM shutdown order, and real testing steps.

AU

Author

Marcus Chen

> FTC disclosure: This article contains affiliate links. If you purchase through these links, we may earn a commission at no additional cost to you.

Key Takeaways

  • If your UPS cannot tell Proxmox when to shut down, you do not really have a power-failure plan. You have a battery with good marketing.
  • For a single Proxmox host, the simplest reliable design is usually NUT running directly on the host, not inside a clever little container you will forget about six months later.
  • Your real job is not just talking to the UPS. It is making sure Proxmox has enough time to stop VMs and LXCs cleanly before the battery gets cranky.
  • Start with a conservative shutdown trigger, test it in a maintenance window, and then tune it. Guessing is how you end up learning about filesystem recovery at 2 AM.
  • If you already use a NAS or another device as a NUT server, Proxmox can be the client. That is fine. Just keep the shutdown path simple.

After running Proxmox long enough, I stopped worrying about the dramatic failures and started worrying about the boring ones. Sudden power loss is a classic example. It rarely produces a cinematic explosion. It just leaves you with dirty filesystems, unhappy databases, confused VMs, and a small but meaningful drop in your will to live.

The fix is not complicated. The fix is that your hypervisor needs to know when utility power is gone, when battery runtime is getting low, and when it is time to shut everything down in the right order.

For most homelabs, I recommend Network UPS Tools (NUT) on the Proxmox host itself. You can get fancy later. Fancy is always available. Clean shutdown is the part you need first.

In this guide, I will show you the setup I actually trust: a Proxmox host connected to a UPS, NUT handling detection and shutdown, and Proxmox taking care of shutting down guests cleanly. I will also explain when to use a remote NUT server, when apcupsd makes sense, and how to test the whole thing without waiting for the next thunderstorm.

Why host-level UPS shutdown matters on Proxmox

Proxmox is not a random Linux box with one process you do not mind restarting.

It is the thing hosting your other mistakes.

If the host loses power without warning, every VM and container on that node gets the same treatment. Databases do not flush nicely. Write caches do not ask permission. Applications that looked stable five minutes ago suddenly develop opinions.

A proper UPS setup gives you three things:

1. Time to ride out short outages.

2. Visibility into battery state and runtime.

3. A controlled shutdown path when the outage lasts longer than your battery.

That last one is the difference between "my services came back normally" and "why is this VM replaying journals like it is 2009?"

If you are already thinking about backup discipline, this sits right next to it. Your restore plan matters, but so does avoiding needless corruption in the first place. I covered the backup side separately in Proxmox Backup Strategies: How to Never Lose a VM Again, and offsite workload backups in Restic Backup for Homelabs. Power handling is part of the same grown-up infrastructure story.

NUT vs apcupsd on Proxmox

Here is the short version.

  • Use NUT if you want the most flexible option, especially if you may monitor the UPS from multiple systems, use USB today and SNMP later, or expose UPS status to other clients.
  • Use apcupsd if you have a straightforward APC-only setup and want the shortest path to basic functionality.

I still lean toward NUT for Proxmox.

Why? Because NUT handles more mixed homelab situations cleanly. USB UPS today, Synology-as-server tomorrow, SNMP card next year, multiple nodes later. The configuration is not exactly beautiful, but it is consistent once you understand the pieces.

apcupsd is fine. I am not here to insult working software for sport. But if I am writing one guide for a wide range of Proxmox users, NUT is the better default.

The topology I recommend first

For a single Proxmox node with a USB-connected UPS, I recommend this:

  • UPS connected directly to the Proxmox host
  • NUT driver on the host
  • upsd on the host
  • upsmon on the host
  • Proxmox shutdown order configured so guests stop before the host powers off

That is it.

No extra container.

No Raspberry Pi side quest.

No "I built a monitoring LXC for elegance" story that later turns into "the LXC came up after the host-level services and broke my shutdown logic." I have done that kind of thing before. It feels smart right up until it is dark and the battery timer is running.

When a remote NUT server makes sense

Use a remote NUT server when:

  • the UPS is physically attached to a NAS or another Linux box
  • you want multiple devices to consume the same UPS status
  • your UPS uses SNMP and lives on the network already
  • you have multiple Proxmox nodes and a shared power event model

That design is legitimate. It is just not where I tell most people to start.

Before you install anything

You need four things sorted out first.

1. Know how long your node actually takes to shut down

Do not assume it is quick.

If you host a few lightweight LXCs, you may be done in a minute or two. If you have VMs with databases, a NAS VM, or anything that thinks shutdown is a negotiation, it can take much longer.

Measure it.

2. Configure guest shutdown behavior in Proxmox

Proxmox can stop guests gracefully during node shutdown, but only if you configure it sensibly. Review the startup and shutdown order settings in the official Proxmox VM documentation.

Your important guests should have:

  • a defined shutdown order
  • realistic shutdown timeout values
  • clean guest agents where appropriate

If your guest shutdown order is nonsense, your UPS integration will faithfully preserve that nonsense.

3. Identify your UPS connection type

You are typically in one of these camps:

  • USB UPS connected directly to Proxmox
  • SNMP UPS reachable over the network
  • Remote NUT server running elsewhere, with Proxmox as client

This guide focuses on the first case, then shows how the logic changes for the others.

4. Decide your shutdown trigger philosophy

You can trigger shutdown based on:

  • remaining runtime
  • battery percentage
  • low-battery event from the UPS

I prefer a conservative battery or runtime threshold over "wait until the UPS screams and then improvise." Cheap UPS runtime reporting can be optimistic, especially when your load changes under stress.

Install NUT on Proxmox

On the Proxmox host:

apt update\napt install -y nut nut-client nut-server

For an SNMP UPS, you may also need:

apt install -y nut-snmp snmp

If your UPS is directly attached over USB, confirm the host sees it:

lsusb

You are looking for your UPS vendor and product IDs. On many APC units, you will see something like this:

Bus 001 Device 002: ID 051d:0002 American Power Conversion Uninterruptible Power Supply

Then check what NUT can see after installation:

nut-scanner -U

Or at least confirm the device class with:

dmesg | tail -n 50

Minimal direct-on-host NUT configuration for USB UPS

This is the simple, sane baseline.

/etc/nut/nut.conf

Set the mode to standalone:

MODE=standalone

That tells NUT this machine will both talk to the UPS and act on the result.

/etc/nut/ups.conf

For a typical USB UPS:

[labups]\n  driver = usbhid-ups\n  port = auto\n  desc = "UPS for Proxmox host"

If autodetection is messy, add vendor and product IDs:

[labups]\n  driver = usbhid-ups\n  port = auto\n  vendorid = 051d\n  productid = 0002\n  desc = "UPS for Proxmox host"

For SNMP-based setups, the block looks more like this:

[labups]\n  driver = snmp-ups\n  port = 192.168.10.50\n  community = public\n  desc = "Network UPS"

/etc/nut/upsd.conf

If the host only needs local monitoring, keep it tight:

LISTEN 127.0.0.1 3493

If other clients need access, add your management IP too.

/etc/nut/upsd.users

Create a monitoring user:

[upsmon]\n  password = change-this-to-a-real-password\n  upsmon primary

Keep this file secure. The official upsmon.conf docs are very clear about permissions for a reason.

/etc/nut/upsmon.conf

Start with something like this:

MONITOR labups@localhost 1 upsmon change-this-to-a-real-password primary\nMINSUPPLIES 1\nSHUTDOWNCMD "/sbin/shutdown -h +0"\nPOLLFREQ 5\nPOLLFREQALERT 5\nHOSTSYNC 15\nDEADTIME 15\nPOWERDOWNFLAG /etc/killpower\nFINALDELAY 5

Those defaults are not magic. They are just reasonable enough to get started without doing something embarrassing.

Enable and start the services

systemctl enable nut-server nut-monitor\nsystemctl restart nut-server nut-monitor\nsystemctl status nut-server nut-monitor

Then validate that NUT can read the UPS:

upsc labups@localhost

You want real metrics back, not sadness.

Typical output includes fields like:

  • battery.charge
  • battery.runtime
  • ups.load
  • ups.status

If ups.status shows OL, the UPS is on line power. That means the basic path works.

The Proxmox part people skip

A lot of guides stop after upsc works.

That is not the end.

That is the beginning.

Your actual goal is that Proxmox shuts down guests cleanly when the host receives a shutdown command. So before you trust this stack, go into the Proxmox UI and review the guests that matter most.

For each critical VM or container, check:

  • Start/Shutdown order
  • Startup delay where needed
  • Shutdown timeout that matches reality
  • guest tools or agents where appropriate

Database VMs, directory services, storage helpers, and anything stateful should stop before disposable application workloads. This is the same mindset behind Homelab Monitoring with Prometheus and Grafana and How to Monitor Proxmox with Grafana and Prometheus: infrastructure needs order, not vibes.

The mistake I made

I once assumed the node would shut everything down "gracefully enough" because Proxmox is good software and I was feeling optimistic.

It was not a total disaster. Which is exactly why it was annoying.

A couple of VMs took longer than expected, one service came back dirty, and the root cause was not NUT at all. It was me not setting realistic shutdown order and timeout values. The UPS did its job. I had simply delegated planning to hope.

Choosing the right shutdown threshold

This is where people overcomplicate things.

Start conservative.

For a small single-node homelab, one of these usually works well:

  • shutdown at 30 to 40 percent battery remaining, or
  • shutdown when runtime falls below 8 to 12 minutes

The right choice depends on your load and your real shutdown duration.

Here is the rule I use:

1. Measure how long the node takes to stop guests and power down.

2. Add margin for battery aging and bad runtime estimates.

3. Pick a threshold that still leaves you breathing room.

If your node needs 4 minutes to stop cleanly, do not trigger shutdown at 5 minutes remaining and call that engineering.

That is gambling in a slightly more professional font.

Host vs LXC vs remote server

Let me save you some future forum browsing.

Run NUT on the Proxmox host when:

  • one UPS is directly attached to that host
  • you want the simplest failure path
  • your main priority is reliable shutdown, not pretty dashboards

Run a remote NUT server when:

  • a Synology or another Linux box already owns the UPS over USB
  • multiple systems need the same UPS status
  • your UPS is networked via SNMP

Avoid putting the whole control path only in an LXC when:

  • that LXC depends on the host state you are trying to protect
  • USB passthrough and container privileges make the setup fragile
  • you are building complexity before you have proven the basic path

You can absolutely use an LXC for dashboards or secondary monitoring. TheTechCorner and Kreaweb both show variants of that pattern. I just would not make it my first line of defense.

How to test without doing something stupid

Please test this in a maintenance window.

Not because it is dangerous in the dramatic sense. Because it is easy to think everything works when only the easy half works.

Test 1: Confirm NUT sees the UPS

upsc labups@localhost

You should get live values for charge, runtime, load, and state.

Test 2: Confirm services survive restart

systemctl restart nut-server nut-monitor\nsystemctl --no-pager --full status nut-server nut-monitor

Test 3: Review logs

journalctl -u nut-server -u nut-monitor -n 100 --no-pager

Test 4: Validate Proxmox guest shutdown order manually

Trigger a normal host shutdown in a controlled window and watch the guest sequence.

If the order is wrong, fix Proxmox. Do not blame the UPS.

Test 5: Simulate the event path carefully

For lab testing, many admins validate the logic by using NUT commands or temporarily adjusted thresholds. The exact method depends on your topology and comfort level.

The important part is verifying:

  • NUT detects the event
  • Proxmox starts guest shutdown cleanly
  • the host powers off before the battery is exhausted

What you do not want is your first real low-battery event doubling as your integration test.

A practical recommendation for most homelabs

If you have one Proxmox node and one USB UPS, do this:

  • install NUT on the Proxmox host
  • use usbhid-ups
  • keep MODE=standalone
  • keep monitoring local at first
  • set sane guest shutdown order
  • trigger shutdown with generous margin
  • test it once, then document it

If your lab is more complex, move to a remote NUT server only after you understand this baseline.

That is also true if you are already hardening the rest of your stack. Clean power handling is part of that same discipline, just like Homelab Firewall Rules and Proxmox ZFS Setup Guide are about reducing the blast radius of bad assumptions.

Recommended gear for this setup

I could pretend hardware does not matter here, but that would be dishonest.

The UPS itself matters. So does output waveform compatibility. So does battery replacement availability, which is the least glamorous buying criterion and one of the most important.

Here are the product classes I would look at for a Proxmox shutdown setup:

My buying rule is simple: buy enough UPS for your actual load, then add margin for shutdown time and future growth. Do not buy a tiny unit and then act surprised when runtime collapses the moment you add a NAS, a switch, and one slightly ambitious VM host.

Common mistakes to avoid

1. Putting NUT only in a container because it feels cleaner

Cleaner on paper is not always more reliable.

Your shutdown path should depend on as few moving parts as possible.

2. Trusting default runtime estimates blindly

UPS runtime values can be wrong. Battery age, temperature, and real load change everything.

3. Forgetting Proxmox guest shutdown order

This is the biggest practical mistake I see.

NUT can be perfect and your shutdown can still be messy.

4. Never testing the setup

You do not need drama. You do need evidence.

5. Using bargain-bin thresholds

If you trigger shutdown too late, all you did was automate panic.

FAQ

Should I run NUT directly on Proxmox or in an LXC container?

For one host with one directly attached UPS, run NUT on the Proxmox host. Use a container only for secondary monitoring or dashboards, not as the only control path unless you have a very specific design reason.

What battery threshold should trigger shutdown?

Start around 30 to 40 percent battery remaining, or 8 to 12 minutes of runtime, then adjust after measuring your node's real shutdown time. Conservative thresholds are boring, which is exactly what you want here.

Does Proxmox shut down VMs and containers automatically when the host powers off?

Yes, Proxmox can shut down guests cleanly during host shutdown, but only if you configure shutdown order and timeouts properly. Review those settings before you trust the UPS workflow.

Can I use a Synology NAS as the NUT server and Proxmox as the client?

Yes. That is a perfectly valid setup when the NAS is the device physically attached to the UPS. In that design, Proxmox becomes a NUT client and reacts to events from the NAS-hosted NUT server.

Should I use NUT or apcupsd for APC hardware?

If you want the shortest APC-only path, apcupsd is fine. If you want more flexibility, mixed topologies, or a path to multi-client monitoring, use NUT.

Final recommendation

If you are running Proxmox without automatic UPS-triggered shutdown, fix that before you spend another weekend optimizing something less important.

You do not need a huge redesign.

You need a UPS the host can talk to, NUT configured cleanly, Proxmox guest shutdown order set properly, and one real test to prove it all works. After that, the system becomes pleasantly boring. In infrastructure, boring is usually the compliment.