When the power goes out, everything in a smart home drops at the same moment: the router, the switch, the machine running your home automation software, the Zigbee or Thread coordinator plugged into it, and the NAS holding its backups. Short outages then turn into long ones, because devices come back in random order and anything that was writing to disk may come back with a damaged file system.

An uninterruptible power supply (UPS) covers the first part: it keeps the equipment running through short outages. The second part is software. The Network UPS Tools (NUT) documentation sums up its job in one sentence: "The whole point of UPS software is to bring down the OS cleanly when you run out of battery power." This guide covers choosing a UPS for this kind of load and setting up NUT on a Linux machine such as a Raspberry Pi, so that it shuts down on time and starts again when the power returns.

What belongs on the UPS

Put the equipment that the rest of the house depends on behind the UPS:

  • the modem or ONT and the router;
  • the main network switch and any access points powered from it;
  • the computer running your home automation server, with its USB radio adapters;
  • a NAS or backup disk, if it is on all the time.

Leave out anything with a heating element or a large motor. A UPS should run well below its rating: APC recommends not exceeding 80% of the rated capacity. Runtime falls as the load grows, so a small network-and-server load on a modest UPS gives far more minutes than the same unit near its limit. Manufacturers publish runtime charts for each model, and once NUT is running, the UPS reports its own estimate.

Standby, line-interactive or online

Eaton describes three UPS designs.

Standby (offline) units pass mains power straight through and switch to the battery when it fails. The transfer takes around 10 ms or less, and on battery they usually produce a simulated sine wave. Eaton considers them suitable for modems and routers but does not recommend them for PCs and servers.

Line-interactive units add automatic voltage regulation, which corrects sags and surges without touching the battery. Some models output a pure sine wave, which matters for computer power supplies with active power factor correction (PFC); cheaper ones produce a simulated sine wave.

Online (double-conversion) units feed the load from the inverter all the time, so there is no transfer time at all. They cost more and are usually overkill for a home network.

For a home server plus network gear, a line-interactive unit is the usual middle ground. If the server has a PC power supply with active PFC, pick a model with pure sine wave output.

One more requirement is easy to miss: the UPS needs a data connection, usually a USB port that presents itself as a HID power device. Without it, the computer has no idea that the power has failed. Check the NUT hardware compatibility list for the exact model before you buy.

Batteries wear out

Most small UPS units use sealed lead-acid (VRLA) batteries. Eaton gives a typical life of three to five years, and APC says the same for most of its batteries. Heat is the main enemy. APC puts the optimal temperature at 20 to 25 °C and says that every 8 °C increase halves battery life, so a battery that would last four years at 25 °C lasts about two at 33 °C. Do not hide the UPS in a closed cupboard next to a warm server.

APC also advises running a runtime calibration, which drains the battery, only once or twice a year. Eaton adds that frequent transfers to battery shorten its life too, which is one more reason to prefer a unit with voltage regulation if your mains voltage drifts.

NUT can warn you when the UPS itself reports that the battery needs replacing (the REPLBATT event, described below).

How NUT is put together

NUT has three layers:

  • a driver talks to the UPS (configured in ups.conf);
  • the data server upsd publishes the driver's data on TCP port 3493 (configured in upsd.conf and upsd.users);
  • the monitor upsmon watches the data and shuts the computer down when needed (configured in upsmon.conf).

The computer connected to the UPS by USB runs all three and is the primary. Other computers on the same UPS run only upsmon, connect to the primary over the network and are secondaries. NUT 2.8.0 renamed master and slave to primary and secondary; the old names are still accepted, so you will see both in older guides.

On Debian and Raspberry Pi OS the configuration lives in /etc/nut. The versions differ between releases: Debian 12 bookworm ships NUT 2.8.0, Debian 13 trixie ships 2.8.1. The nut package pulls in both the server and the client.

sudo apt install nut

Step 1: find the UPS and configure the driver

Connect the USB cable and let NUT look for supported devices:

sudo nut-scanner -U

It prints a ready-made section for ups.conf. A typical USB setup looks like this:

[homeups]
        driver = usbhid-ups
        port = auto
        desc = "Network and server UPS"

USB drivers such as usbhid-ups ignore the port value, but the field must be present, so auto is the convention. The name in square brackets (homeups here) is how every other tool refers to the UPS.

Step 2: choose the mode and secure the server

In /etc/nut/nut.conf set the mode. Note that there must be no spaces around the equals sign:

MODE=standalone

Use standalone if only this computer is on the UPS. Use netserver if other machines (a NAS, a second Pi, Home Assistant on another host) need to read the UPS state. The default is none, which starts nothing.

By default upsd listens only on localhost, port 3493. For netserver, add the LAN address of this machine to /etc/nut/upsd.conf:

