1UPSMON(8) Network UPS Tools (NUT) UPSMON(8)
2
6 upsmon - UPS monitor and shutdown controller
7
9 upsmon -h
10 upsmon -c command
12 upsmon [-D] [-p] [-u user]
14
17 upsmon is the client process that is responsible for the most important
18 part of UPS monitoring ‐ shutting down the system when the power goes
19 out. It can call out to other helper programs for notification pur‐
20 poses during power events.
21 upsmon can monitor multiple systems using a single process. Every UPS
23 that is defined in the upsmon.conf(5) configuration file is assigned a
24 power value and a type (slave or master).
25
28 -h Display the help message.
29 -c command
32 Send the command command to the existing upsmon process. Valid
33 commands are:
34 fsd ‐ shutdown all master UPSes (use with caution)
36 stop ‐ stop monitoring and exit
38 reload ‐ reread upsmon.conf(5) configuration file. See "reload‐
40 ing nuances" below if this doesn't work.
41 -D Raise the debugging level. upsmon will run in the foreground
44 and prints information on stdout about the monitoring process.
45 Use this multiple times for more details.
46 -K Test for the shutdown flag. If it exists and contains the magic
49 string from upsmon, then upsmon will exit with EXIT_SUCCESS.
50 Any other condition will make upsmon exit with EXIT_FAILURE.
51 You can test for a successful exit from upsmon -K in your shut‐
53 down scripts to know when to call upsdrvctl(8) to shut down the
54 UPS.
55 -p Run privileged all the time. Normally upsmon will split into
58 two processes. The majority of the code runs as an unprivileged
59 user, and only a tiny stub runs as root. This switch will dis‐
60 able that mode, and run the old "all root all the time" system.
61 This is not the recommended mode, and you should not use this
63 unless you have a very good reason.
64 -u user
67 Set the user for the unprivileged monitoring process. This has
68 no effect when using -p.
69 The default user is set at configure time with 'configure
71 --with-user=...'. Typically this is 'nobody', but other distri‐
72 butions will probably have a specific 'nut' user for this task.
73 If your notification scripts need to run as a specific user, set
74 it here.
75 You can also set this in the upsmon.conf(5) file with the
77 RUN_AS_USER directive.
78
81 In the upsmon.conf(5), you must specify at least one UPS that will be
82 monitored. Use the MONITOR directive.
83 MONITOR system powervalue username password type
85 The system refers to a upsd(8) server, in the form upsname@host‐
87 name[:port]. Some examples follow:
88 ‐ "su700@mybox" means a UPS called "su700" on a system called "mybox".
90 This is the normal form.
91 ‐ "fenton@bigbox:5678" is a UPS called "fenton" on a system called
93 "bigbox" which runs upsd(8) on port "5678".
94 The powervalue refers to how many power supplies on this system are
96 being driven this UPS. This is typically set to 1, but see the section
97 on power values below.
98 The username is a section in your upsd.users(5) file. Whatever pass‐
100 word you set in that section must match the password set in this file.
101 The type set in that section must also match the type here ‐ master or
103 slave. In general, a master process is one running on the system with
104 the UPS actually plugged into a serial port, and a slave is drawing
105 power from the UPS but can't talk to it directly. See the section on
106 UPS types for more.
107
110 upsmon senses several events as it monitors each UPS. They are called
111 notify events as they can be used to tell the users and admins about
112 the change in status. See the additional NOTIFY‐related sections below
113 for information on customizing the delivery of these messages.
114 ONLINE The UPS is back on line.
117 ONBATT The UPS is on battery.
120 LOWBATT
123 The UPS battery is low (as determined by the driver).
124 FSD The UPS has been commanded into the "forced shutdown" mode.
127 COMMOK Communication with the UPS has been established.
130 COMMBAD
133 Communication with the UPS was just lost.
134 SHUTDOWN
137 The local system is being shut down.
138 REPLBATT
141 The UPS needs to have its battery replaced.
142 NOCOMM The UPS can't be contacted for monitoring.
145
148 In upsmon.conf(5), you can configure a program called the NOTIFYCMD
149 that will handle events that occur.
150 NOTIFYCMD "path to program"
152 NOTIFYCMD "/usr/local/bin/notifyme"
154 Remember to wrap the path in "quotes" if it contains any spaces.
156 The program you run as your NOTIFYCMD can use the environment variables
158 NOTIFYTYPE and UPSNAME to know what has happened and on which UPS. It
159 also receives the notification message (see below) as the first (and
160 only) argument, so you can deliver a preformatted message too.
161 Note that the NOTIFYCMD will only be called for a given event when you
163 set the EXEC flag by using the notify flags, below:
164
167 By default, all notify events (see above) generate a global message
168 (wall) to all users, plus they are logged via the syslog. You can
169 change this with the NOTIFYFLAG directive in the configuration file:
170 NOTIFYFLAG notifytype flags
172 Examples:
174 NOTIFYFLAG ONLINE SYSLOG
176 NOTIFYFLAG ONBATT SYSLOG+WALL
178 NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC
180 The flags that can be set on a given notify event are:
182 SYSLOG Write this message to the syslog.
185 WALL Send this message to all users on the system via 'wall'.
188 EXEC Execute the NOTIFYCMD.
191 IGNORE Don't do anything. If you use this, don't use any of the other
194 flags.
195 You can mix these flags. "SYSLOG+WALL+EXEC" does all three for a given
197 event.
198
201 upsmon comes with default messages for each of the NOTIFY events.
202 These can be changed with the NOTIFYMSG directive.
203 NOTIFYMSG type "message"
205 Examples:
207 NOTIFYMSG ONLINE "UPS %s is getting line power"
209 NOTIFYMSG ONBATT "Someone pulled the plug on %s"
211 The first instance of %s is replaced with the identifier of the UPS
213 that generated the event. These messages are used when sending walls
214 to the users directly from upsmon, and are also passed to the NOTIFY‐
215 CMD.
216
219 The "current overall power value" is the sum of all UPSes that are cur‐
220 rently able to supply power to the system hosting upsmon. Any UPS that
221 is either on line or just on battery contributes to this number. If a
222 UPS is critical (on battery and low battery) or has been put into
223 "forced shutdown" mode, it no longer contributes.
224 A "power value" on a MONITOR line in the config file is the number of
226 power supplies that the UPS runs on the current system.
227 MONITOR upsname powervalue username password type
229 Normally, you only have one power supply, so it will be set to 1.
231 MONITOR myups@myhost 1 username mypassword master
233 On a large server with redundant power supplies, the power value for a
235 UPS may be greater than 1. You may also have more than one of them
236 defined.
237 MONITOR ups-alpha@myhost 2 username mypassword master
239 MONITOR ups-beta@myhost 2 username mypassword master
241 You can also set the power value for a UPS to 0 if it does not supply
243 any power to that system. This is generally used when you want to use
244 the upsmon notification features for a UPS even though it's not actu‐
245 ally running the system that hosts upsmon. Don't set this to "master"
246 unless you really want to power this UPS off when this instance of
247 upsmon needs to shut down for its own reasons.
248 MONITOR faraway@anotherbox 0 username mypassword slave
250 The "minimum power value" is the number of power supplies that must be
252 receiving power in order to keep the computer running.
253 MINSUPPLIES value
255 Typical PCs only have 1, so most users will leave this at the default.
257 MINSUPPLIES 1
259 If you have a server or similar system with redundant power, then this
261 value will usually be set higher. One that requires three power sup‐
262 plies to be running at all times would simply set it to 3.
263 MINSUPPLIES 3
265 When the current overall power value drops below the minimum power
267 value, upsmon starts the shutdown sequence. This design allows you to
268 lose some of your power supplies in a redundant power environment with‐
269 out bringing down the entire system while still working properly for
270 smaller systems.
271
274 upsmon and upsd(8) don't always run on the same system. When they do,
275 any UPSes that are directly attached to the upsmon host should be moni‐
276 tored in "master" mode. This makes upsmon take charge of that equip‐
277 ment, and it will wait for slaves to disconnect before shutting down
278 the local system. This allows the distant systems (monitoring over the
279 network) to shut down cleanly before upsdrvctl shutdown runs and turns
280 them all off.
281 When upsmon runs as a slave, it is relying on the distant system to
283 tell it about the state of the UPS. When that UPS goes critical (on
284 battery and low battery), it immediately invokes the local shutdown
285 command. This needs to happen quickly. Once it disconnects from the
286 distant upsd(8) server, the master upsmon will start its own shutdown
287 process. Your slaves must all shut down before the master turns off
288 the power or filesystem damage may result.
289 upsmon deals with slaves that get wedged, hang, or otherwise fail to
291 disconnect from upsd(8) in a timely manner with the HOSTSYNC timer.
292 During a shutdown situation, the master upsmon will give up after this
293 interval and it will shut down anyway. This keeps the master from sit‐
294 ting there forever (which would endanger that host) if a slave should
295 break somehow. This defaults to 15 seconds.
296 If your master system is shutting down too quickly, set the FINALDELAY
298 interval to something greater than the default 15 seconds. Don't set
299 this too high, or your UPS battery may run out of power before the mas‐
300 ter upsmon process shuts down that system.
301
304 For those rare situations where the shutdown process can't be completed
305 between the time that low battery is signalled and the UPS actually
306 powers off the load, use the upssched(8) helper program. You can use
307 it along with upsmon to schedule a shutdown based on the "on battery"
308 event. upssched can then come back to upsmon to initiate the shutdown
309 once it's run on battery too long.
310 This can be complicated and messy, so stick to the default critical UPS
312 handling if you can.
313
316 If you have more than one power supply for redundant power, you may
317 also have more than one UPS feeding your computer. upsmon can handle
318 this. Be sure to set the UPS power values appropriately and the MIN‐
319 SUPPLIES value high enough so that it keeps running until it really
320 does need to shut down.
321 For example, the HP NetServer LH4 by default has 3 power supplies
323 installed, with one bay empty. It has two power cords, one per side of
324 the box. This means that one power cord powers two power supply bays,
325 and that you can only have two UPSes supplying power.
326 Connect UPS "alpha" to the cord feeding two power supplies, and UPS
328 "beta" to the cord that feeds the third and the empty slot. Define
329 alpha as a powervalue of 2, and beta as a powervalue of 1. Set the
330 MINSUPPLIES to 2.
331 When alpha goes on battery, your current overall power value will stay
333 at 3, as it's still supplying power. However, once it goes critical
334 (on battery and low battery), it will stop contributing to the current
335 overall power value. That means the value will be 1 (beta alone),
336 which is less than 2. That is insufficient to run the system, and
337 upsmon will invoke the shutdown sequence.
338 However, if beta goes critical, subtracting its contribution will take
340 the current overall value from 3 to 2. This is just high enough to
341 satisfy the minimum, so the system will continue running as before. If
342 beta returns later, it will be re‐added and the current value will go
343 back to 3. This allows you to swap out UPSes, change a power configu‐
344 ration, or whatever, as long as you maintain the minimum power value at
345 all times.
346
349 Besides being able to monitor multiple UPSes, upsmon can also monitor
350 them as different roles. If you have a system with multiple power sup‐
351 plies serviced by separate UPS batteries, it's possible to be a master
352 on one and a slave on the other. This usually happens when you run out
353 of serial ports and need to do the monitoring through another system
354 nearby.
355 This is also complicated, especially when it comes time to power down a
357 UPS that has gone critical but doesn't supply the local system. You
358 can do this with some scripting magic in your notify command script,
359 but it's beyond the scope of this manual.
360
363 When upsmon is forced to bring down the local system, it sets the "FSD"
364 (forced shutdown) flag on any UPSes that it is running in master mode.
365 This is used to synchronize slaves in the event that a master UPS that
366 is otherwise OK needs to be brought down due to some pressing event on
367 the master.
368 You can manually invoke this mode on the master upsmon by starting
370 another copy with '-c fsd'. This is useful when you want to initiate a
371 shutdown before the critical stage through some external means, such as
372 upssched(8).
373
376 In the event that upsmon can't reach upsd(8), it declares that UPS
377 "dead" after some interval controlled by DEADTIME in the
378 upsmon.conf(5). If this happens while that UPS was last known to be on
379 battery, it is assumed to have gone critical and no longer contributes
380 to the overall power value.
381 upsmon will alert you to a UPS that can't be contacted for monitoring
383 with a "NOCOMM" notifier by default every 300 seconds. This can be
384 changed with the NOCOMMWARNTIME setting.
385
388 upsmon usually gives up root powers for the process that does most of
389 the work, including handling signals like SIGHUP to reload the configu‐
390 ration file. This means your upsmon.conf(8) file must be readable by
391 the non‐root account that upsmon switches to.
392 If you want reloads to work, upsmon must run as some user that has per‐
394 missions to read the configuration file. I recommend making a new user
395 just for this purpose, as making the file readable by "nobody" (the
396 default user) would be a bad idea.
397 See the RUN_AS_USER section in upsmon.conf(8) for more on this topic.
399 Additionally, you can't change the SHUTDOWNCMD or POWERDOWNFLAG defini‐
401 tions with a reload due to the split‐process model. If you change
402 those values, you must stop upsmon and start it back up. upsmon will
403 warn you in the syslog if you make changes to either of those values
404 during a reload.
405
408 To test a synchronized shutdown without pulling the plug on your
409 UPS(es), you need only set the forced shutdown (FSD) flag on them. You
410 can do this by calling upsmon again to set the flag ‐ i.e.:
411 upsmon -c fsd
413 After that, the master and the slaves will do their usual shutdown
415 sequence as if the battery had gone critical. This is much easier on
416 your UPS equipment, and it beats crawling under a desk to find the
417 plug.
418
421 upsmon.conf(5)
422
425 Server:
426 upsd(8)
427 Clients:
430 upsc(8), upscmd(8), upsrw(8), upsmon(8)
431 CGI programs:
434 upsset.cgi(8), upsstats.cgi(8), upsimage.cgi(8)
435 Internet resources:
438 The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
439 Wed Nov 26 2003 UPSMON(8)