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

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.