NUT (Network UPS Tools) Setup on Proxmox

Purpose: This guide configures NUT to monitor an SNMP-enabled UPS (such as Riello, APC, etc) on Proxmox, allowing for graceful shutdown during power events (A USB USB is very similar but doesn't require snmp or nut-snmp and you will probably use the usbid-ups driver which is included).

1. Installation

Install the required NUT packages:

apt install nut snmp nut-snmp

2. Configuration Files

2.1 Main NUT Configuration

/etc/nut/nut.conf

MODE=netserver

netserver mode allows NUT to serve UPS data to network clients.

2.2 UPS Definition

/etc/nut/ups.conf

[myups]
driver = snmp-ups
port = 10.1.1.29
community = public
desc = "Riello UPS"
override.battery.charge.low = 30

Note: Replace 10.1.1.29 with your UPS IP address. Change community if your UPS uses a different SNMP community string.

2.3 UPS Daemon Configuration

/etc/nut/upsd.conf

LISTEN 0.0.0.0 3493

This allows the UPS daemon to listen on all interfaces on port 3493.

2.4 User Authentication

/etc/nut/upsd.users

[upsadmin]
password = BadBadBattery!
actions = SET
actions = FSD
instcmds = ALL
upsmon master

[upsuser]
password = ItsDark!
upsmon slave

Security: Change these default passwords! The upsadmin user has full control, whilst upsuser is for monitoring only.

2.5 UPS Monitor Configuration

/etc/nut/upsmon.conf

MINSUPPLIES 1
SHUTDOWNCMD "/sbin/shutdown -h +0"
POLLFREQ 5
POLLFREQALERT 5
HOSTSYNC 15
DEADTIME 15
POWERDOWNFLAG /etc/killpower
RBWARNTIME 43200
NOCOMMWARNTIME 300
FINALDELAY 5

RUN_AS_USER root
MONITOR myups@localhost 1 upsadmin BadBadBattery! master
NOTIFYCMD /usr/sbin/upssched

3. Key Configuration Parameters

• MINSUPPLIES 1: Minimum number of UPS units required
• SHUTDOWNCMD: Command executed during shutdown - Note in this example we're using -h to power off the machine after shutdown, and +0 for immediate shutdown. See below for more advanced configurations. 
• POLLFREQ 5: Poll UPS every 5 seconds (normal operation)
• POLLFREQALERT 5: Poll frequency during alerts
• DEADTIME 15: Seconds before declaring UPS dead
• RBWARNTIME 43200: Replace battery warning (12 hours)

4. Starting Services

After configuration, start and enable the NUT services:

systemctl start nut-server
systemctl start nut-monitor
systemctl enable nut-server
systemctl enable nut-monitor

5. Testing

Verify the setup is working:

upsc myups@localhost

This should display UPS status information including battery charge, load, and input voltage.

6. Troubleshooting

• Check logs: journalctl -u nut-server and journalctl -u nut-monitor
• Verify SNMP connectivity: snmpwalk -v1 -c public 10.1.1.29
• Test UPS driver: /lib/nut/snmp-ups -a myups

Important: Test the shutdown procedure during a maintenance window to ensure Proxmox shuts down gracefully when the UPS battery is low.

7. Advanced Configurations

It is possible to use a far more advanced shutdown model for Promox, for example you could run a bash script in SHUTDOWNCMD which, for example does; 

qm shutdown 100
qm shutdown 101
qm migrate 102 node2
qm suspend 103
...
shutdown -h +0

This enables far more granular control over the shutdown process and the migration of services etc. What you actually do is up to you but the tools are here.