How-to: Automatically shutdown Linux using UPS on power failure

Whether you run Home Assistant/PiHole/PiVPN on an RPi4 like in my DIY Smart Home, or run any critical software on any Linux-based system or your homelab, you need to plan for that one scenario none of us like to think about. What if the power fails, especially when you are not around to perform disaster recovery?

A quick note: As an Amazon Associate I earn from qualifying purchases. This post contains affiliate link(s). An affiliate link means I may earn advertising or referral fees if you make a purchase through my link, at no extra cost to you.

Why you need a UPS

Even if you live in a city where power failures are unheard of, I highly recommend getting a UPS for your networking gear and any systems that are running 24/7.

Here are a few reasons why:

1. Data corruption – This is usually the most overlooked reason to get a UPS. A power failure can cause what Linux calls an “unclean shutdown” or in other words a sudden power loss that can cause data loss or database corruption quite easily. You may have backups, but you still will need to restore the backups and check if everything is up-to-date manually.
2. Downtime – While you are fixing the corrupted database and restoring the backup, your systems are down, your smart home automation is down, your CCTV system may be down, you get the picture.
3. Hardware damage – Power surges can quite literally fry your hardware. UPS’ can protect you because they are basically surge protectors with battery backup.
4. Automatic graceful shutdown – A UPS can gracefully shut down your PC.
5. Automatic reboot / startup – When power returns, your PC can boot right up and resume duties immediately, without you having to do anything!

What you need

1. A Linux based PC, running a distribution such as Debian, Ubuntu, Red Hat Enterprise, Fedora, CentOS or openSUSE. I use an Intel NUC.
2. UPS software – Cyberpower provides the Powerpanel Linux software for free.
3. A Cyberpower UPS that supports USB port communications. Here are some recommendations based on my experience:

(* = affiliate link / image source: Amazon Associates Program)

Steps

The Powerpanel user manual suggests changing each setting 1 by 1 through the CLI, I dont recommend this because its far easier to just edit the config file as I explain below.

1. Plug in power cables and USB cable from the UPS to the PC.
2. Download and install Powerpanel from here
   1. Through the Ubuntu desktop GUI (downloaded and opened the .deb file) – the software sets itself up as a service with a default config file, so thats it really, the auto graceful shutdown is now ready.
   2. Through the CLI.
3. Read and understand the default Powerpanel config file, its very helpful and has notes for each setting. You can access this config file using this command: sudo nano /etc/pwrstatd.conf
   • The settings are also documented in the Powerpanel user manual.
4. Default behaviour in this config file is: when the UPS detects power loss, it waits for 1 minute (setting is powerfail-delay) and then sends the shutdown command to the PC.
5. On receiving this shutdown command from the UPS, Ubuntu asks the running services to close gracefully. The UPS will wait for 10 minutes by default for the shutdown to complete (setting is shutdown-sustain).
   • OPTIONAL: I have already set each of my systemd services to wait for a maximum of 9 minutes before force closing to avoid any potential DB corruptions.
6. Reload the service file and the pwrstatd service OR simply reboot your PC for all of the above to take effect.
7. Set your PC power option to Always ON in the BIOS. Note that not all motherboards have this option – the Intel NUC does and you can find the setting in the NUC BIOS manual.
8. Check the UPS status and configuration status by using this command: pwrstat -status

If you are interested in email notifications, the Powerpanel user manual has instructions on setting it up.

Testing and results

So the only deviation I made from the default config is setting the UPS power off delay to 11 minutes instead of 10.

These are the results of my testing:

1. My NUC with Ubuntu 20.04 LTS is running as normal, and I turn off the power at the wall.
2. The UPS kicks in, the Cyberpanel software gets a powerfail signal from the UPS through USB, it waits for 60 seconds (default powerfail-delay setting) then sends a graceful shutdown command to the PC.
3. Ubuntu PC shuts down fully in <60 seconds. Rarely it takes up to 5 minutes but that’s OK.
4. Because the UPS will wait and keep running for another 10 minutes (default shutdown-sustain setting) OR until battery remaining is 35% (default low battery threshold), and only then will it switch itself off fully. In my case the UPS runtime is 60+ mins fully charged, so after 10 minutes it is down to only around 90% (self-reported by UPS).
5. I pretend the power failed for different durations (say 2 minutes, 15 minutes, 1 hour), then turn the power on at the wall. Note that if the power returns after the set 1 min (PC shutdown point) but before the 10 min UPS power off delay period is up, the UPS will still cut the power to the PC after the 10 mins are up. But then it will immediately turn the power back on to the PC so that it can boot right up. Otherwise the PC that is already shut down will never have its power cut off and restored and then boot up automatically – it would just stay shut down.
6. UPS turns on and instantaneously Ubuntu PC powers on and all services resume.

As a failsafe if for any reason the PC fails to turn on when power returns to make sure the PC turns on after a power failure event, I have also set the PC’s BIOS to start the PC everyday in the morning at a particular time (there is an RTC setting in the NUC BIOS).

Let me know if you have any doubts or questions using the comments section below!