UPS Tools (Network UPS Tools) Setup Guide#

This guide covers the installation of a NUT Server on a central VM (230) and the configuration of NUT Clients (Proxmox nodes) to ensure graceful shutdowns across your infrastructure.

1. NUT Server Installation (VM 230)#

Prerequisites & Software#

# Verify USB visibility (Ensure USB passthrough is configured in Proxmox)
lsusb

# Install NUT suite
apt update && apt install nut nut-client nut-server -y

Ubuntu 24.04 (NUT 2.8.1) Library Fix#

If USB scanning fails on Ubuntu 24.04, create the following symlinks:

pushd /usr/lib/x86_64-linux-gnu/
sudo ln -s libusb-1.0.so.0 libusb-1.0.so
sudo ln -s libnetsnmp.so.40 libnetsnmp.so
sudo ln -s libavahi-client.so.3 libavahi-client.so
sudo ln -s libfreeipmi.so.17 libfreeipmi.so
sudo ln -s libneon-gnutls.so.27 libneon.so
popd

2. Server Configuration#

Define UPS Units (`/etc/nut/ups.conf`)#

Identify your serial numbers using nut-scanner -U.

pollinterval = 15
maxretry = 3

[ups1]
    driver = usbhid-ups
    port = auto
    desc = "UPS1 Cogeco-UDM-SE-USW8-MacMini"
    vendorid = 051d
    productid = 0002
    serial = 4B2204P27370

[ups2]
    driver = usbhid-ups
    port = auto
    desc = "UPS2 USW24-Aggregation-USB"
    vendorid = 051d
    productid = 0002
    serial = 5B2334T39839

[ups3]
    driver = usbhid-ups
    port = auto
    desc = "UPS3 HP4-HP6-HP7-UNAS-MP52"
    vendorid = 051d
    productid = 0002
    serial = 4B2211P16160

[ups4]
    driver = usbhid-ups
    port = auto
    desc = "UPS4 HP1-HP2-HP3-HP5"
    vendorid = 051d
    productid = 0002
    serial = 0B2328L01407

Network & User Access#

/etc/nut/nut.conf

MODE=netserver

/etc/nut/upsd.conf

LISTEN 0.0.0.0 3493

/etc/nut/upsd.users

[admin]
    password = H6R49u7b
    actions = SET
    instcmds = ALL

[monuser]
    password = H6R49u7b
    upsmon master

3. Web Monitoring (NUT CGI)#

Visualize your UPS status via Apache.

apt install apache2 nut-cgi -y
a2enmod cgi
systemctl restart apache2

# Edit the config file
nano /etc/nut/hosts.conf

MONITOR ups1@localhost "UPS1 MacMini-HP2"
MONITOR ups2@localhost "UPS2 UNVR-Cogeco-USB"
MONITOR ups3@localhost "UPS3 UNAS-HP3-HP4-HP6"
MONITOR ups4@localhost "UPS4 UDM-SE-Aggr1-Aggr2"

Access URL: http://10.1.2.230/cgi-bin/nut/upsstats.cgi

4. NUT Client Configuration (Proxmox Nodes)#

Client Setup (`/etc/nut/upsmon.conf`)#

Point the client to the specific UPS protecting that node (e.g., ups3).

RUN_AS_USER root
MONITOR ups3@10.1.2.230 1 monuser H6R49u7b slave

MINSUPPLIES 1
SHUTDOWNCMD "/sbin/shutdown -h now"
NOTIFYCMD /usr/sbin/upssched
POLLFREQ 2
DEADTIME 15
POWERDOWNFLAG /etc/killpower

NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
NOTIFYFLAG ONLINE SYSLOG+WALL+EXEC
NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC

Scheduler Logic (`/etc/nut/upssched.conf`)#

CMDSCRIPT /etc/nut/upssched-cmd
PIPEFN /etc/nut/upssched.pipe
LOCKFN /etc/nut/upssched.lock

# Start 10-minute timer on battery
AT ONBATT * START-TIMER shutdown_timer 600
AT ONLINE * CANCEL-TIMER shutdown_timer
AT LOWBATT * EXECUTE immediate_shutdown

Command Script (`/etc/nut/upssched-cmd`)#

#!/bin/sh
case $1 in
    shutdown_timer)
        logger -t upssched-cmd "UPS on battery too long, initiating shutdown"
        /usr/sbin/upsmon -c fsd
        ;;
    immediate_shutdown)
        logger -t upssched-cmd "Critical battery! Forced shutdown"
        /usr/sbin/upsmon -c fsd
        ;;
    *)
        logger -t upssched-cmd "Unrecognized command: $1"
        ;;
esac

chmod +x /etc/nut/upssched-cmd
systemctl restart nut-client

5. Verification#

# Check communication from client to server
upsc ups3@10.1.2.230

6. Run UPS test#

# Add description
upscmd -u monuser -p H6R49u7b UPS4@10.1.2.230 test.battery.start.quick