1UPSMON.CONF(5) Network UPS Tools (NUT) UPSMON.CONF(5)
2
3
4
6 upsmon.conf - Configuration for Network UPS Tools upsmon
7
8
10 This file's primary job is to define the systems that upsmon(8) will
11 monitor and to tell it how to shut down the system when necessary. It
12 will contain passwords, so keep it secure. Ideally,only the upsmon
13 process should be able to read it.
14
15 Additionally, other optional configuration values can be set in this
16 file.
17
18
20 DEADTIME seconds
21
22 upsmon allows a UPS to go missing for this many seconds before
23 declaring it "dead". The default is 15 seconds.
24
25 upsmon requires a UPS to provide status information every few
26 seconds (see POLLFREQ and POLLFREQALERT) to keep things updated.
27 If the status fetch fails, the UPS is marked stale. If it stays
28 stale for more than DEADTIME seconds, the UPS is marked dead.
29
30 A dead UPS that was last known to be on battery is assumed to
31 have changed to a low battery condition. This may force a shut‐
32 down if it is providing a critical amount of power to your sys‐
33 tem. This seems disruptive, but the alternative is barreling
34 ahead into oblivion and crashing when you run out of power.
35
36 Note: DEADTIME should be a multiple of POLLFREQ and POLLFRE‐
37 QALERT. Otherwise, you'll have "dead" UPSes simply because
38 upsmon isn't polling them quickly enough. Rule of thumb: take
39 the larger of the two POLLFREQ values, and multiply by 3.
40
41
42 FINALDELAY seconds
43
44 When running in master mode, upsmon waits this long after send‐
45 ing the NOTIFY_SHUTDOWN to warn the users. After the timer
46 elapses, it then runs your SHUTDOWNCMD. By default this is set
47 to 5 seconds.
48
49 If you need to let your users do something in between those
50 events, increase this number. Remember, at this point your UPS
51 battery is almost depleted, so don't make this too big.
52
53 Alternatively, you can set this very low so you don't wait
54 around when it's time to shut down. Some UPSes don't give much
55 warning for low battery and will require a value of 0 here for a
56 safe shutdown.
57
58 Note: If FINALDELAY on the slave is greater than HOSTSYNC on the
59 master, the master will give up waiting for the slave to discon‐
60 nect.
61
62
63 HOSTSYNC seconds
64
65 upsmon will wait up to this many seconds in master mode for the
66 slaves to disconnect during a shutdown situation. By default,
67 this is 15 seconds.
68
69 When a UPS goes critical (on battery + low battery, or "FSD" ‐
70 forced shutdown), the slaves are supposed to disconnect and shut
71 down right away. The HOSTSYNC timer keeps the master upsmon
72 from sitting there forever if one of the slaves gets stuck.
73
74 This value is also used to keep slave systems from getting stuck
75 if the master fails to respond in time. After a UPS becomes
76 critical, the slave will wait up to HOSTSYNC seconds for the
77 master to set the FSD flag. If that timer expires, the slave
78 will assume that the master is broken and will shut down anyway.
79
80 This keeps the slaves from shutting down during a short‐lived
81 status change to "OB LB" that the slaves see but the master
82 misses.
83
84
85 MINSUPPLIES num
86
87 Set the number of power supplies that must be receiving power to
88 keep this system running. Normal computers have just one power
89 supply, so the default value of 1 is acceptable.
90
91 Large/expensive server type systems usually have more, and can
92 run with a few missing. The HP NetServer LH4 can run with 2 out
93 of 4, for example, so you'd set it to 2. The idea is to keep
94 the box running as long as possible, right?
95
96 Obviously you have to put the redundant supplies on different
97 UPS circuits for this to make sense! See big‐servers.txt in the
98 docs subdirectory for more information and ideas on how to use
99 this feature.
100
101 Also see the section on "power values" in upsmon(8).
102
103
104 MONITOR system powervalue username password type
105
106 Each UPS that you need to be monitor should have a MONITOR line.
107 Not all of these need supply power to the system that is running
108 upsmon. You may monitor other systems if you want to be able to
109 send notifications about status changes on them.
110
111 You must have at least one MONITOR directive in this file.
112
113 system is a UPS identifier. It is in this form:
114
115 <upsname>@<hostname>[:<port>]
116
117 Some examples:
118
119 ‐ "su700@mybox" means a UPS called "su700" on a system called
120 "mybox". This is the normal form.
121
122 ‐ "fenton@bigbox:5678" is a UPS called "fenton" on a system
123 called "bigbox" which runs upsd(8) on port "5678".
124
125 powervalue is an integer representing the number of power sup‐
126 plies that the UPS feeds on this system. Most normal computers
127 have one power supply, and the UPS feeds it, so this value will
128 be 1. You need a very large or special system to have anything
129 higher here.
130
131 You can set the powervalue to 0 if you want to monitor a UPS
132 that doesn't actually supply power to this system. This is use‐
133 ful when you want to have upsmon do notifications about status
134 changes on a UPS without shutting down when it goes critical.
135
136 The username and password on this line must match an entry in
137 that system's upsd.users(5). If your username is "monmaster"
138 and your password is "blah", the MONITOR line might look like
139 this:
140
141 MONITOR myups@bigserver 1 monmaster blah master
142
143 Meanwhile, the upsd.users on 'bigserver' would look like this:
144
145 [monmaster]
146
147 password = blah
148
149 allowfrom = (ACLs from upsd.conf(5))
150
151 upsmon master (or slave)
152
153 The type refers to the relationship with upsd(8). It can be
154 either "master" or "slave". See upsmon(8) for more information
155 on the meaning of these modes. The mode you pick here also goes
156 in the upsd.users file, as seen in the example above.
157
158
159 NOCOMMWARNTIME seconds
160
161 upsmon will trigger a NOTIFY_NOCOMM after this many seconds if
162 it can't reach any of the UPS entries in this configuration
163 file. It keeps warning you until the situation is fixed. By
164 default this is 300 seconds.
165
166
167 NOTIFYCMD command
168
169 upsmon calls this to send messages when things happen.
170
171 This command is called with the full text of the message as one
172 argument. The environment string NOTIFYTYPE will contain the
173 type string of whatever caused this event to happen.
174
175 If you need to use upssched(8), then you must make it your NOTI‐
176 FYCMD by listing it here.
177
178 Note that this is only called for NOTIFY events that have EXEC
179 set with NOTIFYFLAG. See NOTIFYFLAG below for more details.
180
181 Making this some sort of shell script might not be a bad idea.
182 For more information and ideas, see pager.txt in the docs direc‐
183 tory.
184
185 Remember, this also needs to be one element in the configuration
186 file, so if your command has spaces, then wrap it in quotes.
187
188 NOTIFYCMD "/path/to/script --foo --bar"
189
190 This script is run in the background ‐ that is, upsmon forks
191 before it calls out to start it. This means that your NOTIFYCMD
192 may have multiple instances running simultaneously if a lot of
193 stuff happens all at once. Keep this in mind when designing
194 complicated notifiers.
195
196
197 NOTIFYMSG type message
198
199 upsmon comes with a set of stock messages for various events.
200 You can change them if you like.
201
202 NOTIFYMSG ONLINE "UPS %s is getting line power"
203
204 NOTIFYMSG ONBATT "Someone pulled the plug on %s"
205
206 Note that %s is replaced with the identifier of the UPS in ques‐
207 tion.
208
209 Possible values for type:
210
211 ONLINE ‐ UPS is back online
212
213 ONBATT ‐ UPS is on battery
214
215 LOWBATT ‐ UPS is on battery and has a low battery (is crit‐
216 ical)
217
218 FSD ‐ UPS is being shutdown by the master (FSD = "Forced
219 Shutdown")
220
221 COMMOK ‐ Communications established with the UPS
222
223 COMMBAD ‐ Communications lost to the UPS
224
225 SHUTDOWN ‐ The system is being shutdown
226
227 REPLBATT ‐ The UPS battery is bad and needs to be replaced
228
229 NOCOMM ‐ A UPS is unavailable (can't be contacted for moni‐
230 toring)
231
232 The message must be one element in the configuration file, so if
233 it contains spaces, you must wrap it in quotes.
234
235 NOTIFYMSG NOCOMM "Someone stole UPS %s"
236
237
238 NOTIFYFLAG type flag[+flag][+flag]...
239
240 By default, upsmon sends walls global messages to all logged in
241 users) via /bin/wall and writes to the syslog when things hap‐
242 pen. You can change this.
243
244 Examples:
245
246 NOTIFYFLAG ONLINE SYSLOG
247
248 NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
249
250 Possible values for the flags:
251
252 SYSLOG ‐ Write the message to the syslog
253
254 WALL ‐ Write the message to all users with /bin/wall
255
256 EXEC ‐ Execute NOTIFYCMD (see above) with the message
257
258 IGNORE ‐ Don't do anything
259
260 If you use IGNORE, don't use any other flags on the same line.
261
262
263 POLLFREQ seconds
264
265 Normally upsmon polls the upsd(8) server every 5 seconds. If
266 this is flooding your network with activity, you can make it
267 higher. You can also make it lower to get faster updates in
268 some cases.
269
270 There are some catches. First, if you set the POLLFREQ too
271 high, you may miss short‐lived power events entirely. You also
272 risk triggering the DEADTIME (see above) if you use a very large
273 number.
274
275 Second, there is a point of diminishing returns if you set it
276 too low. While upsd normally has all of the data available to
277 it instantly, most drivers only refresh the UPS status once
278 every 2 seconds. Polling any more than that usually doesn't get
279 you the information any faster.
280
281
282 POLLFREQALERT seconds
283
284 This is the interval that upsmon waits between polls if any of
285 its UPSes are on battery. You can use this along with POLLFREQ
286 above to slow down polls during normal behavior, but get quicker
287 updates when something bad happens.
288
289 This should always be equal to or lower than the POLLFREQ value.
290 By default it is also set 5 seconds.
291
292 The warnings from the POLLFREQ entry about too‐high and too‐low
293 values also apply here.
294
295
296 POWERDOWNFLAG filename
297
298 upsmon creates this file when running in master mode when the
299 UPS needs to be powered off. You should check for this file in
300 your shutdown scripts and call upsdrvctl shutdown if it exists.
301
302 This is done to forcibly reset the slaves, so they don't get
303 stuck at the "halted" stage even if the power returns during the
304 shutdown process. This usually does not work well on contact‐
305 closure UPSes that use the genericups driver.
306
307 See the shutdown.txt file in the docs subdirectory for more
308 information.
309
310
311 RBWARNTIME seconds
312
313 When a UPS says that it needs to have its battery replaced,
314 upsmon will generate a NOTIFY_REPLBATT event. By default this
315 happens every 43200 seconds ‐ 12 hours.
316
317 If you need another value, set it here.
318
319
320 RUN_AS_USER username
321
322 upsmon normally runs the bulk of the monitoring duties under
323 another user ID after dropping root privileges. On most systems
324 this means it runs as "nobody", since that's the default from
325 compile‐time.
326
327 The catch is that "nobody" can't read your upsmon.conf, since by
328 default it is installed so that only root can open it. This
329 means you won't be able to reload the configuration file, since
330 it will be unavailable.
331
332 The solution is to create a new user just for upsmon, then make
333 it run as that user. I suggest "nutmon", but you can use any‐
334 thing that isn't already taken on your system. Just create a
335 regular user with no special privileges and an impossible pass‐
336 word.
337
338 Then, tell upsmon to run as that user, and make upsmon.conf
339 readable by it. Your reloads will work, and your config file
340 will stay secure.
341
342 This file should not be writable by the upsmon user, as it would
343 be possible to exploit a hole, change the SHUTDOWNCMD to some‐
344 thing malicious, then wait for upsmon to be restarted.
345
346
347 SHUTDOWNCMD command
348
349 upsmon runs this command when the system needs to be brought
350 down. If it is a slave, it will do that immediately whenever
351 the current overall power value drops below the MINSUPPLIES
352 value above.
353
354 When upsmon is a master, it will allow any slaves to log out
355 before starting the local shutdown procedure.
356
357 Note that the command needs to be one element in the config
358 file. If your shutdown command includes spaces, then put it in
359 quotes to keep it together, i.e.:
360
361 SHUTDOWNCMD "/sbin/shutdown -h +0"
362
363
365 upsmon(8), upsd(8), nutupsdrv(8).
366
367
368 Internet resources:
369 The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
370
371
372
373 Wed Oct 16 2002 UPSMON.CONF(5)