Ubuntu Manpage: apccontrol — apcupsd(8) event handler script

Provided by: apcupsd_3.14.14-3.1build2_amd64

NAME

       apccontrol — apcupsd(8) event handler script

SYNOPSIS

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

DESCRIPTION

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:

event This is the event that occurred. Refer to the list of possible events below.

ups-name This is the name of the UPS as specified in the /etc/apcupsd/apcupsd.conf configuration file
- not the name in the EEPROM of a smart UPS.

connected This is 1 if apcupsd is connected to the UPS via a serial or USB port. In the case of a
slave machine where apcupsd is not directly connected to the UPS, this value will be 0.

powered This is 1 if the computer on which apcupsd is running is powered by the UPS and 0 if not.
This is not currently implemented and always defaults to 0.

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.

LIST OF EVENTS AND DEFAULT ACTIONS
annoyme apcupsd generates this event when a shutdown is scheduled, and the time specified by the
ANNOYME configuration directive in the /etc/apcupsd/apcupsd.conf file has expired.

Default action -- sends "Power problems please logoff." to wall(1) and then exits.

battattach apcupsd generates this event when it detects that the UPS battery has been reconnected after
a battdetach event.

Default action: does nothing.

battdetach apcupsd generates this event when it detects that the UPS battery has been disconnected.

Default action: does nothing.

changeme apcupsd generates this event when it detects that the utility power is on, but the battery
is not functioning correctly. This is repeated every 9 hours.

Default action -- sends "Emergency! UPS batteries have failed Change them NOW" to wall and
then exits.

commfailure apcupsd generates this event each time it loses communication with the monitored UPS. This
event is not detected on simple signalling UPSes like the Back-UPS 650.

Default action -- sends "Communications with UPS lost." to wall and then exits.

commok apcupsd generates this event after a commfailure event when communication with the UPS is
re-established.

Default action -- sends "Communications with UPS restored." to wall and then exits.

doreboot This event is deprecated and should not be used.

Default action -- sends "Beginning Reboot Sequence" to wall and then calls shutdown(8) with
the "-r now" command line arguments to reboot the computer.

doshutdown apcupsd generates this event to shutdown the computer when the UPS is running on battery
power and one of the limits (time, run, load) is reached.

Default action -- sends "Beginning Shutdown Sequence" to wall and then calls shutdown(8)
with the command line arguments "-h now" to shutdown the computer.

emergency apcupsd generates this event when the UPS is on battery power, the battery is low and the
utility power is on: a sure sign of battery failure!

Default action -- sends "Emergency Shutdown. Possible UPS battery failure." to wall.
Immediately after this, apcupsd generates a doshutdown event to shutdown the system.

failing apcupsd generates this event when the UPS is running on batteries and the UPS sets the low
battery signal indicating that battery power is nearly exhausted. After this event, apcupsd
will immediately generate a doshutdown event.

Default action -- sends "UPS battery power exhausted. Doing shutdown." to wall and then
exits.

killpower apcupsd does not normally generate this event. Instead, it is invoked directly from the
system halt script as 'apccontrol killpower' because the killpower event needs to be
performed as late in system shutdown as possible.

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.

loadlimit apcupsd generates this event when the battery discharge limit specified by the BATTERYLEVEL
configuration directive has been reached.

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.

mainsback apcupsd generates this event when the utility power returns after a powerout event. The
doshutdown event may or may not have been generated depending on the parameters you have
defined and the length of the power outage. Attempting cancellation of a doshutdown event
should never be tried as it is very unlikely to succeed and will almost certainly leave your
computer in an indeterminate state.

Default action -- if the file /var/run/powerfail exists, sends "Continuing with shutdown."
to wall and then exits. Otherwise, does nothing.

onbattery apcupsd generates this event if a power failure has been detected and the UPS is still on
battery power at the expiry of the delay specified by the ONBATTERYDELAY configuration
directive.

Default action -- sends "Power failure. Running on UPS batteries." to wall and then exits.

offbattery apcupsd generates this event when the utility power returns if, and only if, the onbattery
event has been generated.

Default -- sends ""Power has returned..." to wall and then exits.

powerout apcupsd generates this event as soon as apcupsd detects that the UPS has switched to battery
power and it is not a self-test.

Default action -- does nothing.

remotedown apcupsd generates this event on a slave machine when it detects either (1) that the master
has shutdown, or (2) that an onbattery event has occurred and communication with the master
has been lost.

Default action: sends "Remote Shutdown. Beginning Shutdown Sequence." to wall and exits.
Immediately after this, apcupsd generates a doshutdown event to shutdown the system.

runlimit apcupsd generates this event when the remaining runtime limit specified by the MINUTES
configuration directive expires while the UPS is on battery power as the result of a utility
power outage. The remaining runtime is internally calculated by the UPS and monitored by
apcuspd.

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.

timeout apcupsd generates this event when the time specified by the TIMEOUT configuration directive
expires while the UPS is on battery power as the result of a utility power outage. This
configuration directive is not normally used with smart UPSes which would instead rely on
the more reliable remaining runtime (MINUTES) or the battery level (BATTERYLEVEL)
configuration directives.

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.

startselftest apcupsd generates this event when it detects the start of a UPS self test.

Default action: does nothing.

endselftest apcupsd generates this event when it detects the end of a UPS self test.

Default action: does nothing.

CUSTOMISING EVENT ACTIONS
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.

FILES

       /etc/apcupsd/apccontrol

AUTHORS

   This page
       Trevor Roydhouse

   Software
       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)

   Contributors
       An enormous number of users who have devoted their time and energy to this project -- thanks.

apccontrol v3.14.6                              January 10, 2009                                   APCCONTROL(8)

NAME

SYNOPSIS

DESCRIPTION

FILES

SEE ALSO

AUTHORS