Unraid UPS Setup: Built-in apcupsd, the NUT Plugin and Shutdown Timing

Two routes on Unraid

Unraid gives you a built-in UPS option and a popular add-on. Both work; they suit different hardware and goals.

If you have an APC unit and only Unraid on it, the built-in option is simplest. If you have a CyberPower, Eaton or Tripp Lite unit that shows incomplete data, or a homelab with several machines on one UPS, the NUT plugin is the better fit.

Configuring the built-in UPS settings

In recent Unraid releases the page is at Settings > UPS Settings (under System Settings on some versions). The fields map directly onto apcupsd's configuration file; the apcupsd guide explains each directive in depth.

1. Connect the USB data cable from the UPS to the server.
2. Set UPS cable to USB and UPS type to USB. Leave Device blank for USB; apcupsd finds the device itself.
3. Set Start APC UPS daemon to Yes and apply.
4. Check the status panel on the same page. You should see a model, status ONLINE, battery charge, load and runtime left. Missing fields hint at partial support.
5. Set the three shutdown thresholds (explained below) and apply again.
6. Decide on Turn off UPS after shutdown, and test before enabling it.

The config you produce is equivalent to an apcupsd.conf along these lines:

UPSCABLE usb
UPSTYPE usb
DEVICE
BATTERYLEVEL 50
MINUTES 10
TIMEOUT 300

The three thresholds

• Battery level to initiate shutdown (%): shutdown starts when the reported charge drops to this value (apcupsd's BATTERYLEVEL).
• Runtime left to initiate shutdown (minutes): shutdown starts when the UPS's runtime estimate drops to this value (MINUTES).
• Time on battery before shutdown (seconds): shutdown starts after this long on battery regardless of charge (TIMEOUT; 0 disables it).

Whichever condition is met first wins. Using all three gives you belt and braces: a timer for predictability and two estimate-based backstops for the day the battery is weaker than you think.

Budget the shutdown time, then set the thresholds

Unraid's shutdown has more steps than a desktop's. Docker containers are stopped, VMs are asked to shut down (and given a timeout before being forced off), then the array is stopped and the disks are unmounted. Each step has its own timeout in Unraid's settings, and if the overall shutdown runs past its limit, Unraid forces it, which is exactly the unclean stop you are trying to avoid.

Here is a worked example with illustrative numbers. Measure your own system; these are only for showing the arithmetic.

Suppose the UPS shows 22 minutes of runtime at this server's load when the battery is new. Applying our rule of at least twice the shutdown time as margin, shutdown must begin with at least 320 seconds (about 5.5 minutes) of runtime left. A sensible configuration:

• Time on battery: 300 seconds. Short outages under 5 minutes are ridden through; longer ones trigger shutdown with roughly 17 minutes of runtime still estimated.
• Runtime left: 10 minutes, a backstop in case the battery has aged or the load is heavier than usual.
• Battery level: 50%, a second backstop.

Using the NUT plugin

Install the NUT plugin from Community Applications, then stop and disable the built-in apcupsd daemon first, since only one program can own the USB device. In the plugin's settings page:

1. Set the mode to standalone (UPS on this server, no sharing), netserver (UPS on this server, shared) or netclient (UPS on another NUT server).
2. For a local UPS, choose the usbhid-ups driver and port auto, or use the plugin's detection button if present.
3. Set shutdown triggers similar to the built-in page: on battery for a time, battery percentage or runtime.
4. In netserver mode, define a user for clients. Clients then use a MONITOR line such as MONITOR ups@192.168.1.40 1 upsclient yourpassword secondary (or slave on NUT versions older than 2.8).

Run upsc ups@localhost from the Unraid terminal (replacing ups with the name you configured) to confirm the driver is reading live values. The NUT guide covers the underlying files and roles.

Turn off UPS after shutdown: when to enable it

The Turn off UPS after shutdown option tells the UPS to switch its outlets off once Unraid has halted. The UPS then switches them back on when mains power returns. Combined with a BIOS setting that powers the server on after AC loss, this gives unattended recovery from long outages.

Without it, a common failure looks like this: Unraid shuts down cleanly, the UPS keeps its outlets powered, mains returns 20 minutes later before the battery is empty, and the server sits there switched off because it never saw power disappear. That is safe, but it is not what most people want from a home server.

The risk is timing. If the UPS turns off before Unraid has finished, you get the very unclean stop you were avoiding. Most UPS units wait a fixed or configurable delay after the turn-off command, and apcupsd sends it at the very end of the shutdown sequence, but verify on your hardware: enable it, run a pull-the-plug test, and watch that the server reaches power-off before the outlets click off.

Troubleshooting

Finally, test it: with a charged battery and a quiet moment, unplug the UPS from the wall, watch the Unraid log, and confirm the array stops cleanly and no parity check starts on the next boot. If the server also hosts storage for hypervisors, see Proxmox UPS shutdown for multi-machine ordering.