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 behavior
for all possible situations apcupsd is likely to detect from
the UPS. Nevertheless you can change the apccontrol behavior
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 communications 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 exhausted. Doing
shutdown.\n" | wall then exits.
- loadlimit
- Does a printf "UPS battery discharge limit
reached. Doing shutdown.\n" | wall then exits.
After completing 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 completing this event, apcupsd will immediately
initiate a doshutdown event.
- timeout
- Does a printf "UPS battery runtime limit
exceeded. Doing shutdown.\n" | wall then exits.
After completing 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.