Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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	trig-
     gers an event which usually results in one	or more	calls to the
     apccontrol	shell script.  Each event causes apccontrol to take a particu-
     lar action. These actions default to sane behaviour for all the events
     that apcupsd is likely to encounter. However, you can change the behav-
     iour 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 possi-
		 ble 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 pow-
		 ered by the UPS and 0 if not. This is not currently imple-
		 mented	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 direc-
		  tive 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	util-
		  ity power is on, but the battery is not functioning cor-
		  rectly. 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 communica-
		  tion 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	argu-
		  ments	"-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 bat-
		  teries 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 'apccon-
		  trol killpower' because the killpower	event needs to be per-
		  formed 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 con-
		  figured shutdown time	delay specified	by the SLEEP configu-
		  ration directive.  In	hibernate mode,	the UPS	will restore
		  utility power	to the connected equipment subject to the val-
		  ues 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 de-
		  fined	and the	length of the power outage. Attempting cancel-
		  lation 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 de-
		  tected 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 bat-
		  teries." 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 de-
		  tects	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 ex-
		  pires	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 UP-
		  Ses which would instead rely on the more reliable remaining
		  runtime (MINUTES) or the battery level (BATTERYLEVEL)	con-
		  figuration 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 oc-
     curs, apccontrol will execute your	program	or script.

     If	you want apccontrol to also execute its	default	action for the se-
     lected 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	onbat-
     tery) 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

NAME | SYNOPSIS | DESCRIPTION | FILES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=apccontrol&sektion=8&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help