Uninterruptible Power Supply

The source material this page replaces covers installing the NUT server on an OpenWrt router with the UPS connected directly to it via USB. In this network, the UPS is connected to the February homelab server, which runs as the NUT primary. The router, desktop, and NAS are all NUT secondary clients.

This page covers the router’s role in the UPS shutdown sequence: how the UDM-SE connects to the NUT server on the homelab, receives power event notifications, and shuts down cleanly before the battery is exhausted.

The desktop NUT client configuration was covered in the Desktop Toolbox section. The NUT server configuration is covered in the Server section. This page covers the router-specific aspects.

Architecture

APC UPS ──USB── February (NUT primary)
                    │
                    ├── NUT secondary: Prevernal (UDM-SE)
                    ├── NUT secondary: Desktop
                    └── NUT secondary: NAS

The primary is responsible for:

• Reading UPS status from the USB connection
• Broadcasting power events to all secondary clients
• Instructing secondaries to shut down when battery is low
• Issuing the final UPS shutdown command after all secondaries confirm they are down

The router’s responsibilities as a secondary:

• Connect to the NUT primary and monitor power status
• Shut down cleanly when instructed
• Not cut power before the primary and other secondaries are ready

UniFi UPS integration

The UDM-SE has native UPS monitoring support via UniFi OS. This is the cleanest integration for a UniFi router: no custom software needed, management via the web interface.

Navigate to UniFi OS > Settings > UPS.

Configure the UPS connection:

Once configured, UniFi OS monitors the UPS via the homelab NUT server and can:

• Display UPS status (battery charge, load, runtime estimate) in the UniFi dashboard
• Send notifications when the UPS switches to battery
• Initiate a graceful shutdown when battery is low

Verify the connection status in UniFi OS > Settings > UPS > Status. The UPS status should show online and display battery charge and load percentage.

NUT client via SSH (alternative approach)

If the UniFi native UPS integration does not work with your NUT server version or configuration, the NUT client can be configured manually via SSH.

The UDM-SE runs a Debian-based system with apt available. Install the NUT monitor:

ssh prevernal
apt update
apt install nut-client

/etc/nut/nut.conf

tee /etc/nut/nut.conf << 'EOF'
MODE=netclient
EOF

/etc/nut/upsmon.conf

tee /etc/nut/upsmon.conf << 'EOF'
# NUT secondary client configuration for Prevernal

RUN_AS_USER nut

# Monitor the UPS on the homelab server
MONITOR apc@10.1.0.x 1 upsmon-secondary <password> secondary

MINSUPPLIES 1
SHUTDOWNCMD "/bin/systemctl poweroff"
POLLFREQ 5
POLLFREQALERT 5
HOSTSYNC 15
DEADTIME 15
POWERDOWNFLAG /etc/killpower
FINALDELAY 5

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

chmod 0640 /etc/nut/upsmon.conf
chown root:nut /etc/nut/upsmon.conf

Enable and start the NUT monitor:

systemctl enable --now nut-monitor

Verify it is connected:

upsc apc@10.1.0.x

This should return UPS status information. If it shows an error, check connectivity to the NUT server and the credentials.

Note: manual SSH changes to UniFi OS may be overwritten by firmware updates. If using the manual NUT client configuration rather than the native UniFi UPS integration, verify it survives firmware upgrades and re-apply if needed.

Firewall rules

The NUT protocol uses TCP port 3493. Traffic from the router to the homelab server on this port must be permitted.

On the homelab server firewall:

sudo ufw allow from 10.1.0.0/24 to any port 3493 proto tcp

Since the router is on the Core VLAN at the primary site, and the homelab server is also on the Core VLAN, this traffic stays within the same VLAN and does not need additional firewall rules on the UniFi side.

For the secondary site routers (Vernal, Estival), traffic from their Core VLANs (10.2.0.1 and 10.3.0.1) must reach the homelab server’s NUT port via the inter-site VPN. Add those to the firewall allow rules:

sudo ufw allow from 10.2.0.0/24 to any port 3493 proto tcp
sudo ufw allow from 10.3.0.0/24 to any port 3493 proto tcp

Secondary sites

Vernal and Estival do not have local UPS hardware. They connect to the primary NUT server via the inter-site VPN. Their NUT configuration is identical to Prevernal’s, substituting their respective IP addresses.

When the UPS at the primary site is on battery and approaching low battery:

1. The NUT primary sends FSD (forced shutdown) to all secondaries
2. Prevernal shuts down cleanly
3. Vernal and Estival also receive the FSD command over the VPN and shut down
4. Once all secondaries confirm shutdown, the primary shuts down
5. The UPS cuts power

This means a power failure at the primary site initiates a controlled shutdown across all three sites, since all secondary site routers are monitoring the same UPS.

Whether this is the desired behaviour depends on the network design. If the secondary sites should remain operational during a primary site power event, configure them to monitor a local UPS at each site rather than the primary’s UPS. This is the correct architecture for true multi-site resilience and is a future improvement once each site has UPS hardware.

Testing

Test the UPS shutdown sequence without pulling the power. This is important: do it once during initial setup and after any major change to the NUT configuration.

From the homelab server, trigger a test forced shutdown:

sudo upsmon -c fsd

This tells the NUT primary to send FSD to all connected secondaries. All machines should begin their shutdown sequence within HOSTSYNC seconds (15 seconds by default).

Watch the router’s behaviour:

# From the desktop, before triggering FSD
ssh prevernal 'journalctl -u nut-monitor -f'

The log should show FSD received and the shutdown sequence beginning.

Verify what the source material recommends: check that all secondaries receive the shutdown command, that the primary waits long enough for them to complete, and that power returns cleanly after the sequence completes.

Do not test by disconnecting the UPS from mains power unless you have confirmed the software sequence works first.

The UPS is only as useful as the shutdown sequence it enables. An untested shutdown sequence is not a shutdown sequence. Test it within the first week of deployment and document the results.