Configuration of apcupsd in Linux

Introduction to apcupsd¶

Apcupsd is a software daemon available in most Linux distributions. It communicates with the APC UPS and pulls all available information about the utility power and the battery operation. Based on the data gathered from the UPS apcupsd can invoke different actions on the server it is running on.

The most important feature of apcupsd in the HomeLab environment is that it provides the networking functionality allowing for the data from a single UPS to be available on the other hosts running apcupsd. That way as long as the machine that monitors the UPS by a direct USB connection is running, all machines connected to the same UPS can react to the power events according to their individual configurations.

Events¶

The idea behind the software is very simple. After installation the /etc/apcupsd directory is created with various scripts and a single configuration file. These scripts are executed based on events pulled from the UPS. The most important ones are:

• commfailure - communication with the UPS failed
• commok - communication with the UPS restored
• onbattery - running on battery
• offbattery - no longer running from battery
• doshutdown - shutdown invoked

Each of the scripts is run every time the corresponding event is triggered. First four have the standard content that sends an e-mail to the administrator and provides the wall notification for the users. It is worth considering if it's necessary on all hosts connected to the same UPS as when the power goes out each host will send its own notification to the administrator.

The last script doshutdown is not included in the default installation. Upon creation it will be executed just before the shutdown procedure begins. It can be used on the last machine going down to execute shutdown procedures on the devices that do not have apcupsd installed. I am also using it to notify me that the particular machine is going down. I have copied email code from another script with some modifications and put it on every machine running apcupsd. That way during the power outage I can see in real time which machines are shutting down and how much of the battery run-time is left.

#!/bin/bash

HOSTNAME=`hostname`
MSG="$HOSTNAME UPS $1 Going Down !!!"

(
   echo "$MSG"
   echo " "
   /sbin/apcaccess status
) | $APCUPSD_MAIL -s "$MSG" $SYSADMIN

exit 0

Configuration¶

The configuration file is well documented so I won't go into too much detail about the different options available. The most important parameters are:

• UPSCABLE - USB for directly connected machine or ether for slave machines connected over the network
• UPSTYPE - modbus for USB connected device or net for remote machines
• DEVICE - hostname:port of the machine that has direct USB connection to the UPS.
• ONBATTERYDELAY - delay in seconds for apcupsd to wait until onbattery script is run
• BATTERYLEVEL - percentage of battery charge at which shutdown is initiated
• MINUTES - remaining run-time when shutdown is initiated (in minutes)

Once all servers are connected to the UPS and apcupsd is installed on every machine it is possible using the above options to turn them off in the correct order while the battery is discharging. By utilizing MINUTES parameter the remaining time will depend on the current electrical load and the remaining battery level. Once some of the servers shut down the battery time will increase due to lower wattage draw so the most critical systems can stay powered for longer.

When the power is restored it would be nice to have everything back to normal operating conditions. But once the machines are powered down how can we start them again? I will describe that in the next article.

Monitoring¶

The connected UPS can provide useful information about the load and electricity supply. There is a command called apcaccess that prints all the information from the UPS as well as some configuration parameters in a machine readable format.

PARAMETER   : VALUE

The output of apcaccess is included in every email sent to the administrator providing valuable insight into the UPS status and as the output is easily parsable using regular expressions it can be used to include UPS information in the monitoring solution of your choice.

In the next article I will describe how to ensure all of the systems start in the correct order after the power outage.

Share on: Twitter ❄ Reddit ❄ e-mail