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
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
You can disable any unwanted scripts without removing them by
exit 0 at the top of the file.
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
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:
USBfor directly connected machine or
etherfor slave machines connected over the network
modbusfor USB connected device or
netfor remote machines
hostname:portof the machine that has direct USB connection to the UPS.
ONBATTERYDELAY- delay in seconds for apcupsd to wait until
onbatteryscript is run
BATTERYLEVEL- percentage of battery charge at which shutdown is initiated
MINUTES- remaining run-time when shutdown is initiated (in minutes)
If both the remaining battery level (
BATTERYLEVEL) and the remaining time
MINUTES) are set the first matching parameter will initiate the
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.
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
On most Linux distributions the
apcaccess is installed in
/usr/sbin/ which by default is only added to the
PATH of the root
user. But the program itself doesn't require any special privileges
and can be run by providing the full path
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.
This article is a part of the series "UPS Backup"