How to Set Up UPS Clean Shutdown on Proxmox and TrueNAS

Affiliate disclosure: If you buy through links on this site, we may earn a commission at no extra cost to you. Learn more

A UPS protects a home server only when the server knows that the battery is running down. Without that communication path, a mini PC and NAS keep working until power disappears. The result can be interrupted writes, damaged virtual machine state, or a storage pool that needs recovery.

Network UPS Tools, usually called NUT, provides that path. One computer connects to the UPS and runs the driver, the NUT data server, and the monitoring client. Other computers receive the status over the network and shut down as secondary clients. This arrangement works well for a Proxmox host, a TrueNAS system, and the small network switch between them.

This guide uses Debian-style paths for a Linux NUT primary and the current TrueNAS SCALE service screen for a TrueNAS primary or secondary. The exact driver still depends on the UPS. Confirm it in the NUT hardware compatibility list before copying a configuration.

The clean-shutdown design

NUT has three useful layers:

The driver talks to the UPS over USB, serial, network, or another supported interface.
upsd publishes the driver status to local and network clients.
upsmon watches the status and runs the shutdown command when the battery condition becomes critical.

The system with the direct UPS data connection is the primary. A system that only reads the status from the network is a secondary. The primary must stay on the UPS, along with the network equipment needed by the secondary clients. If the switch loses power first, a healthy NUT server becomes unreachable at exactly the wrong time.

For a single Proxmox host, the host can run all three layers. For a Proxmox host and a NAS, connect the data cable to whichever system is the more reliable NUT primary. Configure the other system as a secondary. Avoid two independent primary configurations pointed at the same USB UPS.

Before you edit anything

Prepare the shutdown path before simulating an outage.

Confirm the UPS is pure sine wave when the connected power supplies require it. The UPS sizing calculator helps check load and headroom.
Connect the UPS to wall power and give it time to charge.
Put the mini PC, NAS, switch, and any required access point on battery-backed outlets.
Confirm that a current backup exists and that you can restore it.
Keep local console access available. Do not depend on a remote session that may vanish when the switch or access point shuts down.
Record the UPS model, serial connection details, operating system version, and current service state.
Decide whether the system should shut down on low battery or after a fixed on-battery timer.

The site has not run this procedure on your specific UPS, Proxmox node, or TrueNAS installation. Treat the controlled battery test as your validation step after the configuration checks below.

Configure a Linux NUT primary

Install the NUT packages on the Linux host that owns the UPS data cable. On Debian or Ubuntu, the package names are:

sudo apt update
sudo apt install nut

Set the operating mode in /etc/nut/nut.conf:

MODE=netserver

netserver starts the driver, upsd, and upsmon. A host that only monitors a remote primary uses netclient instead.

1. Define the UPS driver

Edit /etc/nut/ups.conf and create one section for the UPS. This example uses the common HID driver and a local USB connection:

[homelab]
    driver = usbhid-ups
    port = auto
    desc = "Homelab UPS"

The homelab name is local. You can use another name, but use it consistently in every NUT file and command. USB drivers commonly accept auto for the port. Do not assume that usbhid-ups is correct for every model. Check the NUT hardware list and driver manual for the exact unit.

Start with the driver in the foreground so an error is visible:

sudo upsdrvctl start
sudo systemctl status nut-driver@homelab

On some distributions the driver unit name differs. The important check is that the driver starts without a permission, protocol, or device-not-found error.

2. Create the NUT data server account

Add a monitor account to /etc/nut/upsd.users:

[monuser]
    password = replace-this-with-a-long-local-password
    upsmon = primary

Use a unique password. Keep this file readable only by the NUT service account and administrators. The password is used by monitoring clients and must not be placed in a public article, screenshot, or shell history.

3. Bind the data server safely

By default, upsd may listen only on localhost. For secondary systems, add the primary host address or a restricted homelab interface to /etc/nut/upsd.conf:

LISTEN 127.0.0.1 3493
LISTEN 192.168.1.20 3493

Replace 192.168.1.20 with the primary host address. Do not expose port 3493 to the public internet. Use firewall rules so only the required homelab clients can reach it.

4. Configure the primary monitor

Edit /etc/nut/upsmon.conf:

RUN_AS_USER nut
MONITOR homelab@localhost 1 monuser replace-this-with-a-long-local-password primary
MINSUPPLIES 1
SHUTDOWNCMD "/sbin/shutdown -h +0"
POWERDOWNFLAG /etc/killpower
FINALDELAY 5

