Nexapp - UPS(NUT)

UPS (NUT)

An Uninterruptible Power Supply (UPS) provides backup power when the main supply fails. It protects equipment such as firewalls and servers from power loss and enables safe shutdown to avoid corruption or service disruption.

Network UPS Tools (NUT) is a suite that allows NexappOS to monitor and manage UPS hardware. This guide explains how to configure a USB-connected UPS so that:

the UPS is monitored continuously
the firewall shuts down safely when battery level is critical

Note: NUT is an extra package and is not installed by default. It is not supported on systems with a NexappOS subscription (advanced users only).

What gets installed

NUT is made of several packages. The most important are:

nut-server – connects to the UPS and exposes status to clients
nut-upsc – CLI tool to query UPS status
nut-upsmon – daemon that monitors UPS and triggers shutdown
nut-upscmd – CLI tool to send commands to the UPS (model-dependent)

Configure a local UPS (USB)

Before starting, connect the UPS to the firewall with the USB cable.

Step 1 — Install NUT packages

opkg update
opkg install nut-server nut-upsc nut-upsmon nut-upscmd

These packages are not preserved during upgrades. See Restore extra packages if you want them reinstalled automatically.

Step 2 — Detect UPS and install driver

List connected USB devices:

lsusb

Example output:

Bus 002 Device 002: ID 0463:ffff EATON 5E
Bus 002 Device 001: ID 1d6b:0002 Linux 5.15.150 xhci-hcd xHCI Host Controller

Pick the correct driver from the NUT driver list. Most USB UPS models work with usbhid-ups.

Install driver package:

opkg install nut-driver-usbhid-ups

Register the driver in NUT:

uci set nut_server.eaton5e=driver
uci set nut_server.eaton5e.driver=usbhid-ups
uci set nut_server.eaton5e.port=auto

uci set nut_server.upsd=upsd
uci commit nut_server

Keep note of the UPS name (eaton5e here). You’ll need it in the next step.

Step 3 — Configure monitoring (upsmon)

Create a local monitoring user in upsd:

uci set nut_server.upsuser=user
uci set nut_server.upsuser.username=upsuser
uci set nut_server.upsuser.password=password
uci set nut_server.upsuser.upsmon=master

Configure upsmon to monitor the UPS locally:

uci set nut_monitor.upsmon=upsmon
uci set nut_monitor.master=master
uci set nut_monitor.master.upsname=eaton5e
uci set nut_monitor.master.hostname=localhost
uci set nut_monitor.master.username=upsuser
uci set nut_monitor.master.password=password

Commit and restart:

uci commit nut_server
uci commit nut_monitor

/etc/init.d/nut-server restart
/etc/init.d/nut-monitor restart

Step 4 — Verify UPS status

Query UPS status:

upsc eaton5e

Typical output:

battery.charge: 100
battery.runtime: 2637
device.mfr: EATON
device.model: 5E 850i
...

Check logs if needed:

tail -n 50 /var/log/messages

Good server log example:

upsd: Connected to UPS [eaton5e]: usbhid-ups-eaton5e

Good upsmon log example:

upsmon: Communications with UPS eaton5e@localhost established

Once working, NexappOS will shut down automatically when battery is critical (usually <20%).

Allow remote monitoring (optional)

By default NUT listens only on localhost. To monitor the UPS from another machine:

1) Listen on all interfaces

uci set nut_server.listen=listen_address
uci set nut_server.listen.address=0.0.0.0

2) Add a remote user (use a strong password)

uci set nut_server.remoteuser=user
uci set nut_server.remoteuser.username=remoteuser
uci set nut_server.remoteuser.password=password

uci commit nut_server
/etc/init.d/nut-server restart

3) Verify server is listening

netstat -tuln | grep 3493

4) Allow access from LAN (TCP/3493)

uci set firewall.ns_allow_nut=rule
uci set firewall.ns_allow_nut.name='Allow-NUT-from-LAN'
uci set firewall.ns_allow_nut.proto='tcp'
uci set firewall.ns_allow_nut.src='lan'
uci set firewall.ns_allow_nut.dest_port='3493'
uci set firewall.ns_allow_nut.target='ACCEPT'

uci commit firewall
/etc/init.d/firewall restart

Connect a remote client to the NUT server

On the client firewall/machine, install monitor tools:

opkg update
opkg install nut-upsc nut-upsmon

Configure upsmon as a slave:

uci set nut_monitor.upsmon=upsmon
uci set nut_monitor.slave=slave
uci set nut_monitor.slave.upsname=eaton5e
uci set nut_monitor.slave.hostname=192.168.1.8
uci set nut_monitor.slave.username=remoteuser
uci set nut_monitor.slave.password=password

uci commit nut_monitor
/etc/init.d/nut-monitor restart

Verify remote query:

upsc eaton5e@192.168.1.8

If it returns data, the client is correctly connected and will shut down when battery is low.

Extra UPS commands (model-dependent)

Grant the local user permission to run UPS commands:

uci add_list nut_server.upsuser.instcmd=all
uci add_list nut_server.upsuser.actions=set
uci commit nut_server
/etc/init.d/nut-server restart

List supported commands:

upscmd -l eaton5e

Example: disable UPS beeper

upscmd -u upsuser -p password eaton5e beeper.disable

Troubleshooting

Permission denied on ups.conf

Example error:

Can't open /etc/nut/ups.conf: Permission denied

Check file ownership and that the driver is installed correctly.

UPS not detected / flapping connection

Example logs:

UPS [eaton5e] is not currently connected
UPS [eaton5e] is now connected as FD -1

This can happen if NUT starts before USB is ready.

Fix 1 (recommended): reboot

reboot

Fix 2 (no reboot): restart NUT and test driver manually

/etc/init.d/nut-server stop
/lib/nut/usbhid-ups -a eaton5e

If still failing, reset the USB device:

Find USB bus/device ID with lsusb
Reset it:

usbreset 002/003

(Replace with your actual bus/device numbers.)