apcupsd: Configuring APC UPS Monitoring and Shutdown

Where apcupsd fits

apcupsd has been around since the late 1990s and is still packaged by most Linux distributions and BSDs. It is also the engine behind Unraid's built-in UPS settings (see Unraid UPS setup). Its appeal is simplicity: one daemon, one config file, one status command, and sensible defaults for APC hardware.

Its limits are equally clear. Development has been quiet for years, it is designed around APC's protocols, and its network model is less flexible than Network UPS Tools. If you have an APC unit and one or two Linux machines, it is a fine choice. For anything bigger or mixed, read the comparison at the end first.

A working USB configuration

Install the package (named apcupsd on major distributions), then edit /etc/apcupsd/apcupsd.conf. These are the lines that matter for a typical USB-connected APC unit; leave the rest at defaults.

## /etc/apcupsd/apcupsd.conf
UPSNAME office-ups
UPSCABLE usb
UPSTYPE usb
DEVICE
POLLTIME 60

## Shutdown thresholds: whichever is reached first wins
BATTERYLEVEL 5
MINUTES 3
TIMEOUT 0

## Events
ONBATTERYDELAY 6
ANNOY 300
ANNOYDELAY 60

## Network information server (for apcaccess and remote clients)
NETSERVER on
NISIP 127.0.0.1
NISPORT 3551

What each setting does

Defaults for NISIP differ between the upstream sample file and some distribution packages. Set it explicitly so you know what it is.

Start it and read the status

sudo systemctl enable --now apcupsd
apcaccess status

On older Debian and Ubuntu packages you also had to set ISCONFIGURED=yes in /etc/default/apcupsd before the service would start. If apcaccess returns quickly with a page of fields, the daemon is talking to the UPS. The fields you will look at most:

Not every model reports every field, and USB Back-UPS units usually report fewer than Smart-UPS units.

Sharing one UPS with other machines

The host with the USB cable runs apcupsd as above with the information server reachable on the LAN:

## On the server (USB-connected host)
NETSERVER on
NISIP 192.168.1.10
NISPORT 3551

Each other machine runs apcupsd in client mode, polling the server instead of a cable:

## On each client
UPSCABLE ether
UPSTYPE net
DEVICE 192.168.1.10:3551
POLLTIME 10
BATTERYLEVEL 20
MINUTES 8
TIMEOUT 0

The client applies its own thresholds to the data it reads. Set them higher than the server's so clients finish shutting down while the server is still up. The older apcupsd docs called these clients "slaves"; the mechanism is the same.

Event scripts with apccontrol

When something happens, apcupsd calls /etc/apcupsd/apccontrol with the event name. The default script logs a message, notifies logged-in users and, for shutdown events, calls the system shutdown. To customize an event, create an executable script in /etc/apcupsd/ with the event's name. apccontrol runs it first; if your script exits with code 99, apccontrol skips its own default action for that event.

A minimal /etc/apcupsd/onbattery script:

#!/bin/sh
# $1 is the UPS name passed by apccontrol
echo "UPS $1 on battery at $(date)" | mail -s "Power failure" admin@example.com
exit 0

Exiting 0 lets the default actions still run. Many distributions already ship small onbattery and offbattery scripts that send mail to root, so check before overwriting.

apctest: diagnostics and settings

apctest is an interactive tool that talks to the UPS directly. Stop apcupsd before running it, because both cannot hold the device. Depending on the UPS model and connection type, it can run a battery calibration, test killpower, and on some models read or change EEPROM settings such as transfer voltages and alarm behavior. Menus vary with the connection: USB units typically expose fewer options than serial Smart-UPS units. Start apcupsd again when finished.

Killpower and automatic restart

After a threshold-triggered shutdown, the system's halt scripts call apcupsd's killpower routine, which tells the UPS to turn its outputs off after a delay. When utility power returns, the UPS restarts output and machines set to power on after AC loss boot. Whether this works depends on the distribution's shutdown integration and the UPS model, so verify it once with a real test at a planned time.

Working with non-APC hardware

apcupsd's USB driver uses HID Power Device reports, which many brands share. Some non-APC units therefore show basic data. Results are inconsistent, though: values may be missing or misread, and shutdown commands may not work. Treat non-APC support as partial at best, and prefer NUT for those units.

apcupsd vs NUT