1APCCONTROL(8) BSD System Manager's Manual APCCONTROL(8)
2
4 apccontrol — apcupsd(8) event handler script
5
7 apccontrol { <event> <ups-name> <connected> <powered> }
8
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 When apcupsd detects an event, it calls the apccontrol script with the
18 following four arguments:
19 event This is the event that occurred. Refer to the list of possi‐
21 ble events below.
22 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 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 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 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 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 Default action -- sends "Power problems please logoff." to
46 wall(1) and then exits.
47 battattach apcupsd generates this event when it detects that the UPS
49 battery has been reconnected after a battdetach event.
50 Default action: does nothing.
52 battdetach apcupsd generates this event when it detects that the UPS
54 battery has been disconnected.
55 Default action: does nothing.
57 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 Default action -- sends "Emergency! UPS batteries have
63 failed Change them NOW" to wall and then exits.
64 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 Default action -- sends "Communications with UPS lost." to
70 wall and then exits.
71 commok apcupsd generates this event after a commfailure event when
73 communication with the UPS is re-established.
74 Default action -- sends "Communications with UPS restored."
76 to wall and then exits.
77 doreboot This event is deprecated and should not be used.
79 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 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 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 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 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 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 Default action -- sends "UPS battery power exhausted. Doing
106 shutdown." to wall and then exits.
107 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 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 loadlimit apcupsd generates this event when the battery discharge
125 limit specified by the BATTERYLEVEL configuration directive
126 has been reached.
127 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 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 Default action -- if the file /var/run/powerfail exists,
141 sends "Continuing with shutdown." to wall and then exits.
142 Otherwise, does nothing.
143 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 Default action -- sends "Power failure. Running on UPS bat‐
150 teries." to wall and then exits.
151 offbattery apcupsd generates this event when the utility power returns
153 if, and only if, the onbattery event has been generated.
154 Default -- sends ""Power has returned..." to wall and then
156 exits.
157 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 Default action -- does nothing.
163 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 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 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 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 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 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 startselftest apcupsd generates this event when it detects the start of a
197 UPS self test.
198 Default action: does nothing.
200 endselftest apcupsd generates this event when it detects the end of a
202 UPS self test.
203 Default action: does nothing.
205 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 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 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 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 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
230 /etc/apcupsd/apccontrol
231
233 wall(1), apcupsd.conf(5), apcupsd(8), shutdown(8).
234 The HTML apcupsd manual installed on your system or available online at
236 http://www.apcupsd.org/
237
239 This page
240 Trevor Roydhouse
241 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 Contributors
249 An enormous number of users who have devoted their time and energy to
250 this project -- thanks.
251apccontrol v3.14.6 January 10, 2009 apccontrol v3.14.6