Penguin
Recent Changes
Annotated edit history of upsmon(8) version 3, including all changes. View license author blame.
Rev Author # Line
1 perry 1 UPSMON
2 !!!UPSMON
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 UPS DEFINITIONS
8 NOTIFY EVENTS
9 NOTIFY COMMAND
10 NOTIFY FLAGS
11 NOTIFY MESSAGES
12 POWER VALUES
13 UPS TYPES
14 TIMED SHUTDOWNS
15 REDUNDANT POWER SUPPLIES
16 MIXED OPERATIONS
17 FORCED SHUTDOWNS
18 DEAD UPSES
19 RELOADING NUANCES
20 SIMULATING POWER FAILURES
21 FILES
22 SEE ALSO
23 ----
24 !!NAME
25
26
27 upsmon - UPS monitor and shutdown controller
28 !!SYNOPSIS
29
30
31 __upsmon -h__
32
33
34 __upsmon -c__ ''command''
35
36
37 __upsmon [[-d] [[-i] [[-p] [[-u__ ''user'']
38 !!DESCRIPTION
39
40
41 __upsmon__ is the client process that is responsible for
42 the most important part of UPS monitoring - shutting down
43 the system when the power goes out. It can call out to other
44 helper programs for notification purposes during power
45 events.
46
47
48 upsmon can monitor multiple systems using a single process.
3 perry 49 Every UPS that is defined in the upsmon.conf(5)
1 perry 50 configuration file is assigned a power value and a type
51 (slave or master).
52 !!OPTIONS
53
54
55 -h
56
57
58 Display the help message.
59
60
61 -c ''command''
62
63
64 Send the command ''command'' to the existing upsmon
65 process. Valid commands are:
66
67
68 fsd - shutdown all master UPSes (use with
69 caution)
70
71
72 stop - stop monitoring and exit
73
74
3 perry 75 reload - reread upsmon.conf(5) configuration
1 perry 76 file
77
78
79 -d
80
81
82 Enable debugging mode. upsmon runs in the foreground and
83 prints debugging information on stdout about the monitoring
84 process.
85
86
87 -i
88
89
90 Enable infinite loop at shutdown. upsmon will keep a process
91 running after calling the shutdown command rather than
92 exiting. This is only useful if you have shutdown scripts
93 that complain when upsmon isn't running as they kill various
94 processes.
95
96
97 -p
98
99
100 Run privileged all the time. Normally upsmon will split into
101 two processes. The majority of the code runs as an
102 unprivileged user, and only a tiny stub runs as root. This
103 switch will disable that mode, and run the old
104
105
106 -u ''user''
107
108
109 Set the user for the unprivileged monitoring process. This
110 has no effect when using -p.
111
112
113 The default user is set at configure time with 'configure
114 --with-user=...'. Typically this is 'nobody', but other
115 distributions will probably have a specific 'nut' user for
116 this task. If your notification scripts need to run as a
117 specific user, set it here.
118
119
3 perry 120 You can also set this in the upsmon.conf(5) file with
1 perry 121 the RUN_AS_USER directive.
122 !!UPS DEFINITIONS
123
124
3 perry 125 In the upsmon.conf(5), you must specify at least one
1 perry 126 UPS that will be monitored. Use the MONITOR
127 directive.
128
129
130 MONITOR ''system powervalue password type''
131
132
133 The ''system'' refers to a upsd(8) server, in the
134 form [[
135 __
136
137
138
139
140 Other possibilities include:
141
142
143
144
145
146
147 Finally, to use all of these options:
148
149
150 upsd__(8) on port
151 __
152
153
154 The ''powervalue'' refers to how many power supplies on
155 this system are being driven this UPS. This is typically set
156 to 1, but see the section on power values
157 below.
158
159
160 Your ''password'' must match the entry in the
3 perry 161 upsd(8) server's upsd.conf(5) ACCESS directive
1 perry 162 for this system.
163
164
165 The ''type'' is either master or slave. In general, a
166 master process is one running on the system with the UPS
167 actually plugged into a serial port, and a slave is drawing
168 power from the UPS but can't talk to it directly. See the
169 section on UPS types for more.
170 !!NOTIFY EVENTS
171
172
173 upsmon senses several events as it monitors each UPS. They
174 are called notify events as they can be used to tell the
175 users and admins about the change in status. See the
176 additional NOTIFY-related sections below for information on
177 customizing the delivery of these messages.
178
179
180 ONLINE
181
182
183 The UPS is back on line.
184
185
186 ONBATT
187
188
189 The UPS is on battery.
190
191
192 LOWBATT
193
194
195 The UPS battery is low (as determined by the
196 driver).
197
198
199 FSD
200
201
202 The UPS has been commanded into the
203
204
205 COMMOK
206
207
208 Communication with the UPS has been
209 established.
210
211
212 COMMBAD
213
214
215 Communication with the UPS was just lost.
216
217
218 SHUTDOWN
219
220
221 The local system is being shut down.
222
223
224 REPLBATT
225
226
227 The UPS needs to have its battery replaced.
228
229
230 NOCOMM
231
232
233 The UPS can't be contacted for monitoring.
234 !!NOTIFY COMMAND
235
236
3 perry 237 In upsmon.conf(5), you can configure a program called
1 perry 238 the NOTIFYCMD that will handle events that
239 occur.
240
241
242 NOTIFYCMD path to program''''
243
244
245 NOTIFYCMD
246
247
248 Remember to wrap the path in
249
250
251 The program you run as your NOTIFYCMD can use the
252 environment variables NOTIFYTYPE and UPSNAME to know what
253 has happened and on which UPS. It also receives the
254 notification message (see below) as the first (and only)
255 argument, so you can deliver a preformatted message
256 too.
257
258
259 Note that the NOTIFYCMD will only be called for a given
260 event when you set the EXEC flag by using the notify flags,
261 below:
262 !!NOTIFY FLAGS
263
264
265 By default, all notify events (see above) generate a global
266 message (wall) to all users, plus they are logged via the
267 syslog. You can change this with the NOTIFYFLAG directive in
268 the configuration file:
269
270
271 NOTIFYFLAG ''notifytype flags''
272
273
274 Examples:
275
276
277 NOTIFYFLAG ONLINE SYSLOG
278
279
280 NOTIFYFLAG ONBATT SYSLOG+WALL
281
282
283 NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC
284
285
286 The flags that can be set on a given notify event
287 are:
288
289
290 SYSLOG
291
292
293 Write this message to the syslog.
294
295
296 WALL
297
298
299 Send this message to all users on the system via
300 'wall'.
301
302
303 EXEC
304
305
306 Execute the NOTIFYCMD.
307
308
309 IGNORE
310
311
312 Don't do anything. If you use this, don't use any of the
313 other flags.
314
315
316 You can mix these flags.
317 !!NOTIFY MESSAGES
318
319
320 upsmon comes with default messages for each of the NOTIFY
321 events. These can be changed with the NOTIFYMSG
322 directive.
323
324
325 NOTIFYMSG ''type''
326 ''message''''
327
328
329 Examples:
330
331
332 NOTIFYMSG ONLINE
333
334
335 NOTIFYMSG ONBATT
336
337
338 The first instance of %s is replaced with the identifier of
339 the UPS that generated the event. These messages are used
340 when sending walls to the users directly from upsmon, and
341 are also passed to the NOTIFYCMD.
342 !!POWER VALUES
343
344
345 The
346
347
348 A
349
350
351 MONITOR ''upsname powervalue password type''
352
353
354 Normally, you only have one power supply, so it will be set
355 to 1.
356
357
358 MONITOR myups@myhost 1 mypassword master
359
360
361 On a large server with redundant power supplies, the power
362 value for a UPS may be greater than 1. You may also have
363 more than one of them defined.
364
365
366 MONITOR ups-alpha@myhost 2 mypassword master
367
368
369 MONITOR ups-beta@myhost 2 mypassword master
370
371
372 You can also set the power value for a UPS to 0 if it does
373 not supply any power to that system. This is generally used
374 when you want to use the upsmon notification features for a
375 UPS even though it's not actually running the system that
376 hosts upsmon. Don't set this to
377
378
379 MONITOR faraway@anotherbox 0 mypassword slave
380
381
382 The
383
384
385 MINSUPPLIES ''value''
386
387
388 Typical PCs only have 1, so most users will leave this at
389 the default.
390
391
392 MINSUPPLIES 1
393
394
395 If you have a server or similar system with redundant power,
396 then this value will usually be set higher. One that
397 requires three power supplies to be running at all times
398 would simply set it to 3.
399
400
401 MINSUPPLIES 3
402
403
404 When the current overall power value drops below the minimum
405 power value, upsmon starts the shutdown sequence. This
406 design allows you to lose some of your power supplies in a
407 redundant power environment without bringing down the entire
408 system while still working properly for smaller
409 systems.
410 !!UPS TYPES
411
412
413 Remember that upsmon and upsd(8) need not run on the
414 same system. When they do, upsmon needs to monitor those
415 UPSes as a master. This means that it will take charge of
416 that UPS, and wait for all of the slaves to disconnect
417 before shutting itself down. This synchronization ensures
418 that systems that do monitoring over the network can shut
419 down cleanly before the master's driver shutdown (-k)
420 command turns them off.
421
422
423 When upsmon runs as a slave, it is relying on the distant
424 system to tell it about the state of the UPS. When that UPS
425 goes critical (on battery and low battery), it immediately
426 invokes the local shutdown command. This needs to happen
427 quickly. Once it disconnects from the distant upsd(8)
428 server, the master upsmon will start its own shutdown
429 process. Your slaves must all shut down before the master
430 turns off the power or filesystem damage may
431 result.
432
433
434 upsmon deals with slaves that get wedged, hang, or otherwise
435 fail to disconnect from upsd(8) in a timely manner
436 with the HOSTSYNC timer. During a shutdown situation, the
437 master upsmon will give up after this interval and it will
438 shut down anyway. This keeps the master from sitting there
439 forever (which would endanger that host) if a slave should
440 break somehow. This defaults to 15 seconds.
441
442
443 If your master system is shutting down too quickly, set the
444 FINALDELAY interval to something greater than the default 15
445 seconds. At the same time, don't set this too high, or your
446 UPS battery may run out of power before the master upsmon
447 process shuts down that system.
448 !!TIMED SHUTDOWNS
449
450
451 For those rare situations where the shutdown process can't
452 be completed between the time that low battery is signalled
453 and the UPS actually powers off the load, use the
454 upssched(8) helper program. You can use it along with
455 upsmon to schedule a shutdown based on the
456 __
457
458
459 This can be complicated and messy, so stick to the default
460 critical UPS handling if you can.
461 !!REDUNDANT POWER SUPPLIES
462
463
464 If you have more than one power supply for redundant power,
465 you may also have more than one UPS feeding your computer.
466 upsmon can handle this. Be sure to set the UPS power values
467 appropriately and the MINSUPPLIES value high enough so that
468 it keeps running until it really does need to shut
469 down.
470
471
2 perry 472 For example, the HP !NetServer LH4 by default has 3 power
1 perry 473 supplies installed, with one bay empty. It has two power
474 cords, one per side of the box. This means that one power
475 cord powers both power supply bays, and that you can only
476 have two UPSes supplying power.
477
478
479 Connect UPS
480
481
482 When alpha goes on battery, your current overall power value
483 will stay at 3, as it's still supplying power. However, once
484 it goes critical (on battery and low battery), it will stop
485 contributing to the current overall power value. That means
486 the value will be 1 (beta alone), which is less than 2. That
487 is insufficient to run the system, and upsmon will invoke
488 the shutdown sequence.
489
490
491 However, if beta goes critical, subtracting its contribution
492 will take the current overall value from 3 to 2. This is
493 just high enough to satisfy the minimum, so the system will
494 continue running as before. If beta returns later, it will
495 be re-added and the current value will go back to 3. This
496 allows you to swap out UPSes, change a power configuration,
497 or whatever, as long as you maintain the minimum power value
498 at all times.
499 !!MIXED OPERATIONS
500
501
502 Besides being able to monitor multiple UPSes, upsmon can
503 also monitor them as different roles. If you have a system
504 with multiple power supplies serviced by separate UPS
505 batteries, it's possible to be a master on one and a slave
506 on the other. This usually happens when you run out of
507 serial ports and need to do the monitoring through another
508 system nearby.
509
510
511 This is also complicated, especially when it comes time to
512 power down a UPS that has gone critical but doesn't supply
513 the local system. You can do this with some scripting magic
514 in your notify command script, but it's beyond the scope of
515 this manual.
516 !!FORCED SHUTDOWNS
517
518
519 When upsmon is forced to bring down the local system, it
520 sets the
521
522
523 You can manually invoke this mode on the master upsmon by
524 starting another copy with '-c fsd'. This is useful when you
525 want to initiate a shutdown before the critical stage
526 through some external means, such as
527 upssched(8).
528 !!DEAD UPSES
529
530
531 In the event that upsmon can't reach upsd(8), it
532 declares that UPS
3 perry 533 upsmon.conf(5). If this
1 perry 534 happens while that UPS was last known to be on battery, it
535 is assumed to have gone critical and no longer contributes
536 to the overall power value.
537
538
539 upsmon will alert you to a UPS that can't be contacted for
540 monitoring with a
541 !!RELOADING NUANCES
542
543
544 upsmon usually gives up root powers for the process that
545 does most of the work, including handling signals like
546 SIGHUP to reload the configuration file. This means your
3 perry 547 upsmon.conf(8) file must be readable by the non-root
1 perry 548 account that upsmon switches to.
549
550
551 If you want reloads to work, upsmon must run as some user
552 that has permissions to read the configuration file. I
553 recommend making a new user just for this purpose, as making
554 the file readable by
555
556
3 perry 557 See the RUN_AS_USER section in upsmon.conf(8) for
1 perry 558 more on this topic.
559 !!SIMULATING POWER FAILURES
560
561
562 To test a synchronized shutdown without pulling the plug on
563 your UPS(es), you need only set the forced shutdown (FSD)
564 flag on them. You can do this by calling upsmon again to set
565 the flag - i.e.:
566
567
568 upsmon -c fsd
569
570
571 After that, the master and the slaves will do their usual
572 shutdown sequence as if the battery had gone critical. This
573 is much easier on your UPS equipment, and it beats crawling
574 under a desk to find the plug.
575 !!FILES
576
577
3 perry 578 upsmon.conf(5)
1 perry 579 !!SEE ALSO
580
581
582 __Server:__
583
584
585 upsd(8)
586
587
588 __Clients:__
589
590
591 upsc(8), upscmd(8), upsct(8),
3 perry 592 upsct2(8), upsmon(8)
1 perry 593
594
595 __Internet resources:__
596
597
598 The NUT (Network UPS Tools) home page:
599 http://www.exploits.org/nut/
600
601
602 NUT mailing list archives and information:
603 http://lists.exploits.org/
604 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.