Stop the Power-Loss Panic: Mastering Network UPS Tools (NUT) for Your HomeLab

The High Cost of a Brief Flicker

It was 2 AM on a Tuesday when a three-second power dip knocked my entire HomeLab offline. The hardware survived, but the aftermath was brutal. My ZFS pool on TrueNAS required a six-hour scrub, and two MariaDB containers suffered unrecoverable table corruption. That night taught me a hard lesson: an Uninterruptible Power Supply (UPS) is useless if your servers don’t know they’re running on battery.

Configuring Network UPS Tools (NUT) changes the game. It moves your lab from a collection of fragile hobbyist machines to a resilient, production-grade setup. If your UPS is just a ‘dumb battery’ plugged into the wall, you are only halfway protected. NUT enables your servers to monitor battery health, track power draw, and—most importantly—trigger a graceful shutdown before the voltage drops too low.

NUT uses a server-client architecture. One machine, the Primary (Master), connects directly to the UPS via USB. Other machines, the Secondaries (Slaves), listen over the network. When the battery hits a critical threshold—perhaps 15% remaining—the Primary signals every Secondary to shut down immediately. Once the clients are safe, the Primary powers itself down.

Installing NUT on Linux

Most labbers use Ubuntu, Debian, or Proxmox. NUT is available in their standard repositories, making installation straightforward. I recommend using your most stable, 24/7 machine as the Primary server. A low-power Raspberry Pi 4 or your main Proxmox node is an ideal candidate.

First, update your package list and install the necessary components:

sudo apt update
sudo apt install nut nut-client nut-server

Next, identify which driver your hardware needs. Connect your UPS to the server via USB and run the scanner utility:

nut-scanner -U

This tool identifies the correct driver. For most modern CyberPower, APC, or Eaton units, you will see usbhid-ups. Note the vendor and product IDs provided in the output; you will need them in the next step.

Configuring the NUT Primary Server

You will primarily work within four files in /etc/nut/. These manage the driver, the data server, and the monitoring daemon.

1. Define the UPS Driver

Open /etc/nut/ups.conf. This file tells NUT how to communicate with the physical hardware. Use the values you gathered from the scanner:

[myups]
    driver = usbhid-ups
    port = auto
    desc = "CyberPower CP1500PFCLCD"
    vendorid = 0764
    productid = 0501

2. Configure the Data Server

Edit /etc/nut/upsd.conf. By default, NUT only listens to the local machine. To allow other servers in your rack to monitor the battery, add your server’s static IP address:

LISTEN 127.0.0.1 3493
LISTEN 192.168.1.50 3493 # Use your server's actual IP

3. Create Secure Users

NUT requires authentication for network clients. Edit /etc/nut/upsd.users. I create one administrative account for the local machine and a restricted account for remote clients:

[upsmon_primary]
    password = your_strong_password
    upsmon master

[upsmon_secondary]
    password = secondary_password
    upsmon slave

4. Set the Operating Mode and Monitor

Set the system mode in /etc/nut/nut.conf to netserver. Finally, tell the server to monitor itself by adding this line to /etc/nut/upsmon.conf:

MONITOR myups@localhost 1 upsmon_primary your_strong_password master

Restart the services to apply your new configuration:

sudo systemctl restart nut-server nut-client
sudo upsdrvctl stop
sudo upsdrvctl start

Verification and Testing

Query your UPS status using the upsc command. It should return a detailed list of metrics, including battery charge, input voltage, and current load in Watts.

upsc myups@localhost

Check the ups.status line. OL means you are on Online power. If you pull the plug from the wall, it should switch to OB (On Battery) within two seconds. If your lab draws 150W on a 1500VA UPS, you might see roughly 25 to 30 minutes of runtime.

The Moment of Truth: Testing the Shutdown

Never assume your configuration works until you see it happen. You do not want to troubleshoot a config error while your battery is at 2% during a real outage. Trigger a simulated “forced shutdown” (FSD) to verify the sequence:

sudo upsmon -c fsd

Warning: This command initiates an immediate shutdown of all connected systems. Save your work before hitting Enter.

Adding Secondary Clients

For every other machine in your lab, like a dedicated Plex server or a backup node, install only nut-client. Set MODE=netclient in /etc/nut/nut.conf and add the following to /etc/nut/upsmon.conf:

MONITOR [email protected] 1 upsmon_secondary secondary_password slave

These clients will now wait for the Primary to signal a critical power event. When that signal arrives, they will trigger their own shutdown -h now command automatically.

Visualizing Your Power

If you use a monitoring stack like Grafana, the Telegraf NUT plugin can scrape these metrics for you. Seeing your real-time power consumption and battery health on a dashboard is incredibly satisfying. It helps with capacity planning and ensures you aren’t overloading your UPS as you add more gear to your rack.

Implementing NUT moves you beyond simple hardware protection. You have built an automated orchestration system that saves you from hours of data recovery. The next time the grid fails, your lab will handle it with professional-grade grace.