APCCONTROL(8)			   BSD System Manager's Manual			    APCCONTROL(8)

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 argu‐
     ments:

     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 con‐
		 figuration 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 speci‐
		  fied 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 dis‐
		  connected.

		  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 moni‐
		  tored 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 can‐
		  cellation 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 ONBAT‐
		  TERYDELAY 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 commu‐
		  nication 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 cal‐
		  culated 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 configura‐
		  tion 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 direc‐
     tory. 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 pro‐
     gram 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

SEE ALSO
     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/

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 v3.14.6
