Complete Proxmox NUT Client Configuration Guide

Configuring Proxmox VE as NUT Client for Synology NAS UPS Server

This guide configures your Proxmox hypervisor to monitor a UPS connected to a Synology NAS and automatically handle power events with graceful shutdowns.

Prerequisites

Synology NAS with UPS connected and configured
Proxmox VE server on the same network
Root access to Proxmox server

Step 1: Install NUT on Proxmox

Connect to your Proxmox server via SSH and install the Network UPS Tools:

apt-get update
apt-get install nut

Step 2: Configure NUT Client Mode

Edit the NUT configuration file:

vi /etc/nut/nut.conf

Modify the last line to set client mode:

MODE=netclient

Step 3: Configure UPS Monitoring

Edit the UPS monitoring configuration:

vi /etc/nut/upsmon.conf

Add the following line (look for other MONITOR example comments and add after them):

MONITOR [email protected] 1 monuser secret slave

Parameters explained:

[email protected] - Replace with your NAS IP address
1 - Power value (1 unless you have multiple UPS units)
monuser secret - Default Synology NAS NUT credentials
slave - This server is a client, not the UPS master

Step 4: Configure Notification Flags

In the same /etc/nut/upsmon.conf file, add or uncomment the following notification flags:

NOTIFYFLAG ONLINE     SYSLOG+EXEC
NOTIFYFLAG ONBATT     SYSLOG+EXEC
NOTIFYFLAG LOWBATT    SYSLOG+EXEC
NOTIFYFLAG FSD        SYSLOG+WALL+EXEC
NOTIFYFLAG COMMOK     SYSLOG+EXEC
NOTIFYFLAG COMMBAD    SYSLOG+EXEC
NOTIFYFLAG SHUTDOWN   SYSLOG+WALL+EXEC
NOTIFYFLAG REPLBATT   SYSLOG+WALL+EXEC
NOTIFYFLAG NOCOMM     SYSLOG+WALL+EXEC
NOTIFYFLAG NOPARENT   SYSLOG+WALL+EXEC

Add the notification command:

NOTIFYCMD /usr/sbin/upssched

Step 5: Configure UPS Scheduler

Edit the UPS scheduler configuration:

vi /etc/nut/upssched.conf

Update the CMDSCRIPT to point to the correct path:

CMDSCRIPT /usr/bin/upssched-cmd

Uncomment or add the following lines:

PIPEFN /run/nut/upssched/upssched.pipe
LOCKFN /run/nut/upssched/upssched.lock

Add the scheduling commands:

AT ONLINE * EXECUTE online
AT ONBATT * EXECUTE onbatt
AT LOWBATT * EXECUTE lowbatt

Step 6: Create Shutdown Script

Create the command script that handles power events:

vi /usr/bin/upssched-cmd

Add the following content (replace IP address with your NAS IP):

#!/bin/sh
#
# UPS event handler script for Proxmox
# Called by upssched via CMDSCRIPT directive
#

UPS="[email protected]"

STATUS=$( upsc $UPS ups.status )
CHARGE=$( upsc $UPS battery.charge )
CHMSG="[$STATUS]:$CHARGE%"

case $1 in
        online)
                MSG="$UPS, $CHMSG - power supply has been restored."
                # Cancel any pending shutdown
                /sbin/shutdown -c
                ;;
        onbatt)
                MSG="$UPS, $CHMSG - power failure - save your work!"
                # Shutdown VMs gracefully first
                echo "Shutting down VMs..." | logger -i -t upssched-cmd
                qm list | awk 'NR>1 {print $1}' | xargs -I {} qm shutdown {}
                sleep 30
                # Schedule host shutdown in 2 minutes
                /sbin/shutdown -h +2
                ;;
        lowbatt)
                MSG="$UPS, $CHMSG - critical battery level - shutdown now!"
                # Immediate shutdown
                echo "Shutting down VMs immediately..." | logger -i -t upssched-cmd
                qm list | awk 'NR>1 {print $1}' | xargs -I {} qm shutdown {} --timeout 10
                sleep 15
                /sbin/shutdown -h now
                ;;
        upsgone) 
                MSG="The UPS $UPS has been gone for awhile" 
                ;;
        *) 
                MSG="$UPS, $CHMSG - Unrecognized command: $1" 
                ;;
esac

logger -i -t upssched-cmd $MSG

Make the script executable:

chmod +x /bin/upssched-cmd

Step 7: Enable and Start Services

Enable the NUT services to start automatically:

systemctl enable nut-client
systemctl enable nut-monitor

Start the monitoring services:

systemctl start nut-client
systemctl start nut-monitor

Step 8: Verify Configuration

Check that services are running properly:

systemctl status nut-client
systemctl status nut-monitor

Test UPS communication:

upsc [email protected]

This should return UPS information including battery status, load, etc.

Check connected clients:

upsc -c ups

Step 9: Test the Configuration

Important: Test your setup before relying on it in production.

Test UPS communication: Verify the upsc command returns UPS data
Test notifications: Check /var/log/syslog for NUT messages
Test shutdown behavior:
- Simulate power loss (if safe to do so)
- Monitor that VMs shutdown gracefully
- Verify host shutdown behavior

Customization Options

Adjust Shutdown Timing

Modify the shutdown delay in /bin/upssched-cmd:

Change +2 to +5 for 5-minute delay
Adjust VM shutdown timeout as needed

Add Email Notifications

Install mailutils and add email alerts to the script:

apt-get install mailutils

Add to script cases:

echo "$MSG" | mail -s "UPS Alert" [email protected]

Monitor Multiple UPS Units

Add additional MONITOR lines in /etc/nut/upsmon.conf for each UPS.

Troubleshooting

Common issues:

Connection refused: Check NAS IP address and NUT service status on Synology
Authentication failed: Verify monuser/secret credentials on NAS
Services won't start: Check configuration file syntax
No shutdown on power loss: Verify script permissions and paths

Log locations:

/var/log/syslog - General NUT and system logs
journalctl -u nut-client - NUT client specific logs
journalctl -u nut-monitor - NUT monitor specific logs

Security Considerations

Consider changing default NUT credentials on your Synology NAS
Restrict network access to NUT port (3493) to trusted hosts only
Test your configuration regularly to ensure it works when needed

References:

https://www.johnra.me/2024/05/16/synology-ups-as-nut-primary/

This configuration provides automated power management for your Proxmox environment, ensuring graceful shutdowns during power outages while allowing quick recovery when power is restored.

karthicraghupathi/Proxomox - NUT Client - Synology NAS.md