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

NAME

4     apccontrol apcupsd(8) event handler script
5

SYNOPSIS

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

DESCRIPTION

10     When apcupsd(8) detects anomalies from the UPS being monitored, it trig‐
11     gers an event which usually results in one or more calls to the
12     apccontrol shell script.  Each event causes apccontrol to take a particu‐
13     lar action. These actions default to sane behaviour for all the events
14     that apcupsd is likely to encounter. However, you can change the behav‐
15     iour of every single action.
16
17     When apcupsd detects an event, it calls the apccontrol script with the
18     following four arguments:
19
20     event       This is the event that occurred. Refer to the list of possi‐
21                 ble events below.
22
23     ups-name    This is the name of the UPS as specified in the
24                 /etc/apcupsd/apcupsd.conf configuration file - not the name
25                 in the EEPROM of a smart UPS.
26
27     connected   This is 1 if apcupsd is connected to the UPS via a serial or
28                 USB port.  In the case of a slave machine where apcupsd is
29                 not directly connected to the UPS, this value will be 0.
30
31     powered     This is 1 if the computer on which apcupsd is running is pow‐
32                 ered by the UPS and 0 if not. This is not currently imple‐
33                 mented and always defaults to 0.
34
35     Events are sent to the system log and, optionally, to the temporary
36     events file (/etc/apcupsd/apcupsd.events), and they also generate a call
37     to apccontrol which in turn will call any scripts you have placed in the
38     /etc/apcupsd directory.
39
40   LIST OF EVENTS AND DEFAULT ACTIONS
41     annoyme      apcupsd generates this event when a shutdown is scheduled,
42                  and the time specified by the ANNOYME configuration direc‐
43                  tive in the /etc/apcupsd/apcupsd.conf file has expired.
44
45                  Default action -- sends "Power problems please logoff." to
46                  wall(1) and then exits.
47
48     battattach   apcupsd generates this event when it detects that the UPS
49                  battery has been reconnected after a battdetach event.
50
51                  Default action: does nothing.
52
53     battdetach   apcupsd generates this event when it detects that the UPS
54                  battery has been disconnected.
55
56                  Default action: does nothing.
57
58     changeme     apcupsd generates this event when it detects that the util‐
59                  ity power is on, but the battery is not functioning cor‐
60                  rectly. This is repeated every 9 hours.
61
62                  Default action -- sends "Emergency! UPS batteries have
63                  failed Change them NOW" to wall and then exits.
64
65     commfailure  apcupsd generates this event each time it loses communica‐
66                  tion with the monitored UPS. This event is not detected on
67                  simple signalling UPSes like the Back-UPS 650.
68
69                  Default action -- sends "Communications with UPS lost." to
70                  wall and then exits.
71
72     commok       apcupsd generates this event after a commfailure event when
73                  communication with the UPS is re-established.
74
75                  Default action -- sends "Communications with UPS restored."
76                  to wall and then exits.
77
78     doreboot     This event is deprecated and should not be used.
79
80                  Default action -- sends "Beginning Reboot Sequence" to wall
81                  and then calls shutdown(8) with the "-r now" command line
82                  arguments to reboot the computer.
83
84     doshutdown   apcupsd generates this event to shutdown the computer when
85                  the UPS is running on battery power and one of the limits
86                  (time, run, load) is reached.
87
88                  Default action -- sends "Beginning Shutdown Sequence" to
89                  wall and then calls shutdown(8) with the command line argu‐
90                  ments "-h now" to shutdown the computer.
91
92     emergency    apcupsd generates this event when the UPS is on battery
93                  power, the battery is low and the utility power is on: a
94                  sure sign of battery failure!
95
96                  Default action -- sends "Emergency Shutdown. Possible UPS
97                  battery failure."  to wall. Immediately after this, apcupsd
98                  generates a doshutdown event to shutdown the system.
99
100     failing      apcupsd generates this event when the UPS is running on bat‐
101                  teries and the UPS sets the low battery signal indicating
102                  that battery power is nearly exhausted. After this event,
103                  apcupsd will immediately generate a doshutdown event.
104
105                  Default action -- sends "UPS battery power exhausted. Doing
106                  shutdown." to wall and then exits.
107
108     killpower    apcupsd does not normally generate this event. Instead, it
109                  is invoked directly from the system halt script as 'apccon‐
110                  trol killpower' because the killpower event needs to be per‐
111                  formed as late in system shutdown as possible.
112
113                  Default action -- sends "UPS now committed to shut down" to
114                  wall, waits for 10 seconds and then issues the command
115                  "apcupsd --killpower" to put the UPS into hibernate mode and
116                  shut off power to the connected equipment.  In the case of a
117                  smart UPS, the UPS will then wait for the expiry of any con‐
118                  figured shutdown time delay specified by the SLEEP configu‐
119                  ration directive.  In hibernate mode, the UPS will restore
120                  utility power to the connected equipment subject to the val‐
121                  ues specified for the RETURNCHARGE and WAKEUP configuration
122                  directives.
123
124     loadlimit    apcupsd generates this event when the battery discharge
125                  limit specified by the BATTERYLEVEL configuration directive
126                  has been reached.
127
128                  Default action -- sends "UPS battery discharge limit
129                  reached. Doing shutdown" to wall and then exits. After this
130                  event, apcupsd will immediately generate a doshutdown event.
131
132     mainsback    apcupsd generates this event when the utility power returns
133                  after a powerout event. The doshutdown event may or may not
134                  have been generated depending on the parameters you have
135                  defined and the length of the power outage. Attempting can‐
136                  cellation of a doshutdown event should never be tried as it
137                  is very unlikely to succeed and will almost certainly leave
138                  your computer in an indeterminate state.
139
140                  Default action -- if the file /var/run/powerfail exists,
141                  sends "Continuing with shutdown." to wall and then exits.
142                  Otherwise, does nothing.
143
144     onbattery    apcupsd generates this event if a power failure has been
145                  detected and the UPS is still on battery power at the expiry
146                  of the delay specified by the ONBATTERYDELAY configuration
147                  directive.
148
149                  Default action -- sends "Power failure. Running on UPS bat‐
150                  teries." to wall and then exits.
151
152     offbattery   apcupsd generates this event when the utility power returns
153                  if, and only if, the onbattery event has been generated.
154
155                  Default -- sends ""Power has returned..." to wall and then
156                  exits.
157
158     powerout     apcupsd generates this event as soon as apcupsd detects that
159                  the UPS has switched to battery power and it is not a self-
160                  test.
161
162                  Default action -- does nothing.
163
164     remotedown   apcupsd generates this event on a slave machine when it
165                  detects either (1) that the master has shutdown, or (2) that
166                  an onbattery event has occurred and communication with the
167                  master has been lost.
168
169                  Default action: sends "Remote Shutdown. Beginning Shutdown
170                  Sequence." to wall and exits. Immediately after this,
171                  apcupsd generates a doshutdown event to shutdown the system.
172
173     runlimit     apcupsd generates this event when the remaining runtime
174                  limit specified by the MINUTES configuration directive
175                  expires while the UPS is on battery power as the result of a
176                  utility power outage. The remaining runtime is internally
177                  calculated by the UPS and monitored by apcuspd.
178
179                  Default action -- sends "UPS battery runtime percent
180                  reached. Doing shutdown."  to wall and then exits. After
181                  this event, apcupsd will immediately generate a doshutdown
182                  event.
183
184     timeout      apcupsd generates this event when the time specified by the
185                  TIMEOUT configuration directive expires while the UPS is on
186                  battery power as the result of a utility power outage. This
187                  configuration directive is not normally used with smart
188                  UPSes which would instead rely on the more reliable remain‐
189                  ing runtime (MINUTES) or the battery level (BATTERYLEVEL)
190                  configuration directives.
191
192                  Default action -- send "UPS battery runtime limit exceeded.
193                  Doing shutdown."  to wall and then exits. After this event,
194                  apcupsd will immediately generate a doshutdown event.
195
196     startselftest apcupsd generates this event when it detects the start of a
197                  UPS self test.
198
199                  Default action: does nothing.
200
201     endselftest  apcupsd generates this event when it detects the end of a
202                  UPS self test.
203
204                  Default action: does nothing.
205
206   CUSTOMISING EVENT ACTIONS
207     Do not modify apccontrol directly as it will be overwritten the next time
208     you upgrade to a new release of apcupsd.
209
210     The recommended way to customise an event action is simply to create an
211     executable program or script file with the same name as the event and put
212     that file in the /etc/apcupsd directory. Now, when the selected event
213     occurs, apccontrol will execute your program or script.
214
215     If you want apccontrol to also execute its default action for the
216     selected event, your program or script should exit with an exit status of
217     0 (zero).
218
219     If you do not want apccontrol to also execute its default action for the
220     selected event, your program or script must exit with an exit status of
221     99. Be aware that if you completely override the default action, you must
222     ensure the proper shutdown of your computer if this is necessary.
223
224     Some sample scripts (changeme, commfailure, commok, offbattery and onbat‐
225     tery) that email messages to root instead of broadcasting messages to all
226     logged-in users may be found in /etc/apcupsd after an installation and
227     also in the platforms/etc directory of the apcupsd source code.
228

FILES

230     /etc/apcupsd/apccontrol
231

SEE ALSO

233     wall(1), apcupsd.conf(5), apcupsd(8), shutdown(8).
234
235     The HTML apcupsd manual installed on your system or available online at
236     http://www.apcupsd.org/
237

AUTHORS

239   This page
240     Trevor Roydhouse
241
242   Software
243     Adam Kropelin (current Project Manager and Code Maintainer)
244     Kern Sibbald (former Project Manager and Code Maintainer)
245     Riccardo Facchetti (former Project Manager and Code Maintainer)
246     Andre M. Hedrick (Project Founder and former Code Maintainer)
247
248   Contributors
249     An enormous number of users who have devoted their time and energy to
250     this project -- thanks.
251
252apccontrol v3.14.6             January 10, 2009             apccontrol v3.14.6
Impressum