1UPSMON(8) NUT Manual UPSMON(8)
2
6 upsmon - UPS monitor and shutdown controller
7
9 upsmon -h
10 upsmon -c command [-P pid]
12 upsmon [-D] [-F | -B] [-K] [-p] [-u user]
14
16 upsmon is the client process that is responsible for the most important
17 part of UPS monitoring—shutting down the system when the power goes
18 out. It can call out to other helper programs for notification purposes
19 during power events.
20 upsmon can monitor multiple systems using a single process. Every UPS
22 that is defined in the upsmon.conf(5) configuration file is assigned a
23 power value and a type (primary or secondary).
24
26 -h
27 Display the help message.
28 -c command
30 Send the command command to the existing upsmon process. Valid
31 commands are:
32 fsd
34 shutdown all primary-mode UPSes (use with caution)
35 stop
37 stop monitoring and exit
38 reload
40 reread upsmon.conf(5) configuration file. See "reloading
41 nuances" below if this doesn’t work.
42 -P pid
44 Send the command signal above using specified PID number, rather
45 than consulting the PID file. This can help define service units
46 which start main upsmon as a foreground process so it does not have
47 to rely on a PID file.
48 -D
50 Raise the debugging level. upsmon will run in the foreground by
51 default, and will print information on stdout about the monitoring
52 process. Use this option multiple times for more details.
53 -F
55 upsmon will run in the foreground, regardless of debugging
56 settings.
57 -B
59 upsmon will run in the background, regardless of debugging
60 settings.
61 -K
63 Test for the shutdown flag. If it exists and contains the magic
64 string from upsmon, then upsmon will exit with EXIT_SUCCESS. Any
65 other condition will make upsmon exit with EXIT_FAILURE.
66 You can test for a successful exit from upsmon -K in your shutdown
68 scripts to know when to call upsdrvctl(8) to shut down the UPS.
69 -p
71 Run privileged all the time. Normally upsmon will split into two
72 processes. The majority of the code runs as an unprivileged user,
73 and only a tiny stub runs as root. This switch will disable that
74 mode, and run the old "all root all the time" system.
75 This is not the recommended mode, and you should not use this
77 unless you have a very good reason.
78 -u user
80 Set the user for the unprivileged monitoring process. This has no
81 effect when using -p.
82 The default user is set at configure time with configure
84 --with-user=.... Typically this is nobody, but other distributions
85 will probably have a specific nut user for this task. If your
86 notification scripts need to run as a specific user, set it here.
87 You can also set this in the upsmon.conf(5) file with the
89 RUN_AS_USER directive.
90
92 In the upsmon.conf(5), you must specify at least one UPS that will be
93 monitored. Use the MONITOR directive.
94 MONITOR 'system' 'powervalue' 'username' 'password' 'type'
96 The system refers to a upsd(8) server, in the form
98 upsname[@hostname[:port]]. The default hostname is "localhost". Some
99 examples follow:
100 • "su700@mybox" means a UPS called "su700" on a system called
102 "mybox". This is the normal form.
103 • "fenton@bigbox:5678" is a UPS called "fenton" on a system called
105 "bigbox" which runs upsd(8) on port "5678".
106 The powervalue refers to how many power supplies on this system are
108 being driven this UPS. This is typically set to 1, but see the section
109 on power values below.
110 The username is a section in your upsd.users(5) file. Whatever password
112 you set in that section must match the password set in this file.
113 The type set in that section must also match the type here — primary or
115 secondary. In general, a primary process is one running on the system
116 with the UPS actually plugged into a serial port, and a secondary is
117 drawing power from the UPS but can’t talk to it directly. See the
118 section on UPS types for more.
119
121 upsmon senses several events as it monitors each UPS. They are called
122 notify events as they can be used to tell the users and admins about
123 the change in status. See the additional NOTIFY-related sections below
124 for information on customizing the delivery of these messages.
125 ONLINE
127 The UPS is back on line.
128 ONBATT
130 The UPS is on battery.
131 LOWBATT
133 The UPS battery is low (as determined by the driver).
134 FSD
136 The UPS has been commanded into the "forced shutdown" mode.
137 COMMOK
139 Communication with the UPS has been established.
140 COMMBAD
142 Communication with the UPS was just lost.
143 SHUTDOWN
145 The local system is being shut down.
146 REPLBATT
148 The UPS needs to have its battery replaced.
149 NOCOMM
151 The UPS can’t be contacted for monitoring.
152
154 In upsmon.conf(5), you can configure a program called the NOTIFYCMD
155 that will handle events that occur.
156 NOTIFYCMD "path to program"
158 NOTIFYCMD "/usr/local/bin/notifyme"
160 Remember to wrap the path in "quotes" if it contains any spaces.
162 The program you run as your NOTIFYCMD can use the environment variables
164 NOTIFYTYPE and UPSNAME to know what has happened and on which UPS. It
165 also receives the notification message (see below) as the first (and
166 only) argument, so you can deliver a pre-formatted message too.
167 Note that the NOTIFYCMD will only be called for a given event when you
169 set the EXEC flag by using the notify flags, as detailed below.
170
172 By default, all notify events (see above) generate a global message
173 (wall) to all users, plus they are logged via the syslog. You can
174 change this with the NOTIFYFLAG directive in the configuration file:
175 NOTIFYFLAG notifytype flags
177 Examples:
179 • NOTIFYFLAG ONLINE SYSLOG
181 • NOTIFYFLAG ONBATT SYSLOG+WALL
183 • NOTIFYFLAG LOWBATT SYSLOG+WALL+EXEC
185 The flags that can be set on a given notify event are:
187 SYSLOG
189 Write this message to the syslog.
190 WALL
192 Send this message to all users on the system via wall(1).
193 EXEC
195 Execute the NOTIFYCMD.
196 IGNORE
198 Don’t do anything. If you use this, don’t use any of the other
199 flags.
200 You can mix these flags. "SYSLOG+WALL+EXEC" does all three for a given
202 event.
203
205 upsmon comes with default messages for each of the NOTIFY events. These
206 can be changed with the NOTIFYMSG directive.
207 NOTIFYMSG type "message"
209 Examples:
211 • NOTIFYMSG ONLINE "UPS %s is getting line power"
213 • ` NOTIFYMSG ONBATT "Someone pulled the plug on %s"`
215 The first instance of %s is replaced with the identifier of the UPS
217 that generated the event. These messages are used when sending walls to
218 the users directly from upsmon, and are also passed to the NOTIFYCMD.
219
221 The "current overall power value" is the sum of all UPSes that are
222 currently able to supply power to the system hosting upsmon. Any UPS
223 that is either on line or just on battery contributes to this number.
224 If a UPS is critical (on battery and low battery) or has been put into
225 "forced shutdown" mode, it no longer contributes.
226 A "power value" on a MONITOR line in the config file is the number of
228 power supplies that the UPS runs on the current system.
229 MONITOR upsname powervalue username password type
231 Normally, you only have one power supply, so it will be set to 1.
233 MONITOR myups@myhost 1 username mypassword primary
235 On a large server with redundant power supplies, the power value for a
237 UPS may be greater than 1. You may also have more than one of them
238 defined.
239 MONITOR ups-alpha@myhost 2 username mypassword primary
241 MONITOR ups-beta@myhost 2 username mypassword primary
243 You can also set the power value for a UPS to 0 if it does not supply
245 any power to that system. This is generally used when you want to use
246 the upsmon notification features for a UPS even though it’s not
247 actually running the system that hosts upsmon. Don’t set this to
248 "primary" unless you really want to power this UPS off when this
249 instance of upsmon needs to shut down for its own reasons.
250 MONITOR faraway@anotherbox 0 username mypassword secondary
252 The "minimum power value" is the number of power supplies that must be
254 receiving power in order to keep the computer running.
255 MINSUPPLIES value
257 Typical PCs only have 1, so most users will leave this at the default.
259 MINSUPPLIES 1
261 If you have a server or similar system with redundant power, then this
263 value will usually be set higher. One that requires three power
264 supplies to be running at all times would simply set it to 3.
265 MINSUPPLIES 3
267 When the current overall power value drops below the minimum power
269 value, upsmon starts the shutdown sequence. This design allows you to
270 lose some of your power supplies in a redundant power environment
271 without bringing down the entire system while still working properly
272 for smaller systems.
273
275 upsmon and upsd(8) don’t always run on the same system. When they do,
276 any UPSes that are directly attached to the upsmon host should be
277 monitored in "primary" mode. This makes upsmon take charge of that
278 equipment, and it will wait for the "secondary" systems to disconnect
279 before shutting down the local system. This allows the distant systems
280 (monitoring over the network) to shut down cleanly before upsdrvctl
281 shutdown runs and turns them all off.
282 When upsmon runs as a secondary, it is relying on the distant system to
284 tell it about the state of the UPS. When that UPS goes critical (on
285 battery and low battery), it immediately invokes the local shutdown
286 command. This needs to happen quickly. Once all secondaries disconnect
287 from the distant upsd(8) server, its primary-mode upsmon will start its
288 own shutdown process. Your secondary systems must all quiesce and shut
289 down before the primary turns off the shared power source, or
290 filesystem damage may result.
291 upsmon deals with secondaries that get wedged, hang, or otherwise fail
293 to disconnect from upsd(8) in a timely manner with the HOSTSYNC timer.
294 During a shutdown situation, the primary upsmon will give up after this
295 interval and it will shut down anyway. This keeps the primary from
296 sitting there forever (which would endanger that host) if a secondary
297 should break somehow. This defaults to 15 seconds.
298 If your primary system is shutting down too quickly, set the FINALDELAY
300 interval to something greater than the default 15 seconds. Don’t set
301 this too high, or your UPS battery may run out of power before the
302 primary upsmon process shuts down that system.
303
305 For those rare situations where the shutdown process can’t be completed
306 between the time that low battery is signalled and the UPS actually
307 powers off the load, use the upssched(8) helper program. You can use it
308 along with upsmon to schedule a shutdown based on the "on battery"
309 event. upssched can then come back to upsmon to initiate the shutdown
310 once it has run on battery too long.
311 This can be complicated and messy, so stick to the default critical UPS
313 handling if you can.
314
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
319 MINSUPPLIES 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 (on
334 battery and low battery), it will stop contributing to the current
335 overall power value. That means the value will be 1 (beta alone), which
336 is less than 2. That is insufficient to run the system, and upsmon will
337 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
344 configuration, or whatever, as long as you maintain the minimum power
345 value at all times.
346
348 Besides being able to monitor multiple UPSes, upsmon can also monitor
349 them as different roles. If you have a system with multiple power
350 supplies serviced by separate UPS batteries, it’s possible to be a
351 primary on one UPS and a secondary on the other. This usually happens
352 when you run out of serial or USB ports and need to do the monitoring
353 through another system nearby.
354 This is also complicated, especially when it comes time to power down a
356 UPS that has gone critical but doesn’t supply the local system. You can
357 do this with some scripting magic in your notify command script, but
358 it’s beyond the scope of this manual.
359
361 When upsmon is forced to bring down the local system, it sets the "FSD"
362 (forced shutdown) flag on any UPSes that it is running in primary mode.
363 This is used to synchronize secondary systems in the event that a
364 primary which is otherwise OK needs to be brought down due to some
365 pressing event on the UPS manager system.
366 You can manually invoke this mode on the system with primary-mode
368 upsmon by starting another copy of the program with -c fsd command line
369 argument. This is useful when you want to initiate a shutdown before
370 the critical stage through some external means, such as upssched(8).
371
373 In the event that upsmon can’t reach upsd(8), it declares that UPS
374 "dead" after some interval controlled by DEADTIME in the
375 upsmon.conf(5). If this happens while that UPS was last known to be on
376 battery, it is assumed to have gone critical and no longer contributes
377 to the overall power value.
378 upsmon will alert you to a UPS that can’t be contacted for monitoring
380 with a "NOCOMM" notifier by default every 300 seconds. This can be
381 changed with the NOCOMMWARNTIME setting.
382
384 upsmon usually gives up root powers for the process that does most of
385 the work, including handling signals like SIGHUP to reload the
386 configuration file. This means your upsmon.conf(8) file must be
387 readable by the non-root account that upsmon switches to.
388 If you want reloads to work, upsmon must run as some user that has
390 permissions to read the configuration file. I recommend making a new
391 user just for this purpose, as making the file readable by "nobody"
392 (the default user) would be a bad idea.
393 See the RUN_AS_USER section in upsmon.conf(8) for more on this topic.
395 Additionally, you can’t change the SHUTDOWNCMD or POWERDOWNFLAG
397 definitions with a reload due to the split-process model. If you change
398 those values, you must stop upsmon and start it back up. upsmon will
399 warn you in the syslog if you make changes to either of those values
400 during a reload.
401
403 To test a synchronized shutdown without pulling the plug on your
404 UPS(es), you need only set the forced shutdown (FSD) flag on them. You
405 can do this by calling upsmon again to set the flag, i.e.:
406 upsmon -c fsd
408 After that, the primary and the secondary will do their usual shutdown
410 sequence as if the battery had gone critical, while you can time how
411 long it takes for them. This is much easier on your UPS equipment, and
412 it beats crawling under a desk to find the plug.
413 Note you can also use a dummy SHUTDOWNCMD setting to just report that
415 the systems would shut down at this point, without actually disrupting
416 their work.
417
419 upsmon.conf(5)
420
422 Server:
423 upsd(8)
424 Clients:
426 upsc(8), upscmd(8), upsrw(8), upsmon(8)
427 CGI programs:
429 upsset.cgi(8), upsstats.cgi(8), upsimage.cgi(8)
430 Internet resources:
432 The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
433Network UPS Tools 2.8.0 04/26/2022 UPSMON(8)