Author: Kern Sibbald

# Apcupsd EVENTS

When apcupsd detects anomalies from your UPS device, it will make some decisions that usually result in one or more calls to the script located in /etc/apcupsd/apccontrol. The apccontrol file is a shell script that acts on the first argument that apcupsd passes to it. These actions are set up by default to sane behaviour for all possible situations apcupsd is likely to detect from the UPS. Nevertheless you can change the apccontrol behaviour for every single action. To do so create a file with the same name as the action, which is passed as a command line argument. Put your script in the /etc/apcupsd directory.

These events are sent to the system log, optionally sent to the temporary events file (/etc/apcupsd/apcupsd.events), and they also generate a call to /etc/apcupsd/apccontrol which in turn will call any scripts you have placed in the /etc/apcupsd directory.

Normally, /etc/apcupsd/acpcontrol is called only by apcupsd. Consequently, you should not invoke it directly. However, it is important to understand how it functions, and in some cases, you may want to change the messages that it prints using wall. We recommend that you do so by writing your own script to be invoked by apccontrol rather than by modifying apccontrol directly. This makes it easier for you to upgrade to the next version of apcupsd

In other case, you may want to write your own shell scripts that will be invoked by apccontrol. For example, when a power fail occurs, you may want to send an email message to root. At present the arguments that apccontrol recognizes are:

## How apcupsd calls apccontrol

When apcupsd detects an event, it calls the apccontrol script with four arguments as:

apccontrol <event> <ups-name> <connected> <powered>

where:

event
  is the event that occurred and it may be any one of the values described in the next section.
ups-name
  is the name of the UPS as specified in the configuration file (not the name in the EEPROM). For version 3.8.2, this is always set to Default
connected
  is 1 if apcupsd is connected to the UPS via a serial port (or a USB port). In most configurations, this will be the case. In the case of a Slave machine where apcupsd is not directly connected to the UPS, this value will be 0.
powered
is 1 if apcupsd is powered by the UPS and 0 if not. In version 3.8.2, this value is always 1.

## apccontrol Command Line Options

apccontrol accepts the following command line options:

annoyme
  Does a printf "Power problems please logoff." | wall then exits.
changeme
  Does a printf "Emergency! UPS batteries have failed\nChange them NOW" | wall then exits.
commfailure
  Does a printf "Warning serial port communications with UPS lost." | wall then exits.
commok
  Does a printf "Serial communciations with UPS restored." | wall then exits.
doreboot
  Does a reboot of the system by calling shutdown -r now
doshutdown
  Does a shutdown of the system by calling shutdown -h now
emergency
  Does an emergency shutdown of the system by calling shutdown -h now
failing
  Does a printf "UPS battery power exhaused. Doing shutdown.\n" | wall then exits.
loadlimit
  Does a printf "UPS battery discharge limit reached. Doing shutdown.\n" | wall then exits. After completeting this event, apcupsd will immediately initiate a doshutdown event.
mainsback
  Attempts to cancel the shutdown with a shutdown -c
onbattery
  Does a printf "Power failure. Running on UPS batteries." | wall then exits.
powerout
  Does a printf "Warning power loss detected." | wall then exits.
remotedown
  Does a shutdown -h now
restartme
  Terminates the currently running apcupsd and then restarts it.
runlimit
  Does a printf "UPS battery runtime percent reached. Doing shutdown.\n" | wall then exits. After completeting this event, apcupsd will immediately initiate a doshutdown event.
timeout
  Does a printf "UPS battery runtime limit exceded. Doing shutdown.\n" | wall then exits. After completeting this event, apcupsd will immediately initiate a doshutdown event.
startselftest
  This is called when apcupsd detects that the UPS is doing a self test. No action is taken.
endselftest
  This is called when apcupsd determines that a self test has been completed. No action is taken.

To write your own routine for the powerout action, you create shell script named powerout and put it in the lib directory (normally /etc/apcupsd). When the powerout action is invoked by apcupsd, apccontrol will first give control to your script. If you want apccontrol to continue with the default action, simply exit your script with an exit status of zero. If you do not want apccontrol to continue with the default action, your script should exit with the special exit code of 99. However, in this case, please be aware that you must ensure proper shutdown of your machine if necessary.

Some sample scripts (onbattery and mainsback) that email power failure messages can be found in the examples directory of the source code.