Apcupsd

Using apcupsd to Monitor a USB-Attached APC UPS

This wiki page shows how to install and configure the apcupsd package to monitor and report the statistics for an APC branded USB attached Uninterruptible Power Supply (UPS). The UPS model used in the examples is an APC SmartUPS 1000, but any APC or compatible model should work.

The end goal is to make the UPS status available over the network so it can be monitored and used to trigger actions in a home automation system like Home Assistant.

Installing and Configuring apcupsd

The first step is to add the alpine package for apcupsd. After that, we'll rename the default configuration file and replace them with the parameters needed for our example USB attached APC Smart-UPS.

Installation is by an APK package.

 alpine:/# apk update && apk add apcupsd

There is one main configuration file called /etc/apcupsd/apcupsd.conf that has all the tunable parameters along with many comments. We'll keep the original as a reference and then edit the parameters to suit.

 alpine:/# mv /etc/apcupsd/apcupsd.conf /etc/apcupsd/apcupsd.conf~
 alpine:/# grep -v '^\s*$\|^\s*\#' /etc/apcupsd/apcupsd.conf~ >/etc/apcupsd/apcupsd.conf

Now, edit the parameters in /etc/apcupsd/apcupsd.conf using the backup copy of the original file as a reference for comments. Some of the important parameters are listed below in order of appearance.

UPSNAME - This is to identify your UPS. Exact format is not important, but keep it short and don't use spaces.
UPSCABLE - For a USB attached UPS, use the value usb
USBTYPE - Similar to USBCABLE, use usb
DEVICE - For a USB attached UPS, the parameter is not needed. Comment this line by using a # at the beginning.

These four changes are enough to get started. Everything else can be left as default. Read the comments in the original apcupsd.conf~ file to find out what the other parameters do and if you want to use them.

Note: The comments in the config file say UPSNAME should be eight characters or less. This appears to be a limitation of using the parameter for storing the name in the UPS's EPROM. If you're not planning to update EPROM, longer names do not appear to cause problems. See the config section after Configuration statements used in updating the UPS EPROM for more detail.

Starting apcupsd

The apcupsd package installs a service that allows you to control apcupsd using the standard tools. The following example shows how to start it and ensure it starts each time the system boots.

 alpine:/# rc-service apcupsd start
 * Starting APC UPS daemon ...

 alpine:/# rc-update add apcupsd
 * service apcupsd added to runlevel default

Checking the Configuration

The apcaccess command will communicate with the UPS via the apcupsd daemon's network port and report back what it finds. This is a good way to test your connection and configuration.

A successful test will look similar to what's shown below.

 alpine:/# apcaccess
 APC      : 001,043,1022
 DATE     : 2024-10-12 15:31:10 +0000
 HOSTNAME : alpine.home
 VERSION  : 3.14.14 (31 May 2016) unknown
 UPSNAME  : SmartUPS_1000
 CABLE    : USB Cable
 DRIVER   : USB UPS Driver
 UPSMODE  : Stand Alone
...

The actual list of reported parameters is much longer, but the first few lines show the ones that have been customized in the configuration thus far. If you see the message Error contacting apcupsd @ localhost:3551: Connection refused, check to ensure the apcupsd service is running.

Configuring and Testing Email Alerts

Note: In order to receive notifications, you must have mail delivery setup and working on your Alpine host. In addition, you should have an alias that sends email intended for root to a regular user. See the Alpine HOWTO Small-Time_Email_with_Exim_and_Dovecot for help with that.

apcupsd will send alerts for important events using shell scripts in the /etc/apcupsd directory. These scripts and their alert functions are listed below.

changeme - sends an alert when batteries have reached the end of their useful life
commfailure - apcupsd cannot communicate with the UPS
commok - communication with the UPS has been restored after a failure
offbattery - the UPS is back to running on mains power after running on battery
onbattery - the ups has switched to battery power

All of the scripts have a similar setup and rely on two environment variables, SYSADMIN and APCUPSD_MAIL, to deliver email alerts. To test the alerts, temporarily export these two variables and run one of the scripts from the command-line. The example below shows how to send a test alert for battery change.

alpine:/# export SYSADMIN=root
alpine:/# export APCUPSD_MAIL=mail
alpine:/# sh /etc/apcupsd/changeme</nowiki>

If all goes well, you should receive an email telling you the UPS battery needs changing NOW. If you find you need to use different values for SYSADMIN or APCUPSD_MAIL, be sure to make those changes in /etc/apcupsd/apccontrol. The exported variables used in the test are temporary and will lost after you log out.

Next Steps

Further configuration can be done to initiate automatic shutdown using the parameters in apcupsd.conf (see the original commented file apcupsd.conf~ for details.) You may also monitor the UPS via home automation using Home Assistant and the APC UPS Daemon integration.