Apcupsd

Warning: Work in Progress

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. 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:/# cp /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.

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

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.