APCCONTROL(8) | System Manager's Manual | APCCONTROL(8) |
apccontrol
—
apcupsd(8) event handler script
apccontrol |
{ <event> <ups-name> <connected> <powered> } |
When apcupsd(8) detects anomalies from the UPS
being monitored, it triggers an event which usually results in one or more
calls to the apccontrol
shell script. Each event
causes apccontrol
to take a particular action. These
actions default to sane behaviour for all the events that apcupsd is likely
to encounter. However, you can change the behaviour of every single
action.
When apcupsd detects an event, it calls the
apccontrol
script with the following four
arguments:
Events are sent to the system log and, optionally, to the
temporary events file (/etc/apcupsd/apcupsd.events),
and they also generate a call to apccontrol
which in
turn will call any scripts you have placed in the
/etc/apcupsd directory.
Default action -- sends "Power problems please logoff." to wall(1) and then exits.
Default action: does nothing.
Default action: does nothing.
Default action -- sends "Emergency! UPS batteries have failed Change them NOW" to wall and then exits.
Default action -- sends "Communications with UPS lost." to wall and then exits.
Default action -- sends "Communications with UPS restored." to wall and then exits.
Default action -- sends "Beginning Reboot Sequence" to wall and then calls shutdown(8) with the "-r now" command line arguments to reboot the computer.
Default action -- sends "Beginning Shutdown Sequence" to wall and then calls shutdown(8) with the command line arguments "-h now" to shutdown the computer.
Default action -- sends "Emergency Shutdown. Possible UPS battery failure." to wall. Immediately after this, apcupsd generates a doshutdown event to shutdown the system.
Default action -- sends "UPS battery power exhausted. Doing shutdown." to wall and then exits.
Default action -- sends "UPS now committed to shut down" to wall, waits for 10 seconds and then issues the command "apcupsd --killpower" to put the UPS into hibernate mode and shut off power to the connected equipment. In the case of a smart UPS, the UPS will then wait for the expiry of any configured shutdown time delay specified by the SLEEP configuration directive. In hibernate mode, the UPS will restore utility power to the connected equipment subject to the values specified for the RETURNCHARGE and WAKEUP configuration directives.
Default action -- sends "UPS battery discharge limit reached. Doing shutdown" to wall and then exits. After this event, apcupsd will immediately generate a doshutdown event.
Default action -- if the file /var/run/powerfail exists, sends "Continuing with shutdown." to wall and then exits. Otherwise, does nothing.
Default action -- sends "Power failure. Running on UPS batteries." to wall and then exits.
Default -- sends ""Power has returned..." to wall and then exits.
Default action -- does nothing.
Default action: sends "Remote Shutdown. Beginning Shutdown Sequence." to wall and exits. Immediately after this, apcupsd generates a doshutdown event to shutdown the system.
Default action -- sends "UPS battery runtime percent reached. Doing shutdown." to wall and then exits. After this event, apcupsd will immediately generate a doshutdown event.
Default action -- send "UPS battery runtime limit exceeded. Doing shutdown." to wall and then exits. After this event, apcupsd will immediately generate a doshutdown event.
Default action: does nothing.
Default action: does nothing.
Do not modify apccontrol
directly as it will be overwritten the next time you upgrade to a new
release of apcupsd.
The recommended way to customise an event action is simply to
create an executable program or script file with the same name as the event
and put that file in the /etc/apcupsd directory.
Now, when the selected event occurs, apccontrol
will
execute your program or script.
If you want apccontrol
to also execute its
default action for the selected event, your program or script should exit
with an exit status of 0 (zero).
If you do not want
apccontrol
to also execute its default action for
the selected event, your program or script must exit with an exit status of
99. Be aware that if you completely override the default action, you must
ensure the proper shutdown of your computer if this is necessary.
Some sample scripts (changeme, commfailure, commok, offbattery and onbattery) that email messages to root instead of broadcasting messages to all logged-in users may be found in /etc/apcupsd after an installation and also in the platforms/etc directory of the apcupsd source code.
/etc/apcupsd/apccontrol
wall(1), apcupsd.conf(5), apcupsd(8), shutdown(8).
The HTML apcupsd manual installed on your system or available online at http://www.apcupsd.org/
Trevor Roydhouse
Adam Kropelin (current Project Manager and Code
Maintainer)
Kern Sibbald (former Project Manager and Code
Maintainer)
Riccardo Facchetti (former Project Manager and Code
Maintainer)
Andre M. Hedrick (Project Founder and former Code
Maintainer)
An enormous number of users who have devoted their time and energy to this project -- thanks.
January 10, 2009 | apccontrol v3.14.6 |