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 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
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.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