LISTEN 127.0.0.1 3493
LISTEN 192.168.1.10 3493

Then create a user for the monitor in /etc/nut/upsd.users:

[monuser]
        password = choose-a-long-password
        upsmon primary

Both files contain secrets, and the NUT documentation recommends owner root, group nut and mode 0640:

sudo chown root:nut /etc/nut/upsd.conf /etc/nut/upsd.users
sudo chmod 0640 /etc/nut/upsd.conf /etc/nut/upsd.users

Step 3: configure the monitor

The essential lines in /etc/nut/upsmon.conf on the primary are:

MONITOR homeups@localhost 1 monuser choose-a-long-password primary
SHUTDOWNCMD "/sbin/shutdown -h +0"
POWERDOWNFLAG /run/nut/killpower

The 1 is the number of power supplies this UPS feeds in this computer. POWERDOWNFLAG has to be set explicitly, and the documentation suggests a location on a temporary file system such as /run/nut/killpower, so a stale flag cannot survive into the next boot. This file holds a password too, so give it the same root:nut and 0640 treatment.

On a secondary, the MONITOR line points at the primary and ends with secondary. Create a separate user with upsmon secondary in upsd.users on the primary for it.

Step 4: start the services and check the data

On systemd distributions, NUT runs as nut-driver instances (one per UPS section in ups.conf, created by a helper service since NUT 2.8.0), nut-server and nut-monitor. After editing the files, restart the server and the monitor:

sudo systemctl restart nut-server nut-monitor

Then ask the server what it sees:

upsc homeups@localhost ups.status

OL means the UPS is on line power, often together with CHRG while the battery charges. Pull the UPS plug from the wall for a moment and the status should change to OB (on battery). upsc homeups@localhost without a variable name lists everything the driver knows, including battery.charge, battery.runtime (in seconds) and ups.load.

What happens during an outage

The sequence NUT follows is worth knowing, because it explains the settings:

  1. The UPS switches to battery and reports OB. Nothing shuts down yet.
  2. When the battery runs low, the UPS reports OB LB. This is the trigger.
  3. The primary's upsmon sets the forced shutdown flag (FSD) on the server.
  4. Secondaries see FSD, wait FINALDELAY (5 seconds by default) and run their own SHUTDOWNCMD.
  5. The primary waits until the secondaries have disconnected, or until HOSTSYNC (15 seconds by default) runs out, then creates the POWERDOWNFLAG file and shuts itself down.
  6. Late in the shutdown, the system finds the flag and tells the UPS to cut power to its outlets.
  7. When mains power returns, the UPS turns the outlets back on and the machines boot.

Step 6 matters more than it looks. If the UPS stayed on, a computer configured to power on when mains returns would never see that event, because from its point of view the power never went away. The NUT documentation calls the related failure modes power races. If you installed NUT from distribution packages, the shutdown script that checks the flag is already in place.

Also note that the low battery signal normally comes from the UPS itself. When the driver exposes it, NUT shows the threshold as battery.charge.low.

Notifications

upsmon can tell you about events without any extra software. NOTIFYFLAG lines choose what happens for each event type (SYSLOG, WALL, EXEC), and NOTIFYCMD points at a script that EXEC runs. The event names include ONBATT, ONLINE, LOWBATT, FSD, COMMBAD, NOCOMM and REPLBATT. For example:

NOTIFYCMD /usr/local/bin/ups-notify.sh
NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
NOTIFYFLAG REPLBATT SYSLOG+EXEC

COMMBAD and NOCOMM deserve attention: they mean upsmon has lost contact with the UPS. According to the upsmon.conf manual, a UPS that stops answering while it was last on battery is treated as being on low battery, which starts a shutdown.

If you run Home Assistant, its NUT integration connects to the same server on port 3493 and turns the UPS variables into sensors, so outages can drive automations and notifications there. For that, the NUT server needs netserver mode and a LISTEN line reachable from the Home Assistant host.

Test the shutdown before you need it

The NUT documentation is clear that UPS hardware varies even within one model line, so test the shutdown before leaving the system unattended. Start with a dry run, which only prints what the driver would do:

sudo upsdrvctl -t shutdown

Then, at a time when a reboot does no harm, run the real sequence:

sudo upsmon -c fsd

This performs a full forced shutdown: the computer goes down, the UPS cuts power to its outlets for a while and then restores it, and the machine should start again on its own. If the UPS never switches the outlets back on, you are exposed to a power race and need to fix that before relying on the setup. Keep in mind that upsd holds the FSD state until it is restarted, which the reboot takes care of.

A successful result, in the documentation's words, is one where the operating system halts before the battery runs out and the system restarts when power returns. A Raspberry Pi starts as soon as it gets power. A PC or NAS may stay off after a power loss unless its firmware is set to power on when mains returns, so check that setting too.