The MONITOR line combines the UPS name, server address, power value, credentials, and NUT role. The power value is normally 1 for a single UPS. SHUTDOWNCMD calls the normal operating system shutdown path, allowing Proxmox or other services to stop in their normal order.

The exact service layout varies between Linux distributions. Reload the services after checking their status:

sudo systemctl enable nut-driver@homelab nut-server nut-monitor
sudo systemctl restart nut-driver@homelab nut-server nut-monitor
sudo systemctl status nut-driver@homelab nut-server nut-monitor

5. Verify the primary

Ask NUT for the current device data:

upsc homelab@localhost
upsc homelab@localhost | grep -E 'ups.status|battery.charge|battery.runtime|input.voltage'

You should see a status such as OL when wall power is present. A missing device, stale data, or an empty status is a configuration problem. Check the driver journal before moving to Proxmox or TrueNAS:

sudo journalctl -u nut-driver@homelab -u nut-server -u nut-monitor --since "15 minutes ago"

Add Proxmox as a NUT client

If Proxmox owns the UPS cable, configure it as the primary using the Linux steps above. If another host owns the cable, install the NUT client package on the Proxmox node and set /etc/nut/nut.conf to:

MODE=netclient

The Proxmox node then needs an /etc/nut/upsmon.conf entry for the primary:

MONITOR homelab@192.168.1.20 1 monuser replace-this-with-a-long-local-password secondary
MINSUPPLIES 1
SHUTDOWNCMD "/sbin/shutdown -h +0"
FINALDELAY 5

Replace the address, username, and password with the values from the primary. Keep the client on the same private network as the NUT server and restrict port 3493 at the firewall.

Restart the monitor and inspect its log:

sudo systemctl enable nut-monitor
sudo systemctl restart nut-monitor
sudo systemctl status nut-monitor
upsc homelab@192.168.1.20

When a Proxmox host receives a normal shutdown request, Proxmox stops guests according to their configured shutdown behavior and then powers down the host. Guest applications still need their own service-level safety. A database, container, or virtual machine that ignores shutdown requests can delay the host or lose data even though NUT itself is working.

If you run several Proxmox nodes, give every node a secondary monitor entry. Make sure the switch and network path remain on the UPS. Also allow enough battery time for the primary and all secondary systems to finish their shutdown sequence.

Configure TrueNAS SCALE

TrueNAS SCALE manages NUT through its web interface. Open System Settings, choose Services, find UPS, and select Edit. Use the service screen instead of modifying generated NUT files by hand.

TrueNAS as the primary

Choose Master mode when the UPS data cable is connected directly to TrueNAS. Set the following values:

Identifier: a short name such as homelab
Driver: the driver listed for your UPS
Port: the port shown by TrueNAS for the attached device
Monitor user: a local NUT username
Monitor password: a unique local password
Shutdown mode: low battery or an on-battery timer
Shutdown command: the TrueNAS default unless your release documents another command
Power off UPS: enabled only when the UPS and the shutdown workflow support it

Enable the UPS service and start it automatically. Use System Settings, Shell, and run:

upsc homelab@localhost

TrueNAS documents upsc ups@localhost as the basic status check. If the configured identifier is not ups, use the identifier you selected. A polling error that repeats every few seconds can sometimes be reduced with this auxiliary ups.conf parameter:

pollinterval = 10

Use that setting only when the logs show the polling problem. It is not a universal fix.

TrueNAS as the secondary

Choose Slave mode when another system owns the UPS cable. Enter the primary host address, NUT port, identifier, monitor username, and monitor password. The TrueNAS service then reads status from the remote upsd instance and shuts down when the primary reports the critical battery condition.

The primary must stay available long enough for TrueNAS to finish. If TrueNAS stores the data that matters most, consider making it the primary and letting Proxmox monitor it as a secondary. The correct choice is the system with the better direct connection, service reliability, and shutdown priority.

The CyberPower USB autosuspend caveat

Some CyberPower HID units can connect successfully and then disappear after the Linux USB device enters an idle state. This looks like a NUT authentication or UPS failure, but the useful clue is usually in the driver journal. Search for repeated disconnects, USB reset messages, or a device that vanishes while the host remains online:

sudo journalctl -u nut-driver@homelab --since "2 hours ago"
lsusb
upsc homelab@localhost

Check the current kernel USB power policy before changing it. If autosuspend is the cause, apply a device-specific udev or kernel power rule for the UPS rather than disabling power management for every USB device. The exact rule depends on the vendor and product IDs from lsusb.

After applying a device-specific rule, reload udev, reconnect the UPS, and restart only the relevant NUT services:

sudo udevadm control --reload-rules
sudo udevadm trigger
sudo systemctl restart nut-driver@homelab nut-server nut-monitor
upsc homelab@localhost

Do not substitute CyberPower PowerPanel for NUT on a host that is already managed by NUT. Two monitoring daemons competing for the same USB device can create a less reliable result. Pick one management stack and confirm that it owns the device cleanly.

How to test the shutdown path safely

Do not begin by pulling the UPS plug. First verify the software path while wall power is present:

Confirm upsc reports the expected status and battery values.
Confirm the primary and every secondary can reach the NUT server.
Review the Proxmox guest shutdown order and TrueNAS service state.
Confirm a recent backup and keep a local console open.
Start a controlled battery test using the UPS controls or the documented procedure for that model.
Watch NUT status and system logs from the console.
Confirm that the warning state arrives before the shutdown threshold.
Restore wall power before the battery reaches a dangerous level unless the planned test specifically validates the final shutdown.

The first test should prove monitoring and alerts. A later test can validate the full shutdown sequence after you know how much battery time the load provides. Runtime depends on the UPS battery, load, age, temperature, and power factor. Do not copy a runtime number from another homelab.

Troubleshooting checklist

upsc says the connection is refused: Check that upsd is running, port 3493 is reachable on the private network, and LISTEN includes the primary host address.

The driver cannot find the UPS: Check the USB cable, permissions, driver choice, and lsusb. If another power-management program has claimed the device, stop it before restarting NUT.

TrueNAS shows repeated communication errors: Confirm the identifier, mode, and credentials. For a directly connected device, inspect the console messages and try the documented polling interval adjustment only if the logs support it.

Proxmox shuts down but guests remain active: Review each guest’s shutdown setting, guest agent status, and service timeout. NUT only starts the host shutdown path.

The system shuts down too late: A low-battery threshold may leave too little time for the load. Reduce the on-battery timer, reduce the protected load, or choose a UPS with more watt capacity and battery energy.

The UPS disappears after idle time: Investigate USB autosuspend first, especially with CyberPower HID models. Apply a device-specific power rule and confirm the driver stays connected before changing shutdown thresholds.

Final checks

A working clean-shutdown setup has four visible proofs:

upsc reports live UPS data.
The primary and secondary roles are unambiguous.
Proxmox and TrueNAS use their normal shutdown paths.
A controlled battery test reaches the expected warning and shutdown behavior.

Once those checks pass, label the UPS data cable, record the NUT credentials in your password manager, export the TrueNAS configuration, and keep the recovery notes with the homelab documentation. A UPS is part of the server’s failure-handling system, so its configuration deserves the same backup attention as the storage and virtualization settings.

Frequently Asked Questions

Should the Proxmox host or TrueNAS system be the NUT primary?

Make the system with the direct USB or serial connection the NUT primary. Other systems monitor that primary as secondaries over the network.

Yes. Connect the UPS data cable to one primary system, then configure the other system as a NUT secondary. All systems must have enough battery time to shut down in order.

Why does my CyberPower UPS disappear from NUT?

Some CyberPower USB devices can hit a Linux USB autosuspend problem. Check driver logs, disable autosuspend for the UPS device, and restart the NUT driver before changing the shutdown policy.

Does a NUT shutdown stop every virtual machine cleanly?

The host sends its normal shutdown sequence, but application safety still depends on guest services, filesystem state, and the guest shutdown configuration.

How long should the UPS wait before shutdown?

Use a short delay for a small homelab, often five to ten minutes when the battery and load allow it. A low-battery policy is safer than a timer when runtime is uncertain.

How do I verify that UPS monitoring works?

Check the driver and upsc output, review upsmon logs, confirm the host sees the battery state, and perform a controlled battery test only after backup and console access are ready.

How We Researched This Guide

We based the configuration examples on the NUT user manual, the NUT manual pages, the TrueNAS UPS service documentation, and CyberPower’s Linux software documentation. The examples are templates. Driver names, service units, interface addresses, and shutdown behavior can vary by release and hardware